@arbor-education/design-system.components 0.13.0 → 0.14.0

package/.agent-memory/blanche-designspert/MEMORY.md

@@ -0,0 +1,189 @@
+# Blanche Designspert - Persistent Memory
+
+## Key File Locations
+- Design tokens: `src/tokens.scss` (CSS custom properties, NOT Sass vars - globally available, never import)
+- Component public API: `src/index.ts`
+- Styles entry: `src/index.scss`
+- `src/pages/` does NOT exist on the current branch (confirmed 2026-04-17) — was on a prior branch
+
+## Token Conventions (confirmed from src/tokens.scss)
+- Spacing tokens: `--spacing-xsmall` (0.25rem), `--spacing-small` (0.5rem), `--spacing-medium` (0.75rem), `--spacing-large` (1rem), `--spacing-xlarge` (1.5rem), `--spacing-xxlarge` (2rem), `--spacing-xxxlarge` (4rem)
+- Grey scale: `--color-grey-050` through `--color-grey-900` (050, 100, 200, 300, 400, 500, 600, 700, 800, 900)
+- Mono: `--color-mono-black` (#202020), `--color-mono-white` (#ffffff)
+- Font sizes: `--font-size-1-11` through `--font-size-8-40` (no `--font-size-5-18` listed on line 9-16 but IS defined at line 16)
+- Font weights: `--font-weight-regular`, `--font-weight-medium`, `--font-weight-semi-bold`, `--font-weight-bold`
+- Border radius: `--border-radius-xsmall` (4px), `--border-radius-small` (8px), `--border-radius-large` (16px), `--border-radius-round` (99px)
+- Line heights: `--line-height-tight` (1.25), `--line-height-default` (1.5)
+
+## Semantic / Component Tokens (use over base tokens)
+- Hyperlink color: `--type-body-hyperlink-color` (maps to `--color-brand-700`) - use for link text
+- Hyperlink weight: `--type-body-hyperlink-weight` (maps to `--font-weight-medium`)
+- Body text size: `--type-body-p-size` (maps to `--font-size-2-13`)
+- Page background: `--page-color-background` (maps to `--color-grey-050`)
+- Page border: `--page-base-color-border` (maps to `--color-grey-050`)
+- Page heading text: `--page-heading-color-text` (maps to `--color-mono-black`)
+- Page heading gap: `--page-heading-spacing-gap` (maps to `--spacing-small`)
+- Default icon color: `--icons-icon-default` (maps to `--color-grey-900`)
+- Focus color: `--focus-color-focus` (maps to `--color-brand-500`)
+
+## CSS Naming Conventions
+- Prefix: `ds-` (all design system classes)
+- BEM: `ds-{block}`, `ds-{block}__{element}`, `ds-{block}--{modifier}`
+- SCSS file: camelCase matching directory name (e.g. `assessmentsPage.scss`)
+- Use `classnames` library for conditional classes
+
+## Typography Color Patterns (for body text in pages)
+- Primary / heading text: `--color-grey-900` or `--color-mono-black`
+- Secondary / supporting text: `--color-grey-600` or `--color-grey-500`
+- Muted / disabled: `--color-grey-400`
+- Links: use breadcrumb component tokens when in breadcrumbs (NOT raw `--type-body-hyperlink-color` or `--color-grey-600`)
+- Current breadcrumb text: `--breadcrumbs-breadcrumb-link-active-color-text` (maps to `--color-grey-900`)
+
+## Breadcrumb Component Tokens (tokens exist — line numbers may drift as tokens.scss grows)
+- List gap: `--breadcrumbs-spacing-gap-horizontal` (maps to `--spacing-small`)
+- Divider color: `--breadcrumbs-divider-default-color` (maps to `--color-grey-600`)
+- Link default color: `--breadcrumbs-breadcrumb-link-default-color-text` (maps to `--color-grey-600`)
+- Link hover color: `--breadcrumbs-breadcrumb-link-hover-color-text` (maps to `--color-brand-600`)
+- Link active/current color: `--breadcrumbs-breadcrumb-link-active-color-text` (maps to `--color-grey-900`)
+- Link hover icon color: `--breadcrumbs-breadcrumb-link-hover-color-icon` (maps to `--color-brand-600`)
+- Link default icon color: `--breadcrumbs-breadcrumb-link-default-color-icon` (maps to `--color-grey-600`)
+- No breadcrumb-specific font-weight token exists; use `--type-body-hyperlink-weight` for link weight
+
+## Design Token Hierarchy to Enforce
+1. Component tokens (e.g. `--breadcrumbs-breadcrumb-link-default-color-text`) - most specific, prefer always
+2. Semantic tokens (e.g. `--type-body-hyperlink-color`, `--page-color-background`)
+3. Base tokens (e.g. `--color-grey-600`) - only if no semantic equivalent
+
+## Button Component Tokens (confirmed from src/tokens.scss + src/components/button/button.scss)
+- Spacing pattern: `--button-{size}-spacing-vertical`, `--button-{size}-spacing-horizontal`, `--button-{size}-spacing-gap-vertical` where size = `medium` or `small`
+- Height: `--size-medium` (2.25rem), `--size-small` (2rem) — these are the actual height tokens used
+- Radius: `--button-medium-radius` / `--button-small-radius` (both map to `--border-radius-round`)
+- Color pattern: `--button-{size}-{variant}-{state}-color-{role}` — e.g. `--button-medium-primary-default-color-background`
+- Focus ring: `--focus-border` (3px) + `--button-{size}-{variant}-focus-color-focus` (most map to `--focus-color-focus` = `--color-brand-500`)
+- Error border: `--color-semantic-destructive-500` (applied as `ds-button--error` modifier class)
+- Disabled: CSS `opacity: 0.5` + `cursor: not-allowed` + `pointer-events: none` — no dedicated token
+- Dropdown variant: uses raw base tokens (`--color-grey-200`, `--color-grey-500`, `--color-grey-900`, `--color-brand-500`) NOT component tokens — this is a known inconsistency in the SCSS
+- `ds-text` class: NOT a formal design system class. It is used in story wrappers (e.g. Dropdown.stories.tsx) to apply standard `ds-` font-family/size via the global selector `*[class^='ds-']`. Use `className="ds-text"` on `<p>` or `<span>` wrapper elements in stories only.
+- Story wrapper convention: `padding: 'var(--spacing-xlarge)'`, `gap: 'var(--spacing-large)'`, label text color `'var(--color-grey-600)'`, `className="ds-text"` for text labels
+- Tertiary variant bug: `button.scss` uses `--button-small-tertiary-*` tokens for the tertiary variant regardless of size (not `--button-medium-tertiary-*`). No medium tertiary tokens in tokens.scss for tertiary — small tokens are used for both sizes.
+
+## Banner Component Tokens (confirmed from src/tokens.scss lines 452–470 + banner.scss)
+- Spacing: `--banner-spacing-gap`, `--banner-spacing-vertical`, `--banner-spacing-horizontal` (all resolve to `--spacing-large` / 1rem)
+- Radius: `--banner-radius` (resolves to `--border-radius-small` / 8px)
+- Color pattern: `--banner-{level}-color-{role}` where level = `info|neutral|warning|destructive` and role = `icon|text|border|background`
+- Neutral level has NO `--banner-neutral-color-background` token — transparent bg is intentional
+- Each level wraps semantic tokens: info/warning/destructive use `--color-semantic-{level}-050/500/800` pattern
+- Neutral uses `--color-grey-400` (border) and `--color-grey-900` (icon + text)
+- Inner `__central-container` gap uses `--spacing-small` — internal implementation detail, do not expose to consumers
+
+## Banner Story Conventions
+- AllVariants gap between stacked banners: `--spacing-xxlarge` (2rem) — gives enough breathing room over internal `--spacing-large` padding
+- Neutral variant needs a visible backdrop in stories: `background: 'var(--color-grey-050)'` with `borderRadius: 'var(--border-radius-small)'` and `padding: 'var(--spacing-medium)'`
+- AllVariants disclaimer label wording: "Storybook overview only — the design spec prohibits more than one banner per surface. Never render multiple banners simultaneously in a real page."
+- Banner anti-patterns: hardcoded colours (use level prop), success messages (use Toast), stacking (one per surface), full-sentence titles (use short noun phrases)
+
+## Icon Component Conventions (confirmed from src/components/icon/ + src/tokens.scss)
+- Size tokens: `--icon-size-xsmall` (12px), `--icon-size-small` (16px), `--icon-size-medium` (24px) — exist but NOT used by Icon component itself. Used in SCSS of consuming components (e.g. checkboxInput.scss, numberInput.scss) to size containers that wrap icons.
+- Icon component takes numeric prop `size?: 12 | 16 | 24` (type `IconSize`) — TypeScript enforces it, no runtime token lookup
+- Default color is `'currentColor'` — always inherits from parent CSS `color` property
+- Only 3 allowed sizes: 12 (dense UI only), 16 (default), 24 (high-significance contexts)
+- Icon gallery cell convention: `minmax(7rem, 1fr)` for auto-fill grid, `gap: var(--spacing-small)`, cell `padding: var(--spacing-medium)`, label `font-size: var(--font-size-1-11)` + `color: var(--color-grey-600)`
+- Icon+label tight gap: `--spacing-xsmall` (0.25rem) when icon and label are a fused unit; `--spacing-small` (0.5rem) when adjacent but distinct
+- Semantic icon colours to use at -600 shade: `--color-semantic-info-600`, `--color-semantic-success-600`, `--color-semantic-warning-600`, `--color-semantic-destructive-600` — all confirmed present
+- CurrentColor inheritance swatches for stories: `--color-grey-900` (default/`--icons-icon-default`), `--color-brand-700` (interactive/link), `--color-semantic-destructive-600` (severity), `--color-grey-400` (muted/disabled)
+- Solid icons (`check-solid`, `x-solid`, `favourite-filled`) must not be mixed with outline Lucide icons in flowing content — reserved for specific state indicators
+- `aria-hidden` always applied by component; `screenReaderText` prop renders `sr-only` span — icon-only interactive elements MUST pass `screenReaderText`
+- `--icons-icon-default` token resolves to `--color-grey-900` (line 355, tokens.scss)
+
+## Pill Component Tokens (confirmed from src/tokens.scss lines 268–301 + 1346–1349)
+- Spacing: `--pill-spacing-vertical` (xsmall), `--pill-spacing-horizontal` (small), `--pill-spacing-gap-horizontal` (small), radius: `--pill-radius` (round)
+- Toggle mode: `--pill-single-filter-{default|hover|active|selected}-color-{background|border|text}`
+  - default: white bg, grey-100 border; active: grey-100 bg, grey-500 border; all text grey-900
+- Checkbox mode: `--pill-checkbox-{default|hover|selected}-color-{background|border|text|icon}`
+  - default: white bg, grey-100 border; selected: brand-050 bg, brand-600 border, brand-800 text
+- Focus: `--pill-{checkbox|single-filter}-{default|selected}-focus` all resolve to `--focus-color-focus`
+- CSS classes: `ds-pill__inactive`/`ds-pill__active` (toggle), `ds-pill__unchecked`/`ds-pill__checked` (checkbox)
+- Known a11y limitation: renders `<span onClick>` — not keyboard accessible (no tabIndex, role, or onKeyDown)
+- "All" reset: normal `<Pill text="All">` at position 0, no special props — just stateful management in parent
+- Filter group layout: `flexWrap: wrap`, `gap: var(--spacing-small)`, NEVER horizontal scroll (Confluence rule)
+
+## FormField Component Tokens (confirmed from src/tokens.scss lines 1034–1151)
+- Spacing: `--form-field-spacing-vertical` (small/0.5rem), `--form-field-spacing-horizontal` (small/0.5rem), `--form-field-spacing-vertical-gap` (xsmall/0.25rem), `--form-field-spacing-padding-x/left/right`
+- Sizing: `--form-field-text-small-height` (2rem), `--form-field-text-medium-height` (2.25rem), `--form-field-radius` (border-radius-small/8px)
+- Label: `--form-field-label-color-text` (grey-900), `--form-field-label-color-icon` (grey-900)
+- Description: `--form-field-color-label-description-text` (grey-600) — also aliased as `--form-field-help-text-color-label-description-text`
+- Input text state pattern: `--form-field-text-{state}-color-{role}` (state: default/hover/focus/active/error/disabled/uneditable/placeholder; role: text/border/background)
+- Error message: `--form-field-text-error-color-error-text` (grey-600), `--form-field-text-error-color-error-icon` (semantic-destructive-500)
+- Help text link default: `--form-field-help-text-default-color-text` (brand-600), `--form-field-help-text-default-color-icon` (brand-600)
+- Help text link hover: `--form-field-help-text-hover-color-text` (brand-800), `--form-field-help-text-hover-color-icon` (brand-800)
+- Combobox has a full parallel set: `--form-field-combobox-*` — same state pattern
+- Textarea has a full parallel set: `--form-field-textarea-*` — same state pattern
+- Story wrapper: `maxWidth: '28rem'`, `padding: 'var(--spacing-xlarge)'`; stacked field gap: `--spacing-large`; section group gap: `--spacing-xxlarge`
+
+## TextArea-Specific Story Conventions
+- `--form-field-textarea-*` component tokens exist (lines 1116–1139) and mirror the `--form-field-text-*` pattern exactly — always prefer these over base tokens in TextArea stories
+- There is NO dedicated textarea character-count token. Use `--color-grey-600` (normal count), `--color-semantic-caution-600` (approaching limit), `--color-semantic-destructive-600` (at/over limit)
+- There is NO `--form-field-textarea-min-height` token — component uses `scrollHeight` math in JS. No CSS min-height convention is codified.
+- Default `rows` for stories: 3 (matches Figma spec density for multi-line fields)
+- Story wrapper: same as FormField — `maxWidth: '28rem'`, `padding: 'var(--spacing-xlarge)'`; stacked story gap `--spacing-large`; character count label/count row gap `--spacing-xsmall`
+- `autoSize` resize uses `scrollHeight + 4px` vertical padding hardcoded in component (not a token — implementation detail)
+- Focus outline in input.scss line 22 uses `--button-medium-primary-focus-color-focus` — this is a known cross-token leak (not a textarea-specific token). Do NOT surface this as intended to story readers; just use `--focus-border` + `--focus-color-focus` when describing focus behaviour in prose.
+
+## CheckboxInput Component Tokens (confirmed from src/tokens.scss lines 965–995 + 1378–1382 + checkboxInput.scss)
+- Control size: `--icon-size-small` (16px) — fixed, one size only, no size variants
+- Internal horizontal gap (control to label): `--checkbox-spacing-gap-horizontal` → `--spacing-small` (8px)
+- Focus outline (row with label): `--checkbox-radius` → `--border-radius-small` (8px)
+- Focus outline (control only, no label): `--checkbox-input-control-radius` → `--border-radius-xsmall` (4px)
+- Control radius: `--checkbox-input-control-radius` → `--border-radius-xsmall` (4px)
+- Border is a box-shadow (`inset 0 0 0 [weight] [color]`), NOT a CSS border — overriding `border` CSS has no effect
+- Border weight: `--checkbox-input-control-unchecked-weight-border` → `--border-weight` (global token)
+- Unchecked background: `--checkbox-input-control-unchecked-default-color-background` → `--color-mono-white` (NOT transparent)
+- Checked bg: `--checkbox-input-control-checked-default-color-background` → `--color-brand-600`
+- Indeterminate bg: `--checkbox-input-control-indeterminate-default-color-background` → `--color-brand-600`
+- Disabled (any state) bg: all resolve to `--color-grey-400`
+- Icon color applied inline via JSX `color` prop (not CSS) — cannot override with CSS targeting `.ds-checkbox-input__icon`
+- Label text: `--checkbox-default-color-text` → `--color-grey-900`; hover: `--checkbox-hover-color-text` → `--color-grey-900`
+- Disabled label tokens: `--checkbox-default-disabled-color-text` + `--checkbox-selected-disabled-color-text` → `--color-grey-600` — exist in tokens.scss but NOT applied in checkboxInput.scss (known implementation gap)
+- Focus tokens: `--checkbox-default-focus` + `--checkbox-selected-focus` → `--focus-color-focus`; NOTE: SCSS uses `var(--color-brand-500)` directly (cross-token inconsistency — do not surface as intentional)
+- `--checkbox-group-spacing-gap-horizontal` exists in tokens.scss but is NOT used in any SCSS — reserved token, do not reference as active
+- `--checkbox-spacing-padding` → `--spacing-small` — exists but not applied in component SCSS
+
+## CheckboxGroup / Fieldset Tokens
+- Fieldset uses `--checkbox-or-radio-button-group-spacing-gap-vertical` → `--spacing-medium` (12px) for gap between items
+- Fieldset legend: `--type-body-bold-weight` + `--form-field-label-color-text` (grey-900) + `margin-bottom: --form-field-spacing-vertical`
+- CheckboxGroup passes `options` array of `CheckboxInputProps` — `id` field is required per `key` usage
+- `legend` prop is technically optional in TypeScript but required for accessibility (a11y rule: always pass it)
+
+## CheckboxInput Story Wrapper Conventions
+- Outer container: `padding: 'var(--spacing-xlarge)'`, `maxWidth: '28rem'` (matches FormField convention)
+- AllStates vertical list gap: `--spacing-medium` (12px) — NOT `--spacing-small` (too tight vs focus outline bleed)
+- Section heading (quiet): `font-size: var(--font-size-2-13)`, `color: var(--color-grey-600)`, `font-weight: var(--font-weight-regular)`
+- Section heading (prominent): `font-size: var(--font-size-3-14)`, `color: var(--color-grey-900)`, `font-weight: var(--font-weight-semi-bold)`
+
+## RadioButtonInput Component Tokens (confirmed from src/tokens.scss lines 1324–1344 + radioButtonInput.scss)
+- Shared token namespace: `--checkbox-or-radio-button-group-*` — tokens are shared between CheckboxInput and RadioButtonInput
+- Horizontal gap (indicator to label): `--checkbox-or-radio-button-group-spacing-gap-horizontal` → `--spacing-small` (8px)
+- Vertical gap between items in Fieldset: `--checkbox-or-radio-button-group-spacing-gap-vertical` → `--spacing-medium` (12px) — built into Fieldset SCSS, do NOT add a wrapper gap
+- Focus ring radius: `--checkbox-radius` → `--border-radius-small` (8px) — same token as CheckboxInput
+- Focus ring color: hardcoded `var(--color-brand-500)` in SCSS (NOT using `--focus-color-focus` token — known inconsistency, do not surface as intentional)
+- Label text: `--checkbox-default-color-text` → `--color-grey-900`
+- Disabled label text: `--checkbox-or-radio-button-group-disabled-color-text` → `--color-grey-600`
+- Default indicator: border `--checkbox-or-radio-button-group-default-color-border` (grey-500), bg `--checkbox-or-radio-button-group-default-color-background` (white)
+- Selected indicator: border `--checkbox-or-radio-button-group-selected-color-border` (brand-600), bg `--checkbox-or-radio-button-group-selected-color-background` (white), dot `--checkbox-or-radio-button-group-selected-color-check` (brand-600)
+- Disabled indicator: border `--checkbox-or-radio-button-group-disabled-color-border` (grey-500), bg `--checkbox-or-radio-button-group-disabled-color-background` (grey-100), dot `--checkbox-or-radio-button-group-disabled-color-check` (grey-500)
+- Hover (unselected): border grey-900, bg white — `--checkbox-or-radio-button-group-hover-color-border/background`
+- Hover (selected): border brand-800, bg white, dot brand-800 — `--checkbox-or-radio-button-group-selected-hover-color-border/background/check`
+- CRITICAL: `hasError` prop ONLY sets `aria-invalid` on the `<input>`. There are ZERO radio-specific error visual tokens in tokens.scss and ZERO error CSS rules in radioButtonInput.scss. The indicator does NOT change colour on error. Error state is semantic only (ARIA). Consumers must render their own error message below the group.
+- Error message text in stories: use `--form-field-text-error-color-error-text` (grey-600) for message text, `--form-field-text-error-color-error-icon` (semantic-destructive-500) for any error icon alongside it
+- Story wrapper: `maxWidth: '28rem'`, `padding: 'var(--spacing-xlarge)'` — matches CheckboxInput and FormField conventions
+- AllStates vertical list gap: `--spacing-medium` — same as CheckboxInput (focus ring bleed concern)
+- RadioButtonGroup: uses Fieldset internally — do NOT wrap RadioButtonGroup in a gap container; Fieldset already applies `--checkbox-or-radio-button-group-spacing-gap-vertical` as its internal flex gap
+
+## Known Issues / Patterns
+- Breadcrumb implementations commonly use `--color-grey-600` or `--type-body-hyperlink-color` when dedicated `--breadcrumbs-*` component tokens exist and should be used instead
+- Breadcrumb hover state commonly missing color change; `--breadcrumbs-breadcrumb-link-hover-color-text` should be applied on hover alongside text-decoration
+- `--type-body-bold-weight` DOES exist in tokens.scss (maps to `--font-weight-semi-bold`). It IS a valid semantic token. Use it for bold body text emphasis instead of reaching for the base token directly.
+- Also note: `--hyperlink-default`, `--hyperlink-hover`, `--hyperlink-active` are component tokens for hyperlinks. These are the most specific link tokens and should be used in preference to `--type-body-hyperlink-color` for actual inline hyperlinks.
+- `src/examples/` does NOT exist on the current branch (confirmed 2026-04-17) — was on a prior branch
+- No `@use` import needed for tokens.scss in SCSS files - tokens are CSS custom properties, globally available
+- Do NOT use breadcrumb component tokens (e.g. `--breadcrumbs-breadcrumb-link-default-color-text`) for non-breadcrumb elements like table row counts. Use `--color-grey-600` for secondary/supporting body text when no semantic token exists.

package/.agent-memory/dorothy-fact-checker/MEMORY.md

@@ -0,0 +1,228 @@
+# Dorothy Fact-Checker Memory
+
+## Agent File Locations
+- Agent definitions (all four): `.claude/agents/{blanche-designspert,dorothy-fact-checker,rose-storybookspert,sophia-componentspert}.md`
+- Agent memory directories: `.claude/agent-memory/{agent-name}/`
+- These files use relative paths (from project root) for portability across developer machines
+- Frontmatter `name` field must match the filename (without .md extension)
+
+## The Golden Girls Team
+- blanche-designspert: model sonnet, color purple, design tokens & styling
+- dorothy-fact-checker: model opus, color blue, QA & fact-checking
+- rose-storybookspert: model sonnet, color pink, Storybook stories
+- sophia-componentspert: model sonnet, color gold, component guidance
+- Emojis: blanche=lipstick, dorothy=magnifying glass, rose=rose, sophia=purse
+
+## Create-Page Skill Integration
+- Skill at `.claude/skills/create-page/SKILL.md` calls agents at steps 3/4 (Sophia), 6 (Blanche), 8 (Rose), 10 (Dorothy)
+- Agent names in backtick code refs are what matter for resolution, not the heading text
+
+## Verification Patterns
+- When checking agent file changes, compare against what was loaded into the system prompt (which reflects the pre-change state) since these files may be untracked and have no git history to diff against
+- The Grep tool and memory system resolve relative paths against the project working directory
+- Claude Code injects absolute paths at runtime even when files use relative paths -- this is expected behavior
+
+## Common Issues to Watch For
+- Absolute paths leaking into config files (especially `/Users/{username}/...` patterns)
+- Files claimed to be committed but actually untracked (check `git ls-files` and `git status`)
+- Agent memory directories may be empty (no MEMORY.md) until agents run for the first time -- this is by design
+
+## Project Structure Notes
+- `src/pages/` is a new directory added for page-level components (not in original architecture)
+- No `Pages/*` path alias exists in tsconfig.json -- only `Components/*` and `Utils/*`
+- Therefore page exports in `src/index.ts` must use relative paths (`./pages/...`) not aliases
+- ESLint catches stylistic issues that `check-types` and `style-lint` do not -- always run all three
+
+## Tag vs Badge Prop Spelling (confirmed 2026-04-17)
+- Tag uses `color` (American spelling): `color?: TagColor` (Tag.tsx line 15)
+- Badge uses `colour` (British spelling): `colour?: BadgeColour` (Badge.tsx line 12)
+- TagColor includes a `'neutral'` option that BadgeColour/DotColour does NOT have
+- Rose frequently conflates the two in BAD/GOOD doc snippets — always check spelling in prose code examples
+
+## Phantom Token Names (common Rose/Blanche hallucinations, verified 2026-04-17)
+These tokens DO NOT EXIST in src/tokens.scss — flag them in any story wrapper inline styles:
+- `--color-grey-50` (smallest grey is `--color-grey-100`) — confirmed AGAIN 2026-04-17 in Icon.stories.tsx line 830 gallery cell `background: 'var(--color-grey-50)'`. Recurring Rose hallucination.
+- CRITICAL DISTINCTION: `--color-grey-050` (THREE digits, leading zero) IS VALID — declared at tokens.scss:39 as `#f8f8f8`. Dorothy has wrongly flagged this as phantom — always verify the exact spelling (`-50` vs `-050`) before flagging. Both are real-looking; only the 3-digit `-050` variant actually exists.
+- `--font-size-small` (actual scale: `--font-size-1-11`, `--font-size-2-13`, `--font-size-3-14`, `--font-size-4-16`, `--font-size-5-18`, `--font-size-6-22`, `--font-size-7-27`, `--font-size-8-40`)
+- `--border-radius-medium` (actual: `--border-radius-xsmall` 4px, `--border-radius-small` 8px, `--border-radius-large` 16px, `--border-radius-round` 99px) — confirmed AGAIN 2026-04-17 in Heading.stories.tsx:362 wrapper style `borderRadius: 'var(--border-radius-medium)'`. Recurring Rose hallucination — the "medium" tier does NOT exist between small (8px) and large (16px). Fix is always `--border-radius-small`.
+- `--color-semantic-info-200` does NOT exist (scale is 050, 100, 300, 500, 600, 700, 800, 900 — no 200 tier). Confirmed 2026-04-22 in Separator.stories.tsx:585.
+- `--color-semantic-warning-200` does NOT exist either (same scale gaps).
+When fact-checking stories, always verify every `var(--X)` reference against tokens.scss — the CSS won't throw on phantom names but demos will render with fallback defaults
+
+## Banner Component Quirk (verified 2026-04-17)
+- `banner.scss:44` references `var(--banner-neutral-color-background)` but this token is NOT declared in tokens.scss
+- tokens.scss lines 457-459 only declare `--banner-neutral-color-{icon,text,border}` — NO background
+- The CSS falls back to `transparent` (CSS spec behaviour for unresolved custom property on background-color) — so it renders correctly by accident
+- If a story description claims "Neutral variant intentionally has no background token by design", flag that it's actually an undeclared reference that happens to fall back to transparent
+- The four declared banner layout tokens are `--banner-radius`, `--banner-spacing-gap`, `--banner-spacing-vertical`, `--banner-spacing-horizontal` (all verified)
+- Banner source at Banner.tsx has NO role attribute on root div — so "does not set role='alert'" claims are accurate
+
+## Storybook Link Slug Verification Pattern (confirmed 2026-04-17)
+- Always verify the actual `title:` in the target story file (not infer from component name)
+- For Toast: `Components/Toast` → `components-toast--docs` ✓
+- For Modal: `Components/Modals/Modal` → `components-modals-modal--docs` ✓ (note the `s` in Modals — this is a common hallucination trap)
+- For Button: `Components/Button` → `components-button--docs` ✓
+- For Icon: `Components/Icon` → `components-icon--docs` ✓
+- For Banner: `Components/Banner` → `components-banner--docs` ✓
+- For Badge: `Components/Badge` → `components-badge--docs` ✓
+- For Separator: `Components/Separator` → `components-separator--docs` ✓
+- For Dropdown: `Components/Dropdown` → `components-dropdown--docs` ✓
+- For Section: `Components/Section` → `components-section--docs` ✓
+
+## Progress Component (verified 2026-04-17) — see [progress_component.md](progress_component.md)
+- Radix default `getValueLabel` returns `"X%"` (percentage string), NOT raw number. Agents frequently mischaracterise this (Rose wrote "raw number" in 5 places in Progress.stories.tsx).
+- `value={null}` produces an INVISIBLE bar in this wrapper (Number(null)=0, translateX(-100%), no indeterminate CSS animation defined)
+- Radix auto-sets `role="progressbar"`, `aria-valuemax/min/now`, and `aria-valuetext` from `getValueLabel`
+- Radix silently coerces out-of-range `value` to null (console.error + aria-valuenow omitted) but wrapper's translateX math still uses raw value
+- Progress uses `--border-radius-large` (16px), height `--spacing-small` (8px), root bg `--color-grey-100`, indicator bg `--color-brand-600`
+- Exported at index.ts:39 — Progress only, no type exports
+
+## Dot Component API (verified 2026-04-17)
+- Props: `colour` (required, type `DotColour`) and `label` (optional string). That's IT. No size, className, style, onClick — deliberately closed API.
+- `DotColour` = 7 values: purple, salmon, teal, yellow, green, orange, blue (Dot.tsx:3)
+- `BadgeColour = DotColour` — literal type alias at Badge.tsx:5 (structurally guaranteed identical, not just "same values")
+- Renders as `<span aria-hidden={label ? undefined : 'true'} aria-label={label} className="ds-dot ds-dot--{colour}" />` (Dot.tsx:10-18)
+- Fixed 10×10px circle with `flex-shrink: 0` baked in (dot.scss:3-6)
+- Each colour uses `--color-extended-colours-{colour}-500` (dot.scss:8-34, all 7 declared at tokens.scss:107, 111, 115, 119, 123, 127, 131)
+- Exported at index.ts:18-19 as `Dot` + `DotColour`
+
+## Separator Component (verified 2026-04-22)
+- No forwardRef — plain function component wrapping RadixSeparator.Root
+- Props: `className?: string` + all RadixSeparator.SeparatorProps (orientation, decorative, style, etc.)
+- SCSS: `.ds-separator { width:100%; height:1px; background-color: var(--page-base-color-border); margin: var(--spacing-small) 0; }`
+- --page-base-color-border resolves to --color-grey-050 (tokens.scss:171) -- SAME as --page-color-background (tokens.scss:254) -- so separator IS invisible on default bg
+- No `--separator-*` tokens exist in tokens.scss
+- Exported at index.ts:42, SCSS registered at index.scss:31
+
+## Phantom CSS Class: `ds-text` (identified 2026-04-22)
+- `ds-text` is NOT defined in any SCSS file in this codebase
+- Used across 12+ story files as `className="ds-text"` on `<p>`, `<span>` elements — it's a no-op
+- Not harmful (won't break anything) but applies no styling — it's a Rose convention with no backing SCSS
+- Similar but DIFFERENT: `ds-text-input` (TextInput.tsx:19) and `ds-textarea` (TextArea.tsx:23) ARE real classes
+
+## Rose Accuracy Trend (2026-04-17)
+- Banner stories audit: 14/14 icons verified, all tokens verified, all slug links correct, no phantom tokens, no unsourced authority claims, no hardcoded px/rem/hex in wrappers. Zero hallucinations.
+- Tag stories audit: 8/8 TagColor values verified, 3/3 icon names ('user', 'chevron-down', 'x') verified, 6/6 doc slugs correct (badge/pill/dot/combobox/icon/button), 13+ tokens verified, 4 behavioural claims verified against source (selected overrides color, e.stopPropagation, removeLabel default 'Remove', non-removable renders as span with no role/tabindex). `fn` imported from `storybook/test` correctly. Zero structural hallucinations. Only flag: 6 references to "Confluence design spec" that require human verification against the actual Confluence page — same pattern as other Rose stories, plausible per write-stories skill workflow.
+- This is a significant improvement from prior audits where Rose conflated Tag `color` / Badge `colour` spelling and broke doc links (e.g. `components-formfield-inputs-checkboxinput--docs`)
+- Rose now correctly imports `fn` from `storybook/test` (Storybook 9.1.8+ path — verified in node_modules/storybook/package.json exports)
+- Dot stories audit (2026-04-17): 6 stories, zero hallucinations, zero phantom tokens, zero hardcoded values. `gap: 8` properly replaced with token. All slugs correct, all 7 extended-colour tokens verified, BadgeColour/DotColour equivalence correctly identified as type alias (not just shared values). Only caveats: one Confluence reference and a "de-facto Arbor colour semantics" table that require human/designer sign-off since they cite external context not in code.
+- Separator stories audit (2026-04-22): 6 stories, ONE phantom token (`--color-semantic-info-200` at line 585 — does not exist, scale jumps from 100 to 300). All other tokens verified (20+ references). All behavioural claims correct (no forwardRef, invisible-on-default-bg, decorative role behaviour, vertical not sized by SCSS, Dropdown.Separator exists with ds-dropdown__separator). Both doc slug links correct. Zero ESLint/TS errors. Only other note: `ds-text` className used throughout is a phantom class with no backing SCSS.
+
+## Tag Component API (verified 2026-04-17)
+- Props: `children` (required ReactNode), `color?: TagColor`, `selected?: boolean`, `slotStart?: ReactNode`, `slotEnd?: ReactNode`, `onRemove?: () => void`, `removeLabel?: string` (default `'Remove'`), `removeButtonTabIndex?: 0 | -1` (default `0`)
+- 8 TagColor values: `neutral` (default), `orange`, `blue`, `green`, `purple`, `teal`, `salmon`, `yellow`
+- Renders as `<span className="ds-tag ds-tag--{color}">` with optional `.ds-tag--selected` modifier
+- Non-removable: no `role`, no `tabIndex` on root span (correct a11y — non-interactive elements shouldn't be focusable)
+- Removable: renders `<button type="button" className="ds-tag__remove" aria-label={removeLabel} onClick={e => { e.stopPropagation(); onRemove(); }} tabIndex={removeButtonTabIndex}>` with inner `<Icon name="x" size={12} />`
+- `selected` state overrides `color` bg+border via `--tag-selected-color-background/border` (tokens.scss:234-235), text reverts to `--tag-neutral-color-text`
+- All 8 `--tag-category-{colour}-color-{text,background}` tokens declared in tokens.scss:217-230 (orange/blue/green/purple/teal/salmon/yellow) plus `--tag-neutral-color-{text,background}` at :215-216
+- Layout tokens: `--tag-radius` (border-radius-round/99px), `--tag-height` (size-control-xsmall), `--tag-spacing-horizontal` (spacing-medium), `--tag-spacing-gap-horizontal` (spacing-small), `--tag-spacing-vertical` (spacing-xsmall)
+- Tag exported with `TagProps` and `TagColor` types at src/index.ts:16-17
+
+## Common Hallucination Patterns
+- Agents may claim "all quality checks passed" but only run check-types and style-lint, missing ESLint errors
+- ESLint stylistic rules (@stylistic/arrow-parens, @stylistic/brace-style, @stylistic/operator-linebreak, @stylistic/jsx-one-expression-per-line) are frequently violated in generated code
+- The `yarn eslint` command is not listed in CLAUDE.md's common commands but is critical for quality
+- **NEW PAGE REGISTRATION**: Agents frequently create page component files but forget to register them in `src/index.ts` (export) and `src/index.scss` (@use). The existing pattern (see AssessmentsPage) requires BOTH. Without these, the SCSS is dead code and the component is not part of the library's public API
+- Icon name grep: allowedIcons file is `.tsx` not `.ts` -- use correct extension when searching
+- **Components that DO exist (agents have hallucinated these as missing):**
+  - `Badge` IS exported (index.ts line 20) with `BadgeColour`, `BadgeProps`, `BadgeSize` — `'sm'|'md'|'lg'` sizes, 7 colours
+  - `Dot` IS exported (index.ts line 18) with `DotColour`
+  - `CheckboxInput` IS exported (index.ts line 24)
+  - `SearchBar` IS exported (index.ts line 40)
+  - `BooleanCellRenderer` IS exported (index.ts line 47), also registered as `'dsBooleanCellRenderer'`
+- **Sophia prop hallucinations (confirmed 2026-02-19):**
+  - Button `ghost` variant does NOT exist (actual: primary, secondary, tertiary, primary-destructive, secondary-destructive, text-link, dropdown) ✅ CORRECT
+  - Section `defaultExpanded` does NOT exist (actual: `collapsed` boolean, inverted logic) ✅ CORRECT
+  - Section `headerContent` does NOT exist (Section has buttonText/buttonOnClick for a single button, not an arbitrary ReactNode slot -- Table has headerContent) ✅ CORRECT
+  - Icon `grip-vertical` does NOT exist (actual name: `'grab'` which maps to GripVertical lucide icon) ✅ CORRECT
+  - CheckboxInput IS exported from index.ts (line 24, confirmed 2026-04-17) -- DO NOT claim it's internal
+  - Tree data: codebase uses `treeDataChildrenField` pattern, not `getDataPath` ✅ CORRECT
+  - TextInput has NO icon/prefix support -- it's a bare `<input>` wrapper with only `size` and `hasError` custom props; everything else is passthrough from InputHTMLAttributes ✅ CORRECT
+  - Dropdown has `Dropdown.SelectItem` in addition to `Dropdown.Item` -- agents often omit SelectItem ✅ CORRECT
+  - Table's `treeData`, `getDataPath`, `rowDragManaged` are AG Grid passthroughs (via AgGridReactProps), not Arbor-specific features -- agents should not present them as Table component features ✅ CORRECT
+- **Dorothy's mistakes (corrected):**
+  - ❌ I incorrectly claimed Button `iconLeftName`/`iconRightName` props don't exist - THEY DO EXIST (Button.tsx). User caught this error. These props are real and should be used.
+  - ❌ I claimed CheckboxInput was NOT exported — WRONG. CheckboxInput IS exported (index.ts line 24, confirmed 2026-04-17).
+  - ❌ I claimed Badge does NOT exist — WRONG. Badge IS exported (index.ts line 20, confirmed 2026-04-17) with BadgeColour/BadgeProps/BadgeSize types.
+
+## Table Cell Renderers (verified 2026-02-19)
+- All three registered in Table.tsx `components` prop by string name:
+  - `dsInlineTextCellRenderer` -> InlineTextCellRenderer (renders span with value)
+  - `dsSelectDropdownCellRenderer` -> SelectDropdownCellRenderer (renders dropdown Button, paired with dsSelectDropdownCellEditor)
+  - `dsButtonCellRenderer` -> ButtonCellRenderer (spreads ButtonProps from value, supports iconLeftName/iconRightName for icon buttons)
+- Only `Table.ButtonCellRenderer` is exposed as a static property; others used via string names in colDef
+- `Table.DefaultValueFormatter` also exposed as static property
+
+## Table Themes (verified 2026-02-19)
+- `tidyTheme`: activated via `tableTheme="tidy"` prop. White bg, no borders, clean look. Full example in TidyTable story.
+- `defaultTheme`: the standard theme, supports hasColumnBorders and tableSpacing settings
+- TidyTable story demonstrates: treeData + treeDataChildrenField + inline editing + all cell renderers together
+
+## Section Component (verified 2026-02-19)
+- `title` prop is typed as `string` (NOT ReactNode) -- cannot directly embed JSX like Pill
+- Chevron icon IS auto-added when `collapsible={true}` (chevron-down/chevron-up with aria-expanded)
+- `collapsed` prop sets initial state (inverted from defaultExpanded)
+- `buttonText`/`buttonOnClick` for optional action button in heading
+- `titleIconName`/`titleIconColor`/`titleIconScreenReaderText` for icon next to title
+
+## Sophia Accuracy Trend
+- 2026-02-19 (earlier): Multiple hallucinations (ghost variant, defaultExpanded, headerContent on Section, grip-vertical icon)
+- 2026-02-19 (Student Profile analysis): 100% accuracy on all prop claims across 8 components. Zero hallucinations. Only omissions were Dropdown.SelectItem, some Button variants, and SearchBar.placeholderText -- all editorial choices, not errors.
+- 2026-02-19 (Migration mapping): 14/14 claims verified. Zero hallucinations. Correct on: Heading.InnerContainer, Button type Omit, Tabs semantic HTML, BulkActionsDropdown actions.length (not selected rows), both '3-dot' and 'ellipsis-vertical' icon aliases, setAgGridLicenseKey auto-call, all Table sub-component props. Minor omissions: Tabs.Item link mode, headerContent gatekeeper for search.
+- TooltipWrapper: triggerProps.asChild is technically valid but redundant -- TooltipTrigger already hardcodes asChild={true}
+
+## Icon Alias Gotcha (verified 2026-02-19)
+- `'3-dot'` and `'ellipsis-vertical'` both map to Lucide `EllipsisVertical` -- they are interchangeable aliases
+- `'grab'` maps to Lucide `GripVertical` (NOT `'grip-vertical'`)
+- Prefer Lucide-style naming ('ellipsis-vertical') over legacy aliases ('3-dot') for consistency
+
+## Table Search Gatekeeper (verified 2026-02-19)
+- SearchBar in Table only renders when BOTH `headerContent` is truthy AND `hasSearch` is true (default)
+- `headerContent` controls whether `<TableHeader>` renders at all (Table.tsx line 149)
+- If `headerContent` is falsy, `hasSearch={true}` does nothing -- no search bar appears
+- `quickFilterText` is wired to search state (Table.tsx line 196)
+
+## Export Status (verified 2026-04-17 against src/index.ts)
+- SearchBar: exported (line 40) ✅
+- CheckboxInput: exported (line 24) ✅
+- CheckboxGroup: NOT exported — internal only ✅
+- RadioButtonGroup: NOT exported — internal only ✅
+- BooleanCellRenderer: exported (line 47) ✅ — also registered as `'dsBooleanCellRenderer'` in Table
+- New exports added recently: Toggle, Row, SingleUser, Combobox (+ types), TimeInput (+ types), DatePicker, DateTimePicker (+ types)
+
+## Pill Component API
+- `onclick` prop (lowercase c) accepts `(checked: boolean) => void`
+- Uses `useEffect` to fire onclick on checked state change, including on mount
+- State setters from `useState` are stable references, so passing them directly as onclick is safe
+
+## Test Quality Benchmarks
+- Tests should use accessible queries (getByRole, getByLabelText) over getByText/getByTestId
+- userEvent is preferred over fireEvent for user interactions
+- Tests should verify callback arguments, not just that callbacks were called
+- Edge cases (empty state, no data) should be covered
+
+## NumberInput Component (verified 2026-04-23) -- see [numberinput_component.md](numberinput_component.md)
+- CRITICAL BUG IN STORIES: onBlur claim is INVERTED — `{...rest}` comes AFTER `onBlur={handleOnBlur}` so consumer's onBlur WINS (story says opposite)
+- onChange fires from useEffect with manually constructed event — only `e.currentTarget.value` populated (correct in stories)
+- `defaultValue` guard `if (!defaultValue)` blocks value prop sync when truthy (correct in stories)
+- No forwardRef (correct in stories)
+- Story title `Components/FormField/Inputs/Numeric` follows convention (Checkbox, RadioButton, etc.)
+
+## Storybook Docs Link Slugs (verified 2026-04-17)
+- Storybook slugifies the full `title` path, so `Components/FormField/Inputs/Checkbox` becomes `components-formfield-inputs-checkbox--docs`
+- CheckboxInput's actual story title is `Components/FormField/Inputs/Checkbox` (NOT `CheckboxInput`) — link must be `?path=/docs/components-formfield-inputs-checkbox--docs`
+- Common mistake: Rose wrote `components-formfield-inputs-checkboxinput--docs` in Button.stories.tsx Related components section — broken link
+- When fact-checking docs links, always verify the actual `title:` in the target story file, not just the component name
+
+## Recurring Bugs in Generated Pages (confirmed 2026-02-19)
+- **Icon name `'edit'` does NOT exist** in allowedIcons.tsx -- correct name is `'pencil'`
+- **CSS ds- prefix mismatch**: SCSS uses `.ds-{page-name}` but component JSX omits the `ds-` prefix. Always verify SCSS selectors match JSX classNames
+- **Direct SCSS import in page components**: Pages in `src/pages/` should NOT `import './foo.scss'` directly (causes TS2307). Pages in `src/examples/pages/` CAN use direct imports because Storybook/Vitest handle them fine (global.d.ts declares `*.scss` modules). The `src/examples/` path is for example/demo pages that are NOT part of the library build
+- **Pill renders as `<span>`, NOT `<button>`**: Tests that use `getByRole('button')` to find Pills will fail. Use `getByText` instead
+- **SearchBar inactive state**: SearchBar with empty `searchValue` renders as a collapsed Button, not an input. Tests must click to activate it first, or initialize with non-empty searchValue
+- **TS error downplaying**: Agents may call real TS compilation errors "warnings" or "expected" -- always verify exit code of `yarn check-types`
+- **Page registration still forgotten**: AssessmentBuilderPage was missing from both index.ts and index.scss (same pattern as before)
+- **`@stylistic/jsx-one-expression-per-line` is the #1 ESLint violation**: `<br />` tags inline with text content always trigger this. 12 of 13 ESLint errors in StudentProfilePage were this exact rule. The `--fix` flag can auto-resolve these
+- **Unused imports in test files**: Agents import `beforeEach` from vitest but never use it (1 of 13 errors in StudentProfilePage)
+- **`src/examples/pages/` is a separate convention** from `src/pages/`: example pages are NOT library exports and do NOT need registration in index.ts/index.scss. Direct SCSS imports are fine here

package/.agent-memory/dorothy-fact-checker/numberinput_component.md

@@ -0,0 +1,53 @@
+---
+name: numberinput_component
+description: NumberInput component API, behavioral gotchas, and verified story accuracy (2026-04-23)
+type: project
+---
+
+## NumberInput Component (verified 2026-04-23)
+
+### Props (NumberInputProps)
+- Custom: `hasError?: boolean`, `disableSpinners?: boolean`, `containerClassName?: string`
+- Extends `InputHTMLAttributes<HTMLInputElement>` — so `className`, `disabled`, `step`, `min`, `max`, `value`, `defaultValue`, `onChange`, `placeholder`, `onBlur` etc. all come from HTML attributes
+- Exported type: `NumberInput.Props` via TypeScript namespace (NumberInput.tsx:135-137)
+- No `forwardRef` — component does not expose a ref
+
+### Internal State Model
+- Internal `value` state initialized from `defaultValue.toString() || passedValue.toString()`
+- `defaultValue` defaults to `''` (falsy), `passedValue` (value prop) defaults to `''`
+- useEffect guard: `if (!defaultValue) { setValue(passedValue.toString()) }` — means truthy defaultValue blocks value prop syncing
+- Edge case: `defaultValue={0}` is falsy, so the guard passes and the component acts controlled despite having a "defaultValue"
+
+### onChange Behavior
+- Consumer's `onChange` is called from a useEffect watching internal `value` state (NOT from the native input event)
+- Event is manually constructed: `{ currentTarget: { value } } as ChangeEvent<HTMLInputElement>`
+- Only `e.currentTarget.value` is populated; `e.target` is undefined (accessing `.value` on it throws TypeError)
+
+### CRITICAL: onBlur Prop Ordering Bug
+- JSX order: `onBlur={handleOnBlur}` at line 111, then `{...rest}` at line 115
+- `onBlur` is NOT destructured from props — it stays in `...rest`
+- In React, LATER props override earlier ones — so consumer's `onBlur` in `{...rest}` OVERRIDES internal `handleOnBlur`
+- **The story documentation claims the OPPOSITE** (that internal handler wins) — THIS IS WRONG
+- Actual behavior: consumer's onBlur WINS, internal blur-clamping is SILENTLY LOST
+- NOTE: `onChange` IS destructured (line 17), so it does NOT end up in `...rest` — no conflict there
+
+### Spinner Buttons
+- aria-labels: "Minus button" and "Plus button" (hardcoded, not customisable)
+- Minus disabled when `Number(value) <= Number(min)`
+- Plus disabled when `Number(value) >= Number(max)`
+- Both disabled when `disabled` prop is set
+- Uses Decimal.js for arithmetic precision
+
+### CSS Classes
+- Container: `ds-number-input__container`
+- Error modifier: `ds-number-input__container--error`
+- Disabled modifier: `ds-number-input__container--disabled`
+- Input: `ds-input ds-number-input` (plus consumer's className)
+- Spinner buttons: `ds-number-input__spinner-button`
+
+### Story Title Convention
+- Title: `Components/FormField/Inputs/Numeric` — uses "Numeric" not "NumberInput" (editorial choice, matches pattern where some use shortened names e.g. "Checkbox" not "CheckboxInput")
+
+**Why:** NumberInput has a subtle and dangerous onBlur bug that the story documentation gets backwards. Future fact-checks of this component or its stories should always verify the prop ordering claim.
+
+**How to apply:** When reviewing any NumberInput-related changes, always check whether the onBlur prop ordering documentation has been corrected. If not, flag it.

package/.agent-memory/dorothy-fact-checker/progress_component.md

@@ -0,0 +1,36 @@
+---
+name: Progress Component Mechanics
+description: Radix Progress behaviour quirks — default getValueLabel returns "X%" not raw number, value=null produces invisible bar in this wrapper
+type: project
+---
+
+# Progress Component (verified 2026-04-17)
+
+## Exports & API
+- Exported at `src/index.ts:39` (just `Progress`, no type exports)
+- `ProgressProps = RadixProgress.ProgressProps & { indicatorClassName?: string }` (Progress.tsx:4-6)
+- Radix `ProgressProps` (from `@radix-ui/react-progress/dist/index.d.ts:7-11`) extends `PrimitiveDivProps` with `value?: number | null`, `max?: number`, `getValueLabel?(value, max): string`
+- Since it spreads `PrimitiveDivProps`, ALL `aria-*` attrs, `className`, `style`, etc. flow through — including `aria-label` and `aria-labelledby`
+
+## Critical Radix Default getValueLabel Behaviour
+Radix's default `getValueLabel` returns `"${Math.round(value/max*100)}%"` — a PERCENTAGE STRING WITH `%` SIGN.
+**Why:** Rose in Progress.stories.tsx wrote "Without getValueLabel, screen readers announce the raw number" in 5 places (lines 56, 127, 132, 306, 480). That's wrong — the default is "65%", not "65".
+**How to apply:** When fact-checking any Progress story/docs, verify claims about default `aria-valuetext` output. The correct framing is "Radix's default is `X%`; custom `getValueLabel` lets you produce a full sentence instead."
+
+## The Indeterminate Anti-Pattern (real, not a hallucination)
+- `value={null}` is technically valid per Radix types
+- In our wrapper: `Progress.tsx:9` `value = 0` default ONLY fires for `undefined`, not `null`
+- `Progress.tsx:10`: `Number(null) = 0` → percentage = 0 → `translateX(-100%)` → indicator off-screen
+- Radix DOES set `data-state="indeterminate"` on root (per `@radix-ui/react-progress/dist/index.mjs` `getProgressState`)
+- BUT `progress.scss:1-13` has NO `[data-state="indeterminate"]` rules — no animation defined
+- Net result: value=null renders an invisible bar. Rose's IndeterminateAntiPattern story correctly flags this.
+- Consumers needing indeterminate UX should use a Spinner or pass custom `indicatorClassName` with keyframes targeting `[data-state="indeterminate"]`
+
+## Radix Silently Coerces Out-of-Range value
+At `index.mjs:25-27`: passing `value={150}` with `max={100}` triggers a `console.error` AND coerces `value` to `null` internally (so `aria-valuenow` is omitted). Wrapper still does its own math on the raw `value` prop though, so `Number(150)/100*100 = 150` → `translateX(50%)` (bar overflows past 100%). Silent divergence — worth mentioning in docs.
+
+## Progress Styling Facts
+- `progress.scss`: root uses `--border-radius-large` (16px, tokens.scss:196), NOT `--border-radius-small`
+- Height is `var(--spacing-small)` (8px)
+- Root bg: `--color-grey-100`, indicator bg: `--color-brand-600`
+- Both root and indicator have `border-radius: var(--border-radius-large)`