Theming

WARNING

The token vocabulary below is a working placeholder. Naming and scales are an open item in the repository README's TO DISCUSS section, and are expected to change once the team settles the design language. Treat the mechanism as stable and the values as provisional.

How it works

Two layers, deliberately:

1. Raw values — --hab-* custom properties defined on :root and re-pointed under .dark. These are the actual colours and sizes.
2. Tailwind namespaces — a @theme inline block mapping those into --color-*, --spacing-* and --radius-* so they generate utilities (bg-surface, text-fg-muted, rounded-hab).

The inline keyword is load-bearing. Without it Tailwind copies the value at build time and the .dark override would never take effect.

Overriding tokens

Override the raw --hab-* properties; everything derived follows. No build step, no Tailwind config:

:root {
	--hab-brand-600: oklch(0.55 0.2 150);
	--hab-radius-hab: 2px;
}

.dark {
	--hab-surface: oklch(0.18 0.01 280);
}

Do this after importing the Habitus stylesheet.

Token groups

Semantic surfaces and foregrounds

Prefer these over the brand ramp — they are what adapt between light and dark.

Token	Utility	Use for
--hab-surface	bg-surface	Default page/panel background
--hab-surface-raised	bg-surface-raised	Cards, popovers, anything above the page
--hab-surface-sunken	bg-surface-sunken	Wells, hover states on neutral surfaces
--hab-fg	text-fg	Primary text
--hab-fg-muted	text-fg-muted	Secondary text, captions
--hab-fg-on-brand	text-fg-on-brand	Text on a brand-filled surface
--hab-border	border-border-default	Dividers and control borders

Brand ramp

--hab-brand-50 through --hab-brand-950, as bg-brand-600, text-brand-700 and so on. Use for deliberate brand emphasis; reach for the semantic tokens for everything structural.

Status

--hab-danger, --hab-warning, --hab-success, --hab-info.

Control sizing

--spacing-control-sm|md|lg (h-control-md) give every interactive component a shared height scale, so a button and an input of the same size line up. Any new control should use these rather than inventing its own padding.

Radius

--radius-hab (rounded-hab) is the single corner radius. One value, applied consistently, is most of what makes a component set look intentional.

Rules

• Never hard-code a colour or spacing value in a component. If no token fits, the token set is missing something — add it and say so in review.
• Prefer semantic over literal. bg-surface-raised survives a theme change; bg-white does not.
• Adding a token is a design decision, not an implementation detail. Open a design-change issue so the blast radius across apps gets considered.