@boostdev/design-system-components 2.15.0 → 2.17.0

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 A component library with two targets:
 - **React (web)** — CSS Modules, design tokens from `@boostdev/design-system-foundation`, full component suite
-- **Web Components** (experimental) — Lit-based custom elements, framework-agnostic, entry point `@boostdev/design-system-components/web-components`
+- **Web Components** (alpha) — Lit-based custom elements, framework-agnostic, entry point `@boostdev/design-system-components/web-components`
 
 React Native components live in a separate package: [`@boostdev/design-system-react-native`](https://gitlab.com/b00stdev/boostdev-design-system-react-native).
 
@@ -29,17 +29,17 @@ import '@boostdev/design-system-components/web-components';
 - **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/`
+### Web Components (alpha) — `src/web-components/`
 Custom elements built with Lit. Entry: `src/web-components/index.ts`. Lit is bundled into the runtime JS (no peer dep required) and listed as a regular `dependency` so its type declarations resolve for consumers — the emitted `.d.ts` files `import` from `lit`.
 
 - **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/**: `<bds-accordion>`, `<bds-accordion-item>`, `<bds-button>`, `<bds-collapsible>`, `<bds-dialog>`, `<bds-drawer>`, `<bds-dropdown-menu>`, `<bds-dropdown-menu-group>`, `<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-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.
 
-Storybook stories live at `src/web-components/{ui,interaction,interaction/form}/Bds*.stories.tsx` (title path `'Web Components/{UI|Interaction|Form}/{Name}'`, tags `['!stable', 'experimental']`). Stories use a thin React wrapper to enable Storybook controls.
+Storybook stories live at `src/web-components/{ui,interaction,interaction/form}/Bds*.stories.tsx` (title path `'Web Components/{UI|Interaction|Form}/{Name}'`, tags `['!stable', 'alpha']`). Stories use a thin React wrapper to enable Storybook controls.
 
 MDX docs live at `src/web-components/{ui,interaction,interaction/form}/Bds*.mdx` — one per component.
 
@@ -137,6 +137,10 @@ Components use `box-shadow: inset` (not `outline` or `border`) for all visual fr
 - The neutral shadow default is `0 0 0 0 transparent` — `none` is invalid in a comma-separated `box-shadow` list.
 - `:focus-visible` always uses `outline` + `var(--bds-outline_default)` (never the inset shadow).
 - Focus rings use `--bds-outline_default` (2 px solid interactive colour, 2 px offset) — defined in `src/css/bdc.css`.
+- The `:root` defaults in `src/css/bdc.css` and `src/web-components/globals.ts` live in `@layer boostdev.tokens.semantic`, so consumers override them in `@layer boostdev.tokens.override`: `--bdc_color--focus`, `--bdc_color--error`, the `--bdc-color_active` / `--bdc-color_on-active` family, `--bdc-outline_width`, `--bdc-outline_width--error`, `--bds-outline_default`, `--bds-outline_offset`. Keep both files in sync (`src/css/bdc.spec.ts` checks it). Never put a token default in `boostdev.component`: that layer outranks `tokens.override`.
+- `--bdc-outline_width` is registered `inherits: true` so a `:root` value reaches every component. A component must not set it on an element that has children with their own frame (they would inherit it); read a component hook in the `box-shadow` instead, like Collapsible's `var(--collapsible_border-width, var(--bdc-outline_width))`. Error states set `--bdc-outline_width: var(--bdc-outline_width--error, 2px)` on the field itself.
+- `--bdc_color`, `--bdc-outline_radius`, `--bdc-outline_offset` and `--bdc-outline_shadow` stay `inherits: false` (one instance per element). A component's rest frame colour is themed through its own hook (for example `--dropdown_border-color`), never through `--bdc_color` on `:root`.
+- Internal slots that a modifier class writes and a base rule reads end in `--variant`, `--state` or `--size` (`mcp/extract.ts` hides only those). Reset a slot on the base element (`--x--variant: initial;`) when a modifier sets it and the component can be nested, so a nested default instance does not inherit it.
 
 ### Two-level fallback for active/selected state
 
@@ -178,6 +182,8 @@ Prefer semantic tokens over palette tokens. Key tokens for component states:
 | `--bdc-color_active--strong` | Strong active foreground | Switch thumb when on |
 | `--bds-color_success--subtle` | Subtle background for success variant | Alert, NotificationBanner |
 | `--bds-color_on-success--subtle` | Text on success subtle background | Alert, NotificationBanner |
+| `--bds-color_error--subtle` | Subtle background for error variant | Alert, NotificationBanner, DropdownMenu destructive hover |
+| `--bds-color_on-error--subtle` | Text on error subtle background | Alert, NotificationBanner, DropdownMenu destructive hover |
 | `--bds-color_interactive` | Focus ring colour | All focusable inputs |
 | `--bds-color_error` | Error state | All form components |
 
@@ -364,8 +370,8 @@ The following table lists every component-local token extracted from `src/compon
 | Component | Tokens |
 |---|---|
 | 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` |
+| Alert | `--alert_radius`, `--alert_bg`, `--alert_text`, `--alert_border-width`, `--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_gradient`, `--alert_shadow`, `--alert_accent--info`, `--alert_accent--success`, `--alert_accent--warning`, `--alert_accent--error`, `--alert_dismiss-border`, `--alert_dismiss-radius`, `--alert_dismiss-size`, `--alert_dismiss-shadow`, `--alert_dismiss-opacity--hover` |
+| Avatar | `--avatar_size`, `--avatar_radius`, `--avatar_bg`, `--avatar_text`, `--avatar_bg--primary`, `--avatar_text--primary`, `--avatar_bg--secondary`, `--avatar_text--secondary`, `--avatar_bg--accent-1`, `--avatar_text--accent-1`, `--avatar_bg--accent-2`, `--avatar_text--accent-2`, `--avatar_bg--accent-3`, `--avatar_text--accent-3` |
 | 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_icon-offset`, `--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` |
 | ButtonContainer | `--buttonGroup_gap` |
@@ -374,12 +380,12 @@ The following table lists every component-local token extracted from `src/compon
 | 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` |
+| Collapsible | `--collapsible_border`, `--collapsible_border-color`, `--collapsible_border-radius`, `--collapsible_border-width`, `--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`, `--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_shadow` |
-| DropdownMenu | `--dropdown_border`, `--dropdown_radius`, `--dropdown_color`, `--dropdown_on-color`, `--dropdown_shadow`, `--dropdown_item-bg--hover`, `--dropdown_item-color--hover` |
+| DropdownMenu | `--dropdown_padding`, `--dropdown_border`, `--dropdown_border-color`, `--dropdown_radius`, `--dropdown_color`, `--dropdown_on-color`, `--dropdown_shadow`, `--dropdown_separator-color`, `--dropdown_group-label-padding`, `--dropdown_group-label-font-size`, `--dropdown_group-label-font-weight`, `--dropdown_group-label-color`, `--dropdown_item-padding`, `--dropdown_item-radius`, `--dropdown_item-font-size`, `--dropdown_item-opacity--disabled`, `--dropdown_item-bg--hover`, `--dropdown_item-color--hover`, `--dropdown_item-color--destructive`, `--dropdown_item-bg--destructive-hover`, `--dropdown_item-color--destructive-hover`, `--dropdown_shortcut-color`, `--dropdown_shortcut-font-size` |
 | 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` |
@@ -387,7 +393,8 @@ The following table lists every component-local token extracted from `src/compon
 | 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`, `--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` |
+| Message (form atom) | `--formMessage_font-size`, `--formMessage_gap`, `--formMessage_color--error`, `--formMessage_font-weight--error`, `--formMessage_color--hint`, `--formMessage_font-style--hint`, `--formMessage_icon-size` |
+| NotificationBanner | `--banner_bg`, `--banner_text`, `--banner_border-width`, `--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_gradient`, `--banner_shadow`, `--banner_accent--info`, `--banner_accent--success`, `--banner_accent--warning`, `--banner_accent--error`, `--banner_dismiss-size`, `--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`, `--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` |
@@ -395,20 +402,20 @@ The following table lists every component-local token extracted from `src/compon
 | 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`, `--sectionHeader_gap`, `--sectionHeader_subtitle-line-height`, `--sectionHeader_title-color` |
+| Rating | `--rating_color`, `--rating_color--filled`, `--rating_stroke-color`, `--rating_stroke-color--filled`, `--rating_stroke-width` |
+| SectionHeader | `--sectionHeader_gap`, `--sectionHeader_title-color`, `--sectionHeader-title-color`, `--sectionHeader_title-font-family`, `--sectionHeader_subtitle-color`, `--sectionHeader_title-size`, `--sectionHeader_title-line-height`, `--sectionHeader_title-weight`, `--sectionHeader_subtitle-size`, `--sectionHeader_subtitle-line-height`, `--sectionHeader_title-gradient` |
 | 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` |
+| Separator | `--separator_color`, `--separator_thickness`, `--separator_spacing`, `--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` |
+| Table | `--table_border`, `--table_radius`, `--table_shadow`, `--table_font-size`, `--table_cell-padding`, `--table_header-bg`, `--table_header-font-weight`, `--table_header-font-size`, `--table_header-color`, `--table_divider-color`, `--table_sortBtn-color--hover`, `--table_row-bg--hover` |
+| Tabs | `--tabs_divider-color`, `--tabs_gap`, `--tab_padding`, `--tab_font-weight`, `--tab_font-weight--inactive`, `--tab_color`, `--tab_color--inactive`, `--tab_indicator-width`, `--tab_border-color`, `--tab_font-weight--active`, `--tab_color--active`, `--tab_border-color--active`, `--tab_color--hover`, `--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` |
+| Tooltip | `--tooltip_padding`, `--tooltip_radius`, `--tooltip_bg`, `--tooltip_text`, `--tooltip_font-size`, `--tooltip_max-inline-size`, `--tooltip_offset` |
 | 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.