@boostdev/design-system-components 0.1.17 → 1.0.0

package/AGENTS.md

@@ -16,10 +16,10 @@ Or individual token layers. All component styles live inside `@layer component`.
 
 ## Component categories
 
-- **ui/**: Pure display — Badge, Typography, Loading, Skeleton, Collapsible
-- **interaction/**: Interactive — Button, Dialog, Toast (with Provider + hook), Rating
-- **interaction/form/**: Form fields — FormInput, Checkbox, Radio, Switch, SegmentedControl (+ atom primitives Label, Message, InputContainer)
-- **layout/**: Layout helpers — ButtonGroup, Card, SectionHeader, IconWrapper
+- **ui/**: Accordion, Alert, Avatar, Badge, Breadcrumb, Calendar, Carousel, Collapsible, DescriptionList, Link, Loading, NotificationBanner, Pagination, Progress, ProgressCircle, Separator, Skeleton, SkipLink, Table, Tabs, Tooltip, Typography
+- **interaction/**: Button, Command, Dialog, Drawer, DropdownMenu, Popover, Rating, Toast (ToastProvider + useToast hook)
+- **interaction/form/**: Checkbox, CheckboxGroup, Combobox, FileInput, FormInput, NumberInput, Radio, RadioGroup, SegmentedControl, Select, Slider, Switch, Textarea (+ atom primitives: Label, Message, InputContainer)
+- **layout/**: ButtonGroup, Card, IconWrapper, SectionHeader
 
 ## Styling conventions
 
@@ -39,36 +39,61 @@ Component-scoped variables use **inline fallbacks**, not top-level declarations.
   border: 1px solid var(--input_border-color, currentcolor);
 }
 .input:focus {
-  --input_border-color: var(--color_interactive);
+  --input_border-color: var(--bds-interactive);
 }
 
 /* ❌ wrong — declaring defaults at the element level */
 .input {
-  --input_border-color: var(--color_on-bg);
+  --input_border-color: var(--bds-on-bg);
   border: 1px solid var(--input_border-color);
 }
 ```
 
 For **border colours** that should match surrounding text/icon colour, use `currentcolor` as the fallback rather than a specific token.
 
+### bdc border tokens
+
+Components use `outline` (not `border`) for all visual frame edges via `--bdc_*` tokens defined in `src/css/bdc.css`. Set local values on the component rule:
+
+```css
+.myElement {
+  border: var(--myComponent_border, none);
+  --bdc_color: currentcolor;
+  --bdc_radius: var(--bds-border_radius--xs);
+
+  outline: var(--bdc_width) solid var(--bdc_color);
+  outline-offset: var(--bdc_offset);
+  border-radius: var(--myComponent_radius, var(--bdc_radius));
+  box-shadow: var(--myComponent_shadow, var(--bdc_shadow));
+  transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing);
+}
+
+.myElement:focus {
+  --bdc_color: var(--bdc_color--focus); /* transitions smoothly */
+}
+```
+
+Focus state uses `--bdc_color--focus` (= `--bds-interactive`) for mouse focus, and `var(--bds-outline_default)` for `:focus-visible` keyboard focus.
+
 ### Two-level fallback for active/selected state
 
 Components that express an active, checked, or filled state use a two-level chain so consumers can override at component level or globally:
 
 ```css
 /* component var → global semantic token */
-background-color: var(--checkbox_color-active, var(--color_active));
-border-color:     var(--checkbox_color-active, var(--color_active));
-border: solid     var(--checkbox_color-on-active, var(--color_on-active));
+background-color: var(--checkbox_color-active, var(--bds-active));
+border-color:     var(--checkbox_color-active, var(--bds-active));
+border: solid     var(--checkbox_color-on-active, var(--bds-on-active));
 ```
 
 Apply this pattern to any component with a visually distinct active/selected/filled state (checkboxes, radio buttons, sliders, progress bars, switch thumbs, etc.).
 
 ## Token usage rules (from @boostdev/design-system-foundation)
 
+- Token names use `--bds-` prefix (e.g. `--bds-bg`, `--bds-space_m`). Color tokens dropped the `color_` group: `var(--bds-cta)` not `var(--bds-color_cta)`.
 - Colour surfaces always pair with their `on-` content token
-- Space: use named scale tokens (`--space_xs`, `--space_m`, etc.), never raw px/rem
-- Shadow: use elevation scale (`--shadow_s` … `--shadow_2xl`)
+- Space: use named scale tokens (`--bds-space_xs`, `--bds-space_m`, etc.), never raw px/rem
+- Shadow: use elevation scale (`--bds-shadow_s` … `--bds-shadow_2xl`)
 - Z-index: use named role tokens, never raw integers
 
 ### Semantic tokens for state colours
@@ -77,20 +102,20 @@ Prefer semantic tokens over palette tokens. Key tokens for component states:
 
 | Token | Meaning | Used in |
 |-------|---------|---------|
-| `--color_active` | Active / checked / filled state | Checkbox, Radio, Slider, Progress, ProgressCircle |
-| `--color_on-active` | Content on `--color_active` | Checkbox tick, Radio inner dot |
-| `--color_active--subtle` | Subtle background for active track | Switch (`--switch_track-bg--active`) |
-| `--color_active--strong` | Strong foreground for active thumb | Switch (`--switch_thumb-bg--active`) |
-| `--color_success--subtle` | Subtle background for success variant | Alert, NotificationBanner |
-| `--color_on-success--subtle` | Text on success subtle background | Alert, NotificationBanner |
-| `--color_interactive` | Focus ring colour | All focusable inputs |
-| `--color_error` | Error state | All form components |
+| `--bds-active` | Active / checked / filled state | Checkbox, Radio, Slider, Progress, ProgressCircle |
+| `--bds-on-active` | Content on `--bds-active` | Checkbox tick, Radio inner dot |
+| `--bds-active--subtle` | Subtle background for active track | Switch (`--switch_track-bg--active`) |
+| `--bds-active--strong` | Strong foreground for active thumb | Switch (`--switch_thumb-bg--active`) |
+| `--bds-success--subtle` | Subtle background for success variant | Alert, NotificationBanner |
+| `--bds-on-success--subtle` | Text on success subtle background | Alert, NotificationBanner |
+| `--bds-interactive` | Focus ring colour | All focusable inputs |
+| `--bds-error` | Error state | All form components |
 
 Focus rings must use the relative-colour formula for consistency:
 ```css
-box-shadow: var(--component_focus-ring, 0 0 0 2px rgb(from var(--color_interactive) r g b / 20%));
+box-shadow: var(--component_focus-ring, 0 0 0 2px rgb(from var(--bds-interactive) r g b / 20%));
 ```
-Error focus rings substitute `--color_error` for `--color_interactive`.
+Error focus rings substitute `--bds-error` for `--bds-interactive`.
 
 ## Import paths
 
@@ -109,26 +134,39 @@ import '@boostdev/components/css';
 
 Every component must meet WCAG 2.1 Level AA:
 
-- **Semantic HTML** — use the correct element (`<button>`, `<a>`, `<nav>`, `<dialog>`, etc.)
+- **Semantic HTML** — use the correct element (`<button>`, `<a>`, `<nav>`, `<dialog>`, etc.); never `<div onClick>`
 - **Keyboard navigable** — all interactive elements reachable and operable via keyboard
 - **Focus visible** — visible focus indicator on every interactive element (WCAG 2.4.7)
 - **ARIA** — add `aria-label` / `aria-labelledby` / `role` where native semantics are insufficient; no redundant ARIA
+- **Modal dialogs** — `<dialog>` elements must have `aria-modal="true"`, trap Tab focus within the dialog, and restore focus to the trigger element on close
+- **Form inputs** — each input needs one `<label htmlFor>` association (no duplicates); set `aria-required`, `aria-invalid`, and `aria-describedby` explicitly rather than relying solely on HTML attributes in spread props
+- **Form groups** — group related checkboxes/radios with `CheckboxGroup`/`RadioGroup` (renders `<fieldset>`/`<legend>`); group segmented controls with `role="group"` + `aria-label`
 - **Colour contrast** — minimum 4.5:1 for text, 3:1 for large text and UI components (WCAG 1.4.3 / 1.4.11)
 - **Touch targets** — minimum 44×44px interactive area (WCAG 2.5.5)
-- **State communication** — disabled, loading, error, and expanded states communicated via ARIA attributes
-- **No motion harm** — respect `prefers-reduced-motion` for animations/transitions
+- **State communication** — disabled, loading, error, and expanded states communicated via ARIA attributes; live regions (`aria-live`, `aria-atomic`) on dynamically updated content
+- **No motion harm** — respect `prefers-reduced-motion` for animations/transitions; use `@media (prefers-reduced-motion: reduce)` to disable or reduce all `animation` and `transition` effects
+- **Backdrop token** — use `var(--color_backdrop, rgb(0 0 0 / 50%))` for overlay backdrops; never hardcode `rgb()` values
 
 References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https://www.w3.org/WAI/WCAG21/quickref/
 
+## Key decisions
+
+- **Button variants**: `default` (filled) and `ghost` (transparent, outlined). Renamed from `primary`/`secondary`.
+- **Button colour model**: `--button_color` + `--button_on-color` are the two theming inputs. All other button CSS vars derive from these.
+- **`bdc` border token system**: All component frame borders use `outline` (not `border`) via `--bdc_color`, `--bdc_width`, `--bdc_offset`, `--bdc_radius`, `--bdc_shadow` custom properties registered with `@property`. Default `border: none`. The `--bdc_color` `<color>` registration enables smooth CSS transitions on focus/error state changes without JavaScript.
+- **`--bdc_offset: -1px`** (inset) makes outline appear like a traditional inset border. Switch uses `var(--bds-outline_offset)` (2px outside) — keep distinct.
+- **Backdrop token**: `var(--color_backdrop, rgb(0 0 0 / 50%))` — never hardcode rgba. (`--color_backdrop` is a library hook token, not a foundation token.)
+
 ## Adding new components
 
 1. Create `src/components/{category}/{ComponentName}/`
 2. Add `ComponentName.tsx`, `ComponentName.module.css`, `index.ts`
 3. Wrap all CSS rules in `@layer component { ... }`
 4. Use only design token custom properties for colours, spacing, typography
-5. Re-export from the category barrel and from `src/index.ts`
-6. Meet all accessibility requirements listed above
-7. After changes: `pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm lint:css`, `pnpm test`
+5. Export the props interface (`export interface ComponentNameProps`) from the component file
+6. Re-export component and props type from the local `index.ts` and from `src/index.ts`
+7. Meet all accessibility requirements listed above
+8. After changes: `pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm lint:css`, `pnpm test`
 
 ## MCP server
 

package/README.md

@@ -149,7 +149,7 @@ Renders an `aria-hidden` shimmer block. Size it with a `className` or inline sty
 import { Button } from '@boostdev/components';
 
 <Button>Click me</Button>
-<Button variant="secondary">Cancel</Button>
+<Button variant="ghost">Cancel</Button>
 <Button size="small">Small</Button>
 <Button href="/dashboard">Link button</Button>
 <Button iconStart={<Icon />} aria-label="Delete" />
@@ -158,7 +158,7 @@ import { Button } from '@boostdev/components';
 
 | Prop | Type | Default |
 |---|---|---|
-| `variant` | `'primary' \| 'secondary'` | `'primary'` |
+| `variant` | `'default' \| 'ghost'` | `'default'` |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
 | `href` | `string` | — renders an `<a>` |
 | `iconStart` | `ReactNode` | — |
@@ -166,6 +166,19 @@ import { Button } from '@boostdev/components';
 | `hasPulse` | `boolean` | `false` |
 | `disabled` | `boolean` | `false` |
 
+**Variants:**
+- `default` — filled with `--button_color` (CTA green). Hover transitions to an outlined state.
+- `ghost` — transparent background, border and text use `--button_color`. Hover fills.
+
+**Re-theming** — set two CSS custom properties to change the colour of both variants:
+
+```css
+.danger-zone .my-button {
+  --button_color:    var(--bds-error);
+  --button_on-color: var(--bds-on-error);
+}
+```
+
 ---
 
 #### Dialog
@@ -180,9 +193,10 @@ import { Dialog } from '@boostdev/components';
 ```
 
 Renders a native `<dialog>` element with a dimmed, blurred backdrop. `isOpen` controls open/close;
-`onClose` is called when the close button is pressed or the backdrop is clicked.
+`onClose` is called when the close button is pressed or the backdrop is clicked. Dialog traps focus
+while open and restores focus to the triggering element on close.
 
-Override the backdrop colour via `--dialog_backdrop-color` (default: `rgb(0 0 0 / 50%)`).
+Override the backdrop colour via `--color_backdrop` (default: `rgb(0 0 0 / 50%)`).
 
 ---
 
@@ -248,7 +262,7 @@ import { FormInput } from '@boostdev/components';
 #### Checkbox
 
 ```tsx
-import { Checkbox } from '@boostdev/components';
+import { Checkbox, CheckboxGroup } from '@boostdev/components';
 
 <Checkbox
   label="I agree to the terms"
@@ -257,13 +271,25 @@ import { Checkbox } from '@boostdev/components';
 />
 ```
 
+Group multiple checkboxes with a shared label using `CheckboxGroup`:
+
+```tsx
+<CheckboxGroup legend="Notifications" required error={errors.notifications}>
+  <Checkbox label="Email" name="notify_email" />
+  <Checkbox label="SMS" name="notify_sms" />
+  <Checkbox label="Push" name="notify_push" />
+</CheckboxGroup>
+```
+
 #### Radio
 
 ```tsx
-import { Radio } from '@boostdev/components';
+import { Radio, RadioGroup } from '@boostdev/components';
 
-<Radio label="Option A" name="choice" value="a" description="Optional supporting text." />
-<Radio label="Option B" name="choice" value="b" />
+<RadioGroup legend="Preferred contact" required>
+  <Radio label="Option A" name="choice" value="a" description="Optional supporting text." />
+  <Radio label="Option B" name="choice" value="b" />
+</RadioGroup>
 ```
 
 #### Switch
@@ -286,6 +312,7 @@ import { SegmentedControl } from '@boostdev/components';
 <SegmentedControl
   name="view"
   defaultValue="week"
+  aria-label="Calendar view"
   options={[
     { value: 'day',   label: 'Day'   },
     { value: 'week',  label: 'Week'  },
@@ -306,13 +333,16 @@ Single-select control with a sliding thumb. All options have equal width (sized
 ```tsx
 import { ButtonGroup, Button } from '@boostdev/components';
 
-<ButtonGroup variant="flow">
+<ButtonGroup variant="flow" aria-label="Page navigation">
   <Button>Back</Button>
   <Button>Next</Button>
 </ButtonGroup>
 ```
 
-Variants: `flow` · `card` · `modal` · `content`
+| Prop | Type | Default |
+|---|---|---|
+| `variant` | `'flow' \| 'card' \| 'modal' \| 'content'` | — |
+| `aria-label` | `string` | — recommended when group purpose isn't clear from context |
 
 ---
 
@@ -367,10 +397,15 @@ import { IconWrapper } from '@boostdev/components';
 <IconWrapper>
   <svg>...</svg>
 </IconWrapper>
+
+{/* Mark as decorative when accompanied by a visible label */}
+<IconWrapper aria-hidden>
+  <svg>...</svg>
+</IconWrapper>
 ```
 
 Renders a circular container sized to its own `font-size`. Override the background colour via the
-`--icon-wrapper-color` CSS custom property.
+`--icon-wrapper-color` CSS custom property. Pass `aria-hidden` when the icon is decorative.
 
 ---
 
@@ -395,10 +430,10 @@ Every component exposes CSS custom properties as a styling API. Set them on a pa
 `style` to adjust the component without writing extra CSS:
 
 ```css
-/* Override the button background for a specific context */
+/* Override the button colour for a specific context */
 .hero .button {
-  --button_bg: var(--color_brand);
-  --button_text: var(--color_on-brand);
+  --button_color:    var(--bds-brand);
+  --button_on-color: var(--bds-on-brand);
 }
 ```
 
@@ -415,18 +450,18 @@ All component styles sit in `@layer component`. You can also write rules in a hi
 ### Overriding active/checked state colour
 
 Components with a checked or filled state (Checkbox, Radio, Slider, Progress, ProgressCircle)
-expose a component-scoped variable that falls back to the global `--color_active` token:
+expose a component-scoped variable that falls back to the global `--bds-active` token:
 
 ```css
 /* Override the active colour for a single checkbox */
 .my-checkbox {
-  --checkbox_color-active:    var(--color_brand);
-  --checkbox_color-on-active: var(--color_on-brand);
+  --checkbox_color-active:    var(--bds-brand);
+  --checkbox_color-on-active: var(--bds-on-brand);
 }
 
 /* Override for all sliders in a section */
 .settings-panel {
-  --slider_color-active: var(--color_important);
+  --slider_color-active: var(--bds-important);
 }
 ```
 
@@ -443,28 +478,28 @@ retheme all components at once:
 /* tokens.config.css — import after the design system CSS */
 @layer tokens.override {
   :root {
-    --color_cta:        var(--BASE__color--orange);
-    --color_on-cta:     var(--BASE__color--white);
-    --color_interactive: var(--BASE__color--orange);
+    --bds-cta:        var(--bds-BASE__color--orange);
+    --bds-on-cta:     var(--bds-BASE__color--white);
+    --bds-interactive: var(--bds-BASE__color--orange);
   }
 }
 ```
 
 ### Active state tokens
 
-The `--color_active` family controls the checked/filled/selected colour across all form controls
+The `--bds-active` family controls the checked/filled/selected colour across all form controls
 and progress indicators. Override it once to retheme checkboxes, radio buttons, sliders, progress
 bars, and the switch thumb simultaneously:
 
 ```css
 @layer tokens.override {
   :root {
-    --color_active:            var(--BASE__color--blue);
-    --color_on-active:         var(--BASE__color--white);
-    --color_active--subtle:    var(--BASE__color--blue--100);  /* Switch track */
-    --color_on-active--subtle: var(--BASE__color--blue--900);
-    --color_active--strong:    var(--BASE__color--blue--700);  /* Switch thumb */
-    --color_on-active--strong: var(--BASE__color--white);
+    --bds-active:            var(--bds-BASE__color--blue);
+    --bds-on-active:         var(--bds-BASE__color--white);
+    --bds-active--subtle:    var(--bds-BASE__color--blue--100);  /* Switch track */
+    --bds-on-active--subtle: var(--bds-BASE__color--blue--900);
+    --bds-active--strong:    var(--bds-BASE__color--blue--700);  /* Switch thumb */
+    --bds-on-active--strong: var(--bds-BASE__color--white);
   }
 }
 ```
@@ -480,7 +515,7 @@ pnpm build        # compile to dist/
 pnpm typecheck    # TypeScript check (library code only)
 pnpm lint         # ESLint
 pnpm lint:css     # Stylelint
-pnpm test         # Vitest — 329 tests
+pnpm test         # Vitest — 364 tests
 pnpm mcp:start    # Start the MCP server locally (http://localhost:3001/api/mcp)
 pnpm storybook    # Storybook dev server on port 6006
 ```