@boostdev/design-system-components 2.8.0 → 2.12.0

package/AGENTS.md

@@ -24,18 +24,18 @@ import '@boostdev/design-system-components/web-components';
 ## Component categories
 
 ### React (web)
-- **ui/**: Accordion, Alert, Avatar, Badge, Breadcrumb, Calendar, Carousel, Collapsible, DescriptionList, Link, Loading, NotificationBanner, Pagination, Progress, ProgressCircle, Separator, Skeleton, SkipLink, Table, Tabs, Tooltip, Typography
+- **ui/**: Accordion, Alert, Avatar, Badge, Breadcrumb, Calendar, CalendarRange, 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)
+- **interaction/form/**: Checkbox, CheckboxGroup, Combobox, FieldGroup, FileInput, FormInput, NumberInput, Radio, RadioGroup, SegmentedControl, Select, Slider, Switch, Textarea (+ atom primitives: Label, Message, InputContainer)
 - **layout/**: ButtonContainer (formerly ButtonGroup — deprecated alias still available), Card, Grid (supports `isMasonry` — CSS Grid Level 3 with row-span polyfill (auto-tunes the row-track unit to stay under browser implicit-grid caps; `masonryRowUnitPx` overrides) — and `autoSpanMedia` — per-item span derived from media aspect ratio), GridItem (supports `columnSpan="auto"`), IconWrapper, SectionHeader
 
 ### Web Components (experimental) — `src/web-components/`
 Custom elements built with Lit. Entry: `src/web-components/index.ts`. Bundled with Lit (no peer dep required).
 
-- **ui/**: `<bds-alert>`, `<bds-avatar>`, `<bds-badge>`, `<bds-breadcrumb>`, `<bds-button-group>`, `<bds-calendar>`, `<bds-card>`, `<bds-carousel>`, `<bds-description-list>`, `<bds-icon-wrapper>`, `<bds-link>`, `<bds-loading>`, `<bds-notification-banner>`, `<bds-pagination>`, `<bds-progress>`, `<bds-progress-circle>`, `<bds-rating>`, `<bds-section-header>`, `<bds-separator>`, `<bds-skeleton>`, `<bds-table>`, `<bds-typography>`
+- **ui/**: `<bds-alert>`, `<bds-avatar>`, `<bds-badge>`, `<bds-breadcrumb>`, `<bds-button-group>`, `<bds-calendar>`, `<bds-calendar-range>`, `<bds-card>`, `<bds-carousel>`, `<bds-description-list>`, `<bds-icon-wrapper>`, `<bds-link>`, `<bds-loading>`, `<bds-notification-banner>`, `<bds-pagination>`, `<bds-progress>`, `<bds-progress-circle>`, `<bds-rating>`, `<bds-section-header>`, `<bds-separator>`, `<bds-skeleton>`, `<bds-table>`, `<bds-typography>`
 - **layout/**: `<bds-grid>`, `<bds-grid-item>`
 - **interaction/**: `<bds-accordion>`, `<bds-accordion-item>`, `<bds-button>`, `<bds-collapsible>`, `<bds-dialog>`, `<bds-drawer>`, `<bds-dropdown-menu>`, `<bds-dropdown-menu-item>`, `<bds-popover>`, `<bds-skip-link>`, `<bds-tab>`, `<bds-tab-panel>`, `<bds-tabs>`, `<bds-toast-provider>`, `<bds-tooltip>`
-- **interaction/form/**: `<bds-checkbox>`, `<bds-checkbox-group>`, `<bds-combobox>`, `<bds-file-input>`, `<bds-form-input>`, `<bds-number-input>`, `<bds-radio>`, `<bds-radio-group>`, `<bds-segmented-control>`, `<bds-select>`, `<bds-slider>`, `<bds-switch>`, `<bds-textarea>`
+- **interaction/form/**: `<bds-checkbox>`, `<bds-checkbox-group>`, `<bds-combobox>`, `<bds-field-group>`, `<bds-file-input>`, `<bds-form-input>`, `<bds-number-input>`, `<bds-radio>`, `<bds-radio-group>`, `<bds-segmented-control>`, `<bds-select>`, `<bds-slider>`, `<bds-switch>`, `<bds-textarea>`
 
 **Not ported** (deferred): `Command` — depends on `cmdk` React library internals. Use `<bds-combobox>` as the web component alternative.
 
@@ -144,8 +144,8 @@ Components that express an active, checked, or filled state use a two-level chai
 
 ```css
 /* component var → global semantic token */
-background-color: var(--checkbox_color-active, var(--bds-color_green));
-border-color:     var(--checkbox_color-active, var(--bds-color_green));
+background-color: var(--checkbox_color-active, var(--bdc-color_active));
+border-color:     var(--checkbox_color-active, var(--bdc-color_active));
 border: solid     var(--checkbox_color-on-active, var(--bdc-color_on-active));
 ```
 
@@ -172,7 +172,7 @@ Prefer semantic tokens over palette tokens. Key tokens for component states:
 
 | Token | Meaning | Used in |
 |-------|---------|---------|
-| `--bdc-color_active` | Active / checked / filled state (= `--bds-color_green` by default) | Checkbox, Radio, Slider, Progress, ProgressCircle |
+| `--bdc-color_active` | Active / checked / filled state (= `--bds-color_interactive` by default) | Checkbox, Radio, Slider, Progress, ProgressCircle |
 | `--bdc-color_on-active` | Content on active background | Checkbox tick, Radio inner dot |
 | `--bdc-color_active--subtle` | Subtle active background | Switch track when on |
 | `--bdc-color_active--strong` | Strong active foreground | Switch thumb when on |
@@ -181,11 +181,32 @@ Prefer semantic tokens over palette tokens. Key tokens for component states:
 | `--bds-color_interactive` | Focus ring colour | All focusable inputs |
 | `--bds-color_error` | Error state | All form components |
 
-Focus rings must use the relative-colour formula for consistency:
+A relative-colour box-shadow formula is recommended for focus rings that need a soft, tinted treatment instead of the standard outline:
 ```css
 box-shadow: var(--component_focus-ring, 0 0 0 2px rgb(from var(--bds-color_interactive) r g b / 20%));
 ```
-Error focus rings substitute `--bds-color_error` for `--bds-color_interactive`.
+Error focus rings would substitute `--bds-color_error` for `--bds-color_interactive`. Note: no component currently implements this formula — all components today use `outline: var(--bds-outline_default)` + `outline-offset: var(--bds-outline_offset)` on `:focus-visible` (see "bdc border tokens" above and "Key decisions" below).
+
+### Role tokens, state tokens and grounds (foundation ≥2.2.0)
+
+Foundation 2.2.0 added named role tokens for accent colours, alongside state and additional ground tokens. These are the **canonical** names going forward for new work:
+
+- **Role tokens** — `--bds-color_primary`, `--bds-color_secondary`, `--bds-color_accent-1`, `--bds-color_accent-2`, `--bds-color_accent-3`. Each has the full `--subtle` / `--strong` pair and an `on-` counterpart for content drawn on top (`--bds-color_on-primary`, `--bds-color_on-primary--subtle`, `--bds-color_on-primary--strong`, etc.) — same pairing law as the existing status colours.
+- **Deprecated hue aliases** — `--bds-color_blue`, `--bds-color_green`, `--bds-color_orange` (and their `--subtle`/`--strong`/`on-` variants) still resolve (they now alias to `primary`/`accent-1`/`accent-2` respectively) but are deprecated and scheduled for removal in foundation 3.0. Do not migrate existing hue-name references to role names purely for its own sake — only role names are new-foundation-only, so a reference written against a hue alias keeps working on older foundations that a role-name reference would not.
+- **State tokens** — `--bds-color_interactive--hover` and `--bds-color_interactive--active` give explicit hover/active treatments for interactive elements, instead of components deriving their own tint.
+- **`--bds-color_on-bg--muted`** — de-emphasised text on the page background (e.g. helper text, timestamps). It is guaranteed ≥7:1 contrast against `--bds-color_bg`, so it must never be used to *look* disabled — muted text is still fully readable body content.
+- **`--bds-color_on-bg--border`** — hairline/divider colour intended for use against the page background.
+- **Disabled pair** — `--bds-color_disabled` (background) / `--bds-color_on-disabled` (content) are the dedicated disabled-state tokens. Never reuse `on-bg--muted` for a disabled look, and never put `on-disabled` on content that must stay readable — it is intentionally low-contrast.
+- **`--bds-color_bg--strong`** (+ `--bds-color_on-bg--strong`) — a "prominent ground" for surfaces that need to read as raised above the page: it equals `--bds-color_bg` in light mode but steps up to a distinct grey-800 in dark mode, so cards, dialogs, drawers, toasts, popovers, dropdown/listbox panels and similar floating surfaces get visible separation from the page in dark mode without any extra styling. Regular in-flow content (page backgrounds, inline sections, form-control backgrounds) should keep using plain `--bds-color_bg`.
+
+**Backwards-compatible fallback-chain pattern**: because this package's peer range is `>=2.0.0`, every reference to a token introduced after 2.0.0 must fall back to a token that exists on 2.0.0, so consumers on older foundations don't get a broken `var()`. For example, migrating a raised surface to `bg--strong` while preserving whatever hook/default that surface already had:
+```css
+/* before */
+background-color: var(--card_color, var(--bds-color_bg));
+/* after — falls back to plain bg on foundation <2.2.0 */
+background-color: var(--card_color, var(--bds-color_bg--strong, var(--bds-color_bg)));
+```
+Never reference a 2.2.0+ token without this trailing fallback, and never raise the `@boostdev/design-system-foundation` peerDependency floor just to use a new token — the fallback chain is what lets new tokens ship without a breaking change.
 
 ### Semantic vs raw token layers
 
@@ -320,50 +341,55 @@ The following table lists every component-local token extracted from `src/compon
 
 | Component | Tokens |
 |---|---|
-| Accordion | `--accordion_border`, `--accordion_radius`, `--accordion_trigger-bg--hover` |
-| Alert | `--alert_bg`, `--alert_text`, `--alert_border`, `--alert_bg--info`, `--alert_text--info`, `--alert_border--info`, `--alert_bg--success`, `--alert_text--success`, `--alert_border--success`, `--alert_bg--warning`, `--alert_text--warning`, `--alert_border--warning`, `--alert_bg--error`, `--alert_text--error`, `--alert_border--error`, `--alert_dismiss-border`, `--alert_dismiss-radius`, `--alert_dismiss-opacity--hover` |
+| Accordion | `--accordion_border`, `--accordion_radius`, `--accordion_trigger-bg--hover`, `--accordion_shadow` |
+| Alert | `--alert_bg`, `--alert_text`, `--alert_border`, `--alert_bg--info`, `--alert_text--info`, `--alert_border--info`, `--alert_bg--success`, `--alert_text--success`, `--alert_border--success`, `--alert_bg--warning`, `--alert_text--warning`, `--alert_border--warning`, `--alert_bg--error`, `--alert_text--error`, `--alert_border--error`, `--alert_dismiss-border`, `--alert_dismiss-radius`, `--alert_dismiss-opacity--hover`, `--alert_dismiss-shadow`, `--alert_dismiss-size`, `--alert_radius` |
 | Avatar | `--avatar_size`, `--avatar_radius`, `--avatar_bg`, `--avatar_text` |
 | Badge | `--badge_radius`, `--badge_font-size`, `--badge_bg`, `--badge_text`, `--badge_bg--primary`, `--badge_text--primary`, `--badge_bg--secondary`, `--badge_text--secondary`, `--badge_bg--success`, `--badge_text--success`, `--badge_bg--error`, `--badge_text--error`, `--badge_bg--warning`, `--badge_text--warning` |
 | Button | `--button_color`, `--button_on-color`, `--button_color--on-bg`, `--button_radius`, `--button_height`, `--button_font-size`, `--button_bg`, `--button_text`, `--button_border`, `--button_pulse-color`, `--button_bg--hover`, `--button_text--hover`, `--button_border--hover`, `--button_pulse-color--hover`, `--button_bg--outline`, `--button_text--outline`, `--button_border--outline`, `--button_bg--outline-hover`, `--button_text--outline-hover`, `--button_border--outline-hover` |
-| Calendar | `--calendar_border`, `--calendar_radius`, `--calendar_shadow`, `--calendar_button-radius`, `--calendar_navBtn-bg--hover`, `--calendar_day-bg--hover`, `--calendar_today-color`, `--calendar_today-border`, `--calendar_day-bg--selected`, `--calendar_day-color--selected` |
-| Card | `--card_color`, `--card_on-color`, `--card_shadow--default`, `--card_shadow--elevated`, `--card_shadow--outlined`, `--card_border`, `--card_padding`, `--card_shadow--clickable-hover`, `--card_shadow--default-hover`, `--card_shadow--elevated-hover`, `--card_shadow--outlined-hover` |
-| Carousel | `--carousel_indicator-radius`, `--carousel_navBtn-bg--hover` |
-| Checkbox | `--checkbox_color`, `--checkbox_border`, `--checkbox_radius`, `--checkbox_shadow`, `--checkbox_color_bg`, `--checkbox_color-active`, `--checkbox_color-on-active` |
-| Collapsible | `--collapsible_border-width`, `--collapsible_border-color`, `--collapsible_border-radius`, `--collapsible_color`, `--collapsible_bg`, `--collapsible_bg--hover`, `--collapsible_on-color` |
-| Combobox | `--combobox_border`, `--combobox_radius`, `--combobox_shadow`, `--combobox_color_bg`, `--combobox_color`, `--combobox_on-color`, `--combobox_listbox-border`, `--combobox_listbox-radius`, `--combobox_listbox-shadow`, `--combobox_option-bg--highlighted`, `--combobox_option-color--highlighted` |
-| Command | `--command_color`, `--command_on-color`, `--command_border`, `--command_shadow`, `--command_item-bg--active` |
+| ButtonContainer | `--buttonGroup_gap` |
+| Calendar | `--calendar_border`, `--calendar_radius`, `--calendar_shadow`, `--calendar_button-radius`, `--calendar_navBtn-bg--hover`, `--calendar_day-bg--hover`, `--calendar_today-color`, `--calendar_today-border`, `--calendar_day-bg--selected`, `--calendar_day-color--selected`, `--calendar_day-bg--in-range`, `--calendar_size`, `--calendar_today-shadow` |
+| Card | `--card_color`, `--card_on-color`, `--card_shadow--default`, `--card_shadow--elevated`, `--card_shadow--outlined`, `--card_border`, `--card_padding`, `--card_shadow--clickable-hover`, `--card_shadow--default-hover`, `--card_shadow--elevated-hover`, `--card_shadow--outlined-hover`, `--card_radius`, `--card_shadow--active`, `--card_transition` |
+| Carousel | `--carousel_indicator-radius`, `--carousel_navBtn-bg--hover`, `--carousel_navBtn-radius`, `--carousel_navBtn-shadow` |
+| Checkbox | `--checkbox_color`, `--checkbox_border`, `--checkbox_radius`, `--checkbox_shadow`, `--checkbox_color_bg`, `--checkbox_color-active`, `--checkbox_color-on-active`, `--checkbox_gap`, `--checkbox_offset`, `--checkbox_size` |
+| CheckboxGroup | `--checkboxGroup_gap`, `--checkboxGroup_items-gap`, `--checkboxGroup_legend-color`, `--checkboxGroup_legend-font-family`, `--checkboxGroup_legend-font-size`, `--checkboxGroup_legend-font-weight`, `--checkboxGroup_legend-gap`, `--checkboxGroup_required-color` |
+| Collapsible | `--collapsible_border-width`, `--collapsible_border-color`, `--collapsible_border-radius`, `--collapsible_color`, `--collapsible_bg`, `--collapsible_bg--hover`, `--collapsible_on-color`, `--collapsible_border` |
+| Combobox | `--combobox_border`, `--combobox_radius`, `--combobox_shadow`, `--combobox_color_bg`, `--combobox_color`, `--combobox_on-color`, `--combobox_listbox-border`, `--combobox_listbox-radius`, `--combobox_listbox-shadow`, `--combobox_option-bg--highlighted`, `--combobox_option-color--highlighted`, `--combobox_listbox-bg`, `--combobox_listbox-max-block-size`, `--combobox_listbox-padding-block`, `--combobox_option-font-size`, `--combobox_option-padding-block`, `--combobox_option-padding-inline` |
+| Command | `--command_color`, `--command_on-color`, `--command_border`, `--command_shadow`, `--command_item-bg--active`, `--command_kbd-radius`, `--command_radius` |
 | Dialog | `--dialog_border`, `--dialog_radius`, `--dialog_shadow`, `--dialog_color`, `--dialog_on-color`, `--dialog_close-radius`, `--dialog_close-border` |
-| Drawer | `--drawer_color`, `--drawer_on-color`, `--drawer_close-radius`, `--drawer_close-bg--hover` |
+| Drawer | `--drawer_color`, `--drawer_on-color`, `--drawer_close-radius`, `--drawer_close-bg--hover`, `--drawer_shadow` |
 | DropdownMenu | `--dropdown_border`, `--dropdown_radius`, `--dropdown_color`, `--dropdown_on-color`, `--dropdown_shadow`, `--dropdown_item-bg--hover`, `--dropdown_item-color--hover` |
-| FieldGroup | `--fieldGroup_gap`, `--fieldGroup_min-field-width`, `--fieldGroup_legend-padding-block`, `--fieldGroup_legend-gap`, `--fieldGroup_legend-border-block-end`, `--fieldGroup_legend-color`, `--fieldGroup_legend-font-size`, `--fieldGroup_legend-font-weight`, `--fieldGroup_legend-line-height` |
-| FileInput | `--fileInput_color`, `--fileInput_border-color`, `--fileInput_border-color--hover`, `--fileInput_bg--hover` |
-| FormInput | `--input_border`, `--input_radius`, `--input_shadow`, `--input_color`, `--input_color_bg` |
+| FieldGroup | `--fieldGroup_gap`, `--fieldGroup_min-field-width`, `--fieldGroup_collapse-threshold`, `--fieldGroup_legend-padding-block`, `--fieldGroup_legend-gap`, `--fieldGroup_legend-border-block-end`, `--fieldGroup_legend-color`, `--fieldGroup_legend-font-size`, `--fieldGroup_legend-font-weight`, `--fieldGroup_legend-line-height`, `--fieldGroup_legend-font-family` |
+| FileInput | `--fileInput_color`, `--fileInput_border-color`, `--fileInput_border-color--hover`, `--fileInput_bg--hover`, `--fileInput_bg--dragging`, `--fileInput_border`, `--fileInput_font-size`, `--fileInput_font-size--hint`, `--fileInput_gap`, `--fileInput_label-margin`, `--fileInput_padding`, `--fileInput_radius` |
+| FormInput | `--input_border`, `--input_radius`, `--input_shadow`, `--input_color`, `--input_color_bg`, `--formInput_border`, `--formInput_color`, `--formInput_color_bg`, `--formInput_font-family`, `--formInput_font-size`, `--formInput_padding`, `--formInput_radius`, `--formInput_shadow` |
 | Grid | `--grid_gap`, `--grid_columns` |
-| IconWrapper | `--icon-wrapper-radius`, `--icon-wrapper-color`, `--icon-wrapper_on-color` |
+| IconWrapper | `--icon-wrapper-radius`, `--icon-wrapper-color`, `--icon-wrapper_on-color`, `--icon-wrapper_color`, `--icon-wrapper_margin-block-end`, `--icon-wrapper_margin-block-start`, `--icon-wrapper_radius`, `--icon-wrapper_size` |
 | Link | `--link_color`, `--link_color-hover`, `--link_color--default`, `--link_color-hover--default`, `--link_color--subtle`, `--link_color-hover--subtle`, `--link_color--standalone`, `--link_color-hover--standalone` |
-| Loading | `--loading_radius` |
-| NotificationBanner | `--banner_bg`, `--banner_text`, `--banner_border`, `--banner_bg--info`, `--banner_text--info`, `--banner_border--info`, `--banner_bg--success`, `--banner_text--success`, `--banner_border--success`, `--banner_bg--warning`, `--banner_text--warning`, `--banner_border--warning`, `--banner_bg--error`, `--banner_text--error`, `--banner_border--error`, `--banner_dismiss-radius`, `--banner_dismiss-border`, `--banner_dismiss-opacity--hover` |
-| NumberInput | `--numberInput_border`, `--numberInput_radius`, `--numberInput_shadow`, `--numberInput_color`, `--numberInput_stepper-bg`, `--numberInput_stepper-color`, `--numberInput_stepper-bg--hover`, `--numberInput_stepper-opacity--hover` |
-| Pagination | `--pagination_radius`, `--btn_bg`, `--btn_color`, `--btn_border`, `--btn_bg--hover`, `--btn_color--hover`, `--btn_bg--active`, `--btn_color--active`, `--btn_border--active` |
+| Loading | `--loading_radius`, `--loading_color` |
+| NotificationBanner | `--banner_bg`, `--banner_text`, `--banner_border`, `--banner_bg--info`, `--banner_text--info`, `--banner_border--info`, `--banner_bg--success`, `--banner_text--success`, `--banner_border--success`, `--banner_bg--warning`, `--banner_text--warning`, `--banner_border--warning`, `--banner_bg--error`, `--banner_text--error`, `--banner_border--error`, `--banner_dismiss-radius`, `--banner_dismiss-border`, `--banner_dismiss-opacity--hover`, `--banner_dismiss-size` |
+| NumberInput | `--numberInput_border`, `--numberInput_radius`, `--numberInput_shadow`, `--numberInput_color`, `--numberInput_stepper-bg`, `--numberInput_stepper-color`, `--numberInput_stepper-bg--hover`, `--numberInput_stepper-opacity--hover`, `--numberInput_font-size`, `--numberInput_padding`, `--numberInput_stepper-padding` |
+| Pagination | `--pagination_radius`, `--btn_bg`, `--btn_color`, `--btn_border`, `--btn_bg--hover`, `--btn_color--hover`, `--btn_bg--active`, `--btn_color--active`, `--btn_border--active`, `--pagination_item-bg`, `--pagination_item-bg--active`, `--pagination_item-bg--hover`, `--pagination_item-border`, `--pagination_item-border--active`, `--pagination_item-color`, `--pagination_item-color--active`, `--pagination_item-color--hover` |
 | Popover | `--popover_z-index`, `--popover_max-width`, `--popover_max-height`, `--popover_border`, `--popover_radius`, `--popover_color`, `--popover_on-color`, `--popover_shadow` |
-| Progress | `--progress_height`, `--progress_radius`, `--progress_color-active` |
-| ProgressCircle | `--progressCircle_color-active` |
-| Radio | `--radio_color`, `--radio_border`, `--radio_radius`, `--radio_shadow`, `--radio_color_bg`, `--radio_color-active`, `--radio_description-color` |
+| Progress | `--progress_height`, `--progress_radius`, `--progress_color-active`, `--progress_color-track` |
+| ProgressCircle | `--progressCircle_color-active`, `--progressCircle_color-track`, `--progressCircle_font-size--small` |
+| Radio | `--radio_color`, `--radio_border`, `--radio_radius`, `--radio_shadow`, `--radio_color_bg`, `--radio_color-active`, `--radio_description-color`, `--radio_offset`, `--radio_size` |
+| RadioGroup | `--radioGroup_gap`, `--radioGroup_items-gap`, `--radioGroup_legend-color`, `--radioGroup_legend-font-family`, `--radioGroup_legend-font-size`, `--radioGroup_legend-font-weight`, `--radioGroup_legend-gap`, `--radioGroup_required-color` |
 | Rating | `--rating_color`, `--rating_color--filled` |
-| SectionHeader | `--sectionHeader-title-color`, `--sectionHeader_subtitle-color`, `--sectionHeader_title-size`, `--sectionHeader_title-line-height`, `--sectionHeader_title-weight`, `--sectionHeader_subtitle-size` |
-| SegmentedControl | `--control_track-bg`, `--control_radius`, `--control_thumb-radius`, `--control_thumb-bg`, `--control_label-color`, `--control_label-color--active`, `--control_label-color--hover`, `--control_item-bg`, `--control_item-bg--active`, `--control_indicator-color` |
-| Select | `--select_border`, `--select_radius`, `--select_shadow`, `--select_color_bg`, `--select_color`, `--select_chevron-color` |
-| Separator | `--separator_color`, `--separator_thickness` |
-| Slider | `--slider_color`, `--slider_track-radius`, `--slider_color-active`, `--slider_track-bg`, `--slider_thumb-radius`, `--slider_color--error` |
-| Switch | `--switch_color`, `--switch_track-radius`, `--switch_track-bg`, `--switch_shadow`, `--switch_thumb-bg`, `--switch_thumb-radius`, `--switch_border-color--error`, `--switch_track-bg--active`, `--switch_thumb-bg--active` |
-| Table | `--table_border`, `--table_radius`, `--table_sortBtn-color--hover`, `--table_row-bg--hover` |
-| Tabs | `--tab_color`, `--tab_border-color`, `--tab_color--active`, `--tab_border-color--active`, `--tab_color--hover` |
-| Textarea | `--textarea_border`, `--textarea_radius`, `--textarea_shadow`, `--textarea_color_bg`, `--textarea_color` |
-| Toast | `--toast_color`, `--toast_on-color`, `--toast_color--success`, `--toast_on-color--success`, `--toast_color--warning`, `--toast_on-color--warning`, `--toast_color--info`, `--toast_on-color--info`, `--toast_color--error`, `--toast_on-color--error` |
-| Tooltip | `--tooltip_radius`, `--tooltip_bg`, `--tooltip_text` |
-| Typography | `--typography_color` |
-
-Components not listed have no component-local override tokens: Breadcrumb, ButtonContainer, CheckboxGroup, DescriptionList, GridItem, InputContainer, Label, Message, RadioGroup, Skeleton, SkipLink.
+| SectionHeader | `--sectionHeader-title-color`, `--sectionHeader_subtitle-color`, `--sectionHeader_title-size`, `--sectionHeader_title-line-height`, `--sectionHeader_title-weight`, `--sectionHeader_subtitle-size`, `--sectionHeader_gap`, `--sectionHeader_subtitle-line-height`, `--sectionHeader_title-color` |
+| SegmentedControl | `--control_track-bg`, `--control_radius`, `--control_thumb-radius`, `--control_thumb-bg`, `--control_label-color`, `--control_label-color--active`, `--control_label-color--hover`, `--control_item-bg`, `--control_item-bg--active`, `--control_indicator-color`, `--control_item-padding`, `--control_thumb-shadow`, `--control_track-pad` |
+| Select | `--select_border`, `--select_radius`, `--select_shadow`, `--select_color_bg`, `--select_color`, `--select_chevron-color`, `--select_chevron-size`, `--select_padding`, `--select_padding-end` |
+| Separator | `--separator_color`, `--separator_thickness`, `--separator_length` |
+| Skeleton | `--skeleton_color-base`, `--skeleton_color-highlight`, `--skeleton_min-block-size`, `--skeleton_radius` |
+| SkipLink | `--skip-link_border`, `--skip-link_font-size`, `--skip-link_inset`, `--skip-link_padding`, `--skip-link_radius`, `--skip-link_shadow`, `--skip-link_z-index` |
+| Slider | `--slider_color`, `--slider_track-height`, `--slider_thumb-size`, `--slider_track-radius`, `--slider_color-active`, `--slider_track-bg`, `--slider_thumb-radius`, `--slider_color--error` |
+| Switch | `--switch_color`, `--switch_thumb-size`, `--switch_track-pad`, `--switch_track-radius`, `--switch_track-bg`, `--switch_shadow`, `--switch_thumb-bg`, `--switch_thumb-radius`, `--switch_border-color--error`, `--switch_track-bg--active`, `--switch_thumb-bg--active` |
+| Table | `--table_border`, `--table_radius`, `--table_sortBtn-color--hover`, `--table_row-bg--hover`, `--table_cell-padding`, `--table_font-size`, `--table_header-font-size`, `--table_shadow` |
+| Tabs | `--tab_color`, `--tab_border-color`, `--tab_color--active`, `--tab_border-color--active`, `--tab_color--hover`, `--tab_padding`, `--tabs_gap`, `--tabs_panel-padding` |
+| Textarea | `--textarea_border`, `--textarea_radius`, `--textarea_shadow`, `--textarea_color_bg`, `--textarea_color`, `--textarea_font-family`, `--textarea_font-size`, `--textarea_line-height`, `--textarea_min-block-size`, `--textarea_padding` |
+| Toast | `--toast_color`, `--toast_on-color`, `--toast_color--success`, `--toast_on-color--success`, `--toast_color--warning`, `--toast_on-color--warning`, `--toast_color--info`, `--toast_on-color--info`, `--toast_color--error`, `--toast_on-color--error`, `--toast_radius`, `--toast_shadow` |
+| Tooltip | `--tooltip_radius`, `--tooltip_bg`, `--tooltip_text`, `--tooltip_font-size`, `--tooltip_max-inline-size`, `--tooltip_offset`, `--tooltip_padding` |
+| Typography | `--typography_color`, `--typography_font-size--body`, `--typography_font-size--body_s`, `--typography_font-size--h1`, `--typography_font-size--h2`, `--typography_font-size--h3` |
+
+Components not listed have no component-local override tokens: Breadcrumb, DescriptionList, GridItem, InputContainer, Label, Message.
 
 ## MCP server
 
@@ -375,8 +401,11 @@ https://ds.boostdev.nl/api/mcp
 
 Connect to it to look up component props, CSS custom properties, and tokens without reading source files. Use
 `ds_get_component` before writing any component code — it returns the props interface **and** all
-overridable CSS custom properties with their defaults. Override CSS variables on the component
-element or any parent in plain CSS (no `@layer` needed):
+overridable CSS custom properties with their defaults.
+
+`ds_get_component` covers three platforms via the `platform` argument: `"web"` (default — React components, props + CSS custom properties), `"web-component"` (framework-agnostic `<bds-*>` custom elements — attributes, CSS custom properties, `bds-*` events, and slots), and `"native"` (React Native). `ds_list_components` and `ds_search` include all three.
+
+Override CSS variables on the component element or any parent in plain CSS (no `@layer` needed):
 
 ```css
 .my-branded-button {

package/README.md

@@ -346,6 +346,22 @@ import { SegmentedControl } from '@boostdev/design-system-components';
 
 Children-based API — pass `<button>`, `<a>`, or router `<Link>` elements directly. Active item is set via `selectedIndex` or auto-detected from `aria-current="page"` / `aria-pressed={true}` / `aria-selected={true}`. Variants: `outline` (default) · `filled`. Sizes: `small` · `medium` (default) · `large`.
 
+#### FieldGroup
+
+```tsx
+import { FieldGroup, FormInput } from '@boostdev/design-system-components';
+
+<FieldGroup legend="Address" variant="horizontal">
+  <FormInput label="Street" name="street" />
+  <FormInput label="City" name="city" />
+</FieldGroup>
+```
+
+Semantically groups related fields under a single `<fieldset>`. `horizontal` (default) lays fields
+into a row that collapses to a single column via a CSS container query when the group itself is too
+narrow; `vertical` always stacks. Accepts any form control as a child. Omit `legend` and provide
+`aria-label` / `aria-labelledby` when the surrounding context already names the group.
+
 ---
 
 ### Layout components
@@ -500,8 +516,8 @@ Every component exposes CSS custom properties as a styling API. Set them on a pa
 ```css
 /* Override the button colour for a specific context */
 .hero .button {
-  --button_color:    var(--bds-brand);
-  --button_on-color: var(--bds-on-brand);
+  --button_color:    var(--bds-color_success);
+  --button_on-color: var(--bds-color_on-success);
 }
 ```
 
@@ -535,22 +551,24 @@ shapes from the foundation. Override the component-scoped variable to change ind
 ### 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 `--bds-active` token:
+expose a component-scoped variable that falls back to the shared `--bdc-color_active` hook token
+(defined in `src/css/bdc.css`, defaults to `--bds-color_interactive`):
 
 ```css
 /* Override the active colour for a single checkbox */
 .my-checkbox {
-  --checkbox_color-active:    var(--bds-brand);
-  --checkbox_color-on-active: var(--bds-on-brand);
+  --checkbox_color-active:    var(--bds-color_blue);
+  --checkbox_color-on-active: var(--bds-color_white);
 }
 
 /* Override for all sliders in a section */
 .settings-panel {
-  --slider_color-active: var(--bds-important);
+  --slider_color-active: var(--bds-color_green);
 }
 ```
 
-The two-level chain means you can also override at the global token level — see Theming below.
+The two-level chain means you can also override `--bdc-color_active` / `--bdc-color_on-active`
+once to retheme every component's active state at the same time — see Theming below.
 
 ---
 
@@ -563,28 +581,31 @@ retheme all components at once:
 /* tokens.config.css — import after the design system CSS */
 @layer boostdev.tokens.override {
   :root {
-    --bds-cta:        var(--bds-BASE__color--orange);
-    --bds-on-cta:     var(--bds-BASE__color--white);
-    --bds-interactive: var(--bds-BASE__color--orange);
+    --bds-color_interactive:    var(--bds-color_orange);
+    --bds-color_on-interactive: var(--bds-color_white);
   }
 }
 ```
 
+On foundation `>=2.2.0`, prefer the named role tokens (`--bds-color_primary`, `--bds-color_secondary`,
+`--bds-color_accent-1..3`, each with `--subtle`/`--strong` steps and `on-` pairs) over the deprecated
+hue names (`--bds-color_blue`, `--bds-color_green`, `--bds-color_orange`) for new theming work. Raised
+surfaces — cards, dialogs, drawers, popovers, dropdown panels, toasts — use `--bds-color_bg--strong`,
+which matches `--bds-color_bg` in light mode but steps up to a distinct tone in dark mode for visible
+separation from the page.
+
 ### Active state tokens
 
-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:
+The `--bdc-color_active` family (defined in `src/css/bdc.css`) controls the checked/filled/selected
+colour across form controls and progress indicators. Override it once to retheme checkboxes, radio
+buttons, sliders, and progress bars simultaneously:
 
 ```css
 @layer boostdev.tokens.override {
   :root {
-    --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);
+    --bdc-color_active:         var(--bds-color_blue);
+    --bdc-color_on-active:      var(--bds-color_white);
+    --bdc-color_active--subtle: var(--bds-color_blue--subtle);    /* Switch track */
   }
 }
 ```
@@ -600,7 +621,7 @@ pnpm build        # compile to dist/
 pnpm typecheck    # TypeScript check (library code only)
 pnpm lint         # ESLint
 pnpm lint:css     # Stylelint
-pnpm test         # Vitest — 1122 tests
+pnpm test         # Vitest — runs the full test suite
 pnpm mcp:start    # Start the MCP server locally (http://localhost:3001/api/mcp)
 pnpm storybook    # Storybook dev server on port 6006
 ```