# @rgaa-dev/design

> The design system of RGAA Lab. One foundation for the web app, the browser extension's side panel and the public site.
> Read packages/design/README.md first, then this inventory, then the component folder you need: Name.svelte is the implementation, Name.md the contract, Name.stories.svelte one story per state, Name.test.ts what is guaranteed.

## Rules

- Tokens are the only source of colour, spacing, type and motion: tokens/*.json, generated by scripts/build.mjs. A literal colour anywhere else fails a test.
- Every documented colour pair is measured at generation and the build fails below its floor (tokens/contrast.json).
- One implementation per component, in Svelte 5, with scoped CSS on tokens and rl- classes; never a Tailwind utility inside a component.
- Colour never carries meaning alone: a status has its word, an icon its label, a disabled control its reason.
- English API and docs; French words for what a user reads. Status labels and symbols come from @rgaa-dev/core.
- Native elements first; every scrolling region focusable and named; a busy control keeps the focus; a live region exists from the first render.
- No em dash, in code, docs or generated files. Comments say why.

## Components

- BusyRegion (atom, stable; app): props busy, as?, class?, children; stories idle, busy, asSection. components/BusyRegion/
- Button (atom, stable; site, app, extension): props variant?, size?, fullWidth?, busy?, reason?, children; stories primary, secondary, ghost, destructive, inSentence, small, large, fullWidth, asLink, busy, disabled, withReason. components/Button/
- Checkbox (atom, stable; no surface yet): props id, label, name?, value?, checked?, hint?, error?, required?, disabled?; stories plain, checked, withHint, required, error, disabled. components/Checkbox/
- Chip (atom, stable; no surface yet): props tone?, icon?, class?, children; stories neutral, info, success, warning, error, withIcon. components/Chip/
- CodeBlock (atom, stable; app, site): props inline?, label?, children; stories inline, block, long. components/CodeBlock/
- DisabledReason (atom, stable; app, extension): props reason, layout?, class?, children; stories iconButton, stacked, group. components/DisabledReason/
- Eyebrow (atom, stable; site, app): props children; stories plain, long. components/Eyebrow/
- Figure (atom, stable; app): props src, alt, width?, height?, href?, caption?, code?, size?; stories evidence, opensLarge, natural. components/Figure/
- GlossaryTerm (atom, stable; extension): props term, open?, children; stories closed, open. components/GlossaryTerm/
- Heading (atom, stable; site, app): props level, size?, measure?, id?, class?, children; stories display, level2, levelWithoutSize, measured. components/Heading/
- Icon (atom, stable; site, app, extension): props name, size?, class?; stories small, medium, large, statuses, all. components/Icon/
- IconButton (atom, stable; no surface yet): props label, name, size?, variant?, pressed?; stories ghost, secondary, small, large, toggle, asLink, disabled. components/IconButton/
- InlineMarkup (atom, stable; site, extension): props text; stories plain, code, emphasis, mixed, codeKeepsMarkers. components/InlineMarkup/
- Kbd (atom, stable; no surface yet): props keys?, children?; stories single, combination, inSentence. components/Kbd/
- LevelBadge (atom, stable; no surface yet): props level, class?; stories a, aa, aaa, inRow. components/LevelBadge/
- Link (atom, stable; site, app, extension): props href, class?, children; stories plain, inSentence. components/Link/
- LiveRegion (atom, stable; no surface yet): props message?, tone?, visible?, class?; stories polite, assertive, hidden. components/LiveRegion/
- Logo (atom, stable; site, app, extension): props height?, markOnly?; stories header, small, large, markOnly. components/Logo/
- ProgressBar (atom, stable; extension): props id, label, value?, max?, showValue?, strip?, class?; stories measured, indeterminate, done, strip. components/ProgressBar/
- Prose (atom, stable; site, app): props size?, measure?, class?, children; stories base, small, large, narrow. components/Prose/
- ScrollRegion (atom, stable; site, app): props label?, labelledBy?, class?, framed?, children; stories labelled, framed, labelledBy. components/ScrollRegion/
- Select (atom, stable; no surface yet): props id, label, name?, value?, options?, groups?, placeholder?, hint?, error?, required?, disabled?; stories plain, chosen, grouped, required, error, disabled. components/Select/
- SkipLink (atom, stable; design, site, app): props href?, children?; stories plain, custom. components/SkipLink/
- StatusChip (atom, stable; site, app): props status, short?; stories c, nc, na, nt, short. components/StatusChip/
- Switch (atom, stable; no surface yet): props id, label, checked?, onchange?, hint?, disabled?; stories plain, on, withHint, disabled. components/Switch/
- Text (atom, stable; app, extension, site): props as?, size?, tone?, bold?, mono?, class?, children; stories plain, soft, tones, inline. components/Text/
- Tooltip (atom, stable; no surface yet): props text, children; stories inSentence, short. components/Tooltip/
- Accordion (molecule, stable; no surface yet): props items, level?, open?, exclusive?, class?, panel; stories independent, exclusive, preset. components/Accordion/
- Alert (molecule, stable; site, app): props tone?, title?, live?, class?, children; stories info, success, warning, error, titled, liveError, liveSuccess. components/Alert/
- AnswerButtons (molecule, stable; extension): props answers, value?, onanswer, labelledBy, class?; stories none, retained, three. components/AnswerButtons/
- AutoVerdict (molecule, stable; extension): props status, source?, findings?, onshow?, class?, children?; stories fromPage, fromEngine, ownSentence, fromAuditor. components/AutoVerdict/
- Banner (molecule, stable; no surface yet): props label, dismissKey, dismissLabel?, children; stories beta, maintenance. components/Banner/
- Breadcrumb (molecule, stable; no surface yet): props items, label?, class?; stories plain, deep. components/Breadcrumb/
- Callout (molecule, stable; site): props rule?, status?, aside?, class?, children; stories strong, subtle, aside, nc, c. components/Callout/
- Card (molecule, stable; site): props href?, listItem?, children; stories plain, link, inList. components/Card/
- CardGrid (molecule, stable; site): props columns?, list?, children; stories three, two, four, list. components/CardGrid/
- CommentField (molecule, stable; extension): props id, label, value?, placeholder?, optional?, hint?, rows?, class?; stories empty, filled, withHint. components/CommentField/
- ConfirmDialog (molecule, stable; no surface yet): props open?, title, confirmLabel, cancelLabel?, destructive?, onconfirm?, oncancel?, children; stories plain, destructive. components/ConfirmDialog/
- ConformityRate (molecule, stable; app): props rate, unavailableReason?, suffix?, decimals?; stories high, middle, low, average, unavailable, unavailableBare. components/ConformityRate/
- CriteriaRecap (molecule, stable; extension): props criteria, current?, reachable?, onjump?, label?, class?; stories plain, reachable. components/CriteriaRecap/
- DataTable (molecule, stable; site): props caption, captionHidden?, columns, rows, rowKey, cell?, empty?; stories plain, withCell, empty, captionHidden. components/DataTable/
- DefinitionList (molecule, stable; no surface yet): props items, columns?, class?, value?; stories plain, rendered, single. components/DefinitionList/
- Dialog (molecule, stable; no surface yet): props open?, title, size?, onclose?, closeLabel?, class?, children, actions?; stories question, form. components/Dialog/
- Disclosure (molecule, stable; no surface yet): props title, level?, open?, ontoggle?, class?, children; stories closed, open, level. components/Disclosure/
- EmptyState (molecule, stable; no surface yet): props title, level?, icon?, class?, children?, action?; stories withAction, search, withIcon. components/EmptyState/
- ErrorSummary (molecule, stable; no surface yet): props errors, title?, level?, class?; stories form. components/ErrorSummary/
- Field (molecule, stable; site, app): props id, label, type?, value?, name?, required?, hint?, error?, autocomplete?, placeholder?, multiline?, rows?, minlength?, maxlength?, inputmode?, autofocus?, code?, children?; stories text, email, required, withHint, error, multiline, code. components/Field/
- FilterGroup (molecule, stable; app): props label, filters, selected?, exclusive?, onchange?, class?; stories exclusive, several. components/FilterGroup/
- JumpList (molecule, stable; extension): props items, current, onjump, summary, open?, class?; stories closed, open. components/JumpList/
- Menu (molecule, stable; no surface yet): props label, items, onselect, children?, align?, class?; stories dots, labelled, withDisabled. components/Menu/
- OTPField (molecule, stable; app): props id, label?, value?, name?, length?, required?, hint?, error?, autofocus?; stories code, seven, error. components/OTPField/
- PageHeader (molecule, stable; no surface yet): props title, eyebrow?, lead?, level?, class?, actions?; stories plain, withAction, section. components/PageHeader/
- Pagination (molecule, stable; no surface yet): props page, pages, label, href, onnavigate?, total?, perPage?, rowsName?, class?; stories short, long, counted. components/Pagination/
- PasswordField (molecule, stable; app): props id, label, value?, name?, required?, hint?, error?, autocomplete?, minlength?, showLabel?; stories signIn, newPassword, error. components/PasswordField/
- Popover (molecule, stable; app, extension): props label, title?, open?, align?, variant?, class?, children; stories help, controls, end. components/Popover/
- PrevNext (molecule, stable; site, app, extension): props prev?, next?, label?, prevWord?, nextWord?, class?; stories both, first, last, buttons. components/PrevNext/
- PropositionList (molecule, stable; extension): props propositions, onaccept, ondismiss, onannounce?; stories mixed, single, none, hooked. components/PropositionList/
- Question (molecule, stable; extension): props criterion, id?, class?, children, help?; stories single, twoCriteria, withHelp. components/Question/
- RadioGroup (molecule, stable; no surface yet): props name, legend, options, value?, hint?, error?, required?, inline?; stories plain, chosen, inline, required, error. components/RadioGroup/
- ResumeBanner (molecule, stable; extension): props summary, alert?, note?, class?; stories resumed, alert. components/ResumeBanner/
- ReviewFlag (molecule, stable; extension): props label, answer?, differences?, onconfirm, class?; stories withDifferences, bare. components/ReviewFlag/
- SearchField (molecule, stable; no surface yet): props id, label, placeholder?, value?, name?, action?, buttonLabel?, onsearch?, clearHref?, clearLabel?; stories inPlace, withClear. components/SearchField/
- Stat (molecule, stable; site): props value, secondaryValue?, label, tone?, children?; stories plain, fraction, withSentence, toned. components/Stat/
- StatGroup (molecule, stable; no surface yet): props items, label, class?; stories audit, two. components/StatGroup/
- StatusBreakdown (molecule, stable; app): props counts, total, label, bar?; stories finished, inProgress, countsOnly. components/StatusBreakdown/
- StatusCounters (molecule, stable; extension): props counts, label?, class?; stories inProgress, finished. components/StatusCounters/
- StatusToggle (molecule, stable; extension): props criterionId, value?, onchange, statuses?, size?, hooks?, class?; stories untested, pressed, twoOnly, medium, hooked. components/StatusToggle/
- Table (molecule, stable; no surface yet): props caption, captionHidden?, variant?, fixed?, class?, children; stories plain, report, captionHidden. components/Table/
- Tabs (molecule, stable; no surface yet): props tabs, selected?, label, class?, panel; stories plain, preset. components/Tabs/
- ThemeSwitch (molecule, stable; site, app, extension): props name?, onchange?; stories plain, named. components/ThemeSwitch/
- Toast (molecule, stable; no surface yet): props messages, ondismiss?, fixed?, passthrough?, dismissLabel?; stories flow, tones, passthrough. components/Toast/
- WizardFooter (molecule, stable; extension): props last?, onprev?, onnext?, onfinish?, prevDisabled?, finishReason?, prevLabel?, nextLabel?, finishLabel?, class?, counters?; stories middle, first, last, blocked. components/WizardFooter/
- CriterionRow (organism, stable; extension): props id, title, status?, onstatus, comment?, oncomment?, engine?, action?, hooks?, class?, children?; stories untested, judged, engine, hooked. components/CriterionRow/
- DangerZone (organism, stable; app): props title, level?, actions, class?, children?; stories single, several, busy. components/DangerZone/
- Derogation (organism, stable; extension): props label, justification, id, onderogate, onremove, class?; stories closed, posed. components/Derogation/
- EvidenceBlock (organism, stable; extension): props criterionId, items, picking?, oncapture, onshow?, onpick?, oncancel?, hooks?, class?, shot?, show?; stories detected, complete, empty, picking, kept. components/EvidenceBlock/
- Onboarding (organism, stable; app): props title, level?, steps, doneWord?, dismissLabel?, ondismiss?, class?, children?, actions?, footer?; stories welcome, underWay, dismissible. components/Onboarding/
- PageSwitcher (organism, stable; extension): props open?, pages, currentId?, onswitch, ondelete?, addPath?, addNote?, onadd?, onclose?, title?; stories pages, single. components/PageSwitcher/
- Section (organism, stable; site): props rhythm?, rule?, class?, children; stories lead, plain, tight, ruled. components/Section/
- ThemeList (organism, stable; extension): props themes, open?, ontoggle?, onstatus, oncomment?, onwizard?, wizardReason?, busyTheme?, criterionAction?, hooks?, level?, class?, detail?; stories themes, offPage, collecting, hooked, partiel. components/ThemeList/
- WizardFrame (organism, stable; extension): props title, kind?, progress?, onclose?, closeLabel?, class?, tools?, above?, children, footer?; stories bare, withProgress, withFooter. components/WizardFrame/
- AppShell (view, stable; app): props home, sections, currentPath, collapsed?, oncollapse?, busy?, announcement?, email, logoutAction, logoutEnhance?, siteHref?, siteLabel?, navLabel?, themeName?, banner?, as?, children; stories open, rail, closed, busy, withBanner. components/AppShell/
- AuthShell (view, stable; app): props title, logoHref?, themeName?, width?, as?, headingLevel?, lead?, children, footer?; stories signIn, message. components/AuthShell/
- PanelShell (view, stable; extension): props label, as?, hidden?, id?, class?, banner?, header?, children, footer?; stories bare, full, underWizard. components/PanelShell/
- PrintPage (view, stable; app, design): props as?, labelledBy?, breakBefore?, keep?, class?, screen?, paper?, children; stories part, kept, plain. components/PrintPage/
- ReportDocument (view, stable; app): props title, subtitle?, coverEyebrow, coverTitle, coverLine?, coverItems, coverFootnote?, printHeader, printHeaderDetail?, plan, summaryExtras?, summaryLabel?, contentsLabel?, rights?, actions?, notice?, children; stories screen, withRights. components/ReportDocument/

## Adding one

Create components/Name/ with the four files, declare an interface Props with a JSDoc line per prop, one exported snippet per state in the stories file, a test that mounts every story, and the doc on the template of an existing one. Then: pnpm --filter @rgaa-dev/design build:tokens (regenerates this file and manifest.json), test.