Design system

Semantic tokens

Every colour in the app comes from one of these. Raw Tailwind palette classes do not exist here.

Family accents

The four type families. Each has a paired on-accent colour for text drawn on top of it.

Button

Every size carries a 44x44 touch target from `hitArea44` - a centred before: pseudo-element, never smaller than the control and never smaller than 44px, emitted only under `pointer-coarse` so a mouse never meets the overhang. Do NOT inflate a control to reach the rule; sm is 32px of ink and md is 40, and both already clear it. Reach for the same constant on any control smaller than 44px that is not a native input: ToggleChip, CopyableId, Pagination, Toggle and the theme buttons all use it. Leave 12px between two controls that both carry it, because on touch the overhang owns any gap narrower than itself. A checkbox or a radio is exempt because its label is part of its target, and the matches grid is exempt because 136 cells at 44px stops being a grid - it gets a complete keyboard path instead.

Form controls

Badge

Card

CardHeader renders an h2 by default, because a card is normally a top-level section of its page. A card nested inside another section passes level={3}. Both cards here are inside this Section's h2, so both use level={3}; on a real page you would leave the default.

Stat & Fact

The app's only two numeric treatments. Stat is a headline number, text-3xl, in its own card; Fact is a supporting value inside a dl, text-sm. Five pages used to invent their own, across four sizes and four label styles, so nothing on a dashboard read as more important than anything else by design. The single exception is the feedback average, the hero number of its page, which keeps text-4xl.

Alert

Reserve it for a condition with a state that can change. A permanent, unconditional, undismissable Alert - 'this log cannot be edited', 'nothing reads these yet' - trains an operator to scroll past the banner, and then they scroll past a real one. A fact that is true forever goes in the page description, the card lead, or a text-text-tertiary text-xs note beside the thing it describes.

Modal & dropdown

Shown both as a live trigger and as a static preview, so the panel is visible in a screenshot.

Destructive confirmation

No new component: Button variant=danger, Modal, Input with Field's error slot, Alert and Button loading already exist. What this documents is the mandatory COMPOSITION, because an irreversible action reassembled loosely at each call site is how the wrong account gets erased. The live implementation is admin/(guarded)/users/delete-account.tsx.

Spinner, skeleton & loading block

Skeleton is aria-hidden, which is right for a grey box and wrong for a page: on its own it makes a load completely silent. Every skeleton surface goes inside LoadingBlock, which adds role=status, aria-busy and an sr-only label from common.loading. Spinner already announces itself through its own label, and passes label={null} inside a control that has a name of its own.

Table

The row background lives on the tbody. Never put an opaque background on a Td: cells paint on top of their row, so a cell background hides the hover and the stripe however they are written - which is exactly why no table in this app showed a hover until it was fixed. The stripe and the hover are alpha tints (bg-text/3, bg-text/8) rather than surface tokens, because --surface and --surface-alt are the SAME colour in dark. A head row passes `head` so it gets neither. A numeric column pairs text-right WITH tabular-nums: monospaced digits that are still ragged-right do not line up, which is the whole point of tabular figures. `sort` names the order the rows are already in and sets aria-sort; it does not offer to change it.

Toggle chip & copyable id

ToggleChip is aria-pressed, not a checkbox: these narrow a set rather than answering a question, and sixteen checkboxes read as a form somebody has to complete. CopyableId is truncated on screen and whole on the clipboard, and it says so out loud both ways - a clipboard refusal needs a secure context and must never look like a success.

Tabs

Pagination

Segmented control and selectable stat

SegmentedControl picks one value out of a handful, all visible: a period, a bar width. A radio group, arrow keys move and select; a disabled option carries its reason as a tooltip. A Stat with onPress becomes a switch for what the page shows; the pressed one takes the primary border and ring.

Time chart

Counts over time, stacked bars or lines. Series take the fixed slots nt, sj, nf, sp (validated in that order for colour blindness in both themes), owned by the four most common values overall so a filter never repaints one; a fifth and beyond fold into Other, never a new hue. A family split passes each family's own tone. Two or more series always get a legend; hover or arrow keys open the per-period card.

Empty state

Two treatments, and which one applies is a question about the news, not the layout. EmptyState is for a surface that has nothing to show and needs somebody to act. The all-clear line is for a check that PASSED - 'every entity has all nine locales' is good news, and a dashed box saying it looks like something is missing.

Semantic tokens

Every colour in the app comes from one of these. Raw Tailwind palette classes do not exist here.

Family accents

The four type families. Each has a paired on-accent colour for text drawn on top of it.

Button

Every size carries a 44x44 touch target from `hitArea44` - a centred before: pseudo-element, never smaller than the control and never smaller than 44px, emitted only under `pointer-coarse` so a mouse never meets the overhang. Do NOT inflate a control to reach the rule; sm is 32px of ink and md is 40, and both already clear it. Reach for the same constant on any control smaller than 44px that is not a native input: ToggleChip, CopyableId, Pagination, Toggle and the theme buttons all use it. Leave 12px between two controls that both carry it, because on touch the overhang owns any gap narrower than itself. A checkbox or a radio is exempt because its label is part of its target, and the matches grid is exempt because 136 cells at 44px stops being a grid - it gets a complete keyboard path instead.

Form controls

Badge

Card

CardHeader renders an h2 by default, because a card is normally a top-level section of its page. A card nested inside another section passes level={3}. Both cards here are inside this Section's h2, so both use level={3}; on a real page you would leave the default.

Stat & Fact

The app's only two numeric treatments. Stat is a headline number, text-3xl, in its own card; Fact is a supporting value inside a dl, text-sm. Five pages used to invent their own, across four sizes and four label styles, so nothing on a dashboard read as more important than anything else by design. The single exception is the feedback average, the hero number of its page, which keeps text-4xl.

Alert

Reserve it for a condition with a state that can change. A permanent, unconditional, undismissable Alert - 'this log cannot be edited', 'nothing reads these yet' - trains an operator to scroll past the banner, and then they scroll past a real one. A fact that is true forever goes in the page description, the card lead, or a text-text-tertiary text-xs note beside the thing it describes.

Modal & dropdown

Shown both as a live trigger and as a static preview, so the panel is visible in a screenshot.

Destructive confirmation

No new component: Button variant=danger, Modal, Input with Field's error slot, Alert and Button loading already exist. What this documents is the mandatory COMPOSITION, because an irreversible action reassembled loosely at each call site is how the wrong account gets erased. The live implementation is admin/(guarded)/users/delete-account.tsx.

Spinner, skeleton & loading block

Skeleton is aria-hidden, which is right for a grey box and wrong for a page: on its own it makes a load completely silent. Every skeleton surface goes inside LoadingBlock, which adds role=status, aria-busy and an sr-only label from common.loading. Spinner already announces itself through its own label, and passes label={null} inside a control that has a name of its own.

Table

The row background lives on the tbody. Never put an opaque background on a Td: cells paint on top of their row, so a cell background hides the hover and the stripe however they are written - which is exactly why no table in this app showed a hover until it was fixed. The stripe and the hover are alpha tints (bg-text/3, bg-text/8) rather than surface tokens, because --surface and --surface-alt are the SAME colour in dark. A head row passes `head` so it gets neither. A numeric column pairs text-right WITH tabular-nums: monospaced digits that are still ragged-right do not line up, which is the whole point of tabular figures. `sort` names the order the rows are already in and sets aria-sort; it does not offer to change it.

Toggle chip & copyable id

ToggleChip is aria-pressed, not a checkbox: these narrow a set rather than answering a question, and sixteen checkboxes read as a form somebody has to complete. CopyableId is truncated on screen and whole on the clipboard, and it says so out loud both ways - a clipboard refusal needs a secure context and must never look like a success.

Tabs

Pagination

Segmented control and selectable stat

SegmentedControl picks one value out of a handful, all visible: a period, a bar width. A radio group, arrow keys move and select; a disabled option carries its reason as a tooltip. A Stat with onPress becomes a switch for what the page shows; the pressed one takes the primary border and ring.

Time chart

Counts over time, stacked bars or lines. Series take the fixed slots nt, sj, nf, sp (validated in that order for colour blindness in both themes), owned by the four most common values overall so a filter never repaints one; a fifth and beyond fold into Other, never a new hue. A family split passes each family's own tone. Two or more series always get a legend; hover or arrow keys open the per-period card.

Empty state

Two treatments, and which one applies is a question about the news, not the layout. EmptyState is for a surface that has nothing to show and needs somebody to act. The all-clear line is for a check that PASSED - 'every entity has all nine locales' is good news, and a dashed box saying it looks like something is missing.