@boostdev/design-system-components 2.7.0 → 2.8.0

package/AGENTS.md

@@ -80,7 +80,7 @@ Also: never define story component functions inside a `render: () => { function
 Component-scoped variables use **inline fallbacks**, not top-level declarations. The default value lives inside the `var()` call; state overrides (`:focus`, error modifier, etc.) set the variable on the rule where they apply:
 
 ```css
-/* ✅ correct — default is the fallback, state sets the var */
+/* correct — default is the fallback, state sets the var */
 .input {
   border: 1px solid var(--input_border-color, currentcolor);
 }
@@ -88,7 +88,7 @@ Component-scoped variables use **inline fallbacks**, not top-level declarations.
   --input_border-color: var(--bds-color_interactive);
 }
 
-/* ❌ wrong — declaring defaults at the element level */
+/* wrong — declaring defaults at the element level */
 .input {
   --input_border-color: var(--bds-color_on-bg);
   border: 1px solid var(--input_border-color);
@@ -97,6 +97,20 @@ Component-scoped variables use **inline fallbacks**, not top-level declarations.
 
 For **border colours** that should match surrounding text/icon colour, use `currentcolor` as the fallback rather than a specific token.
 
+### Consumer override surface
+
+Every `var(--{component}_{property}, fallback)` reference in a component's CSS module is a **public override point**. Consumers restyle components by setting these properties on the element or any ancestor -- no `@layer` or specificity tricks needed.
+
+**Naming convention**: `--{component}_{property}` (e.g. `--button_color`, `--card_shadow--default`, `--input_radius`). Variant-specific overrides append a variant suffix: `--alert_bg--success`, `--badge_text--error`. Hover/active state overrides append a state suffix: `--button_bg--hover`, `--dropdown_item-bg--hover`.
+
+**Discovering available overrides**:
+- **MCP server**: call `ds_get_component` -- it returns all overridable CSS custom properties with their default fallbacks.
+- **Source**: read the component's `.module.css` file and look for `var(--{component}_...)` calls.
+
+Internal coordination variables (set via inline styles in the TSX, such as `--control_count`, `--control_selected-index`, `--slider_fill`, `--fieldGroup_field-count`) are **not** part of the override surface -- they are implementation details.
+
+> A `@token` annotation convention for explicit declaration of the override surface may be added in the future.
+
 ### bdc border tokens
 
 Components use `box-shadow: inset` (not `outline` or `border`) for all visual frame edges via `--bdc_*` tokens defined in `src/css/bdc.css`. This keeps `outline` exclusively for `:focus-visible` rings. Set local values on the component rule:
@@ -173,6 +187,34 @@ box-shadow: var(--component_focus-ring, 0 0 0 2px rgb(from var(--bds-color_inter
 ```
 Error focus rings substitute `--bds-color_error` for `--bds-color_interactive`.
 
+### Semantic vs raw token layers
+
+The foundation token set (`--bds-*`) contains two conceptual layers. Understanding the distinction helps component authors choose the right token and keeps the override surface predictable.
+
+**Raw scale tokens** (implementation detail, subject to change between minor versions):
+- Space scale: `--bds-space_xxs`, `--bds-space_xs`, `--bds-space_s`, `--bds-space_m`, `--bds-space_l`, `--bds-space_xl`, `--bds-space_xxl`
+- Border radius scale: `--bds-border_radius--xs`, `--bds-border_radius--s`, `--bds-border_radius--m`, `--bds-border_radius--full`, `--bds-border_radius--circle`
+- Shadow elevation scale: `--bds-shadow_s`, `--bds-shadow_m`, `--bds-shadow_l`, `--bds-shadow_xl`, `--bds-shadow_2xl`
+- Font size scale: `--bds-font_size--body--s`, `--bds-font_size--body`, `--bds-font_size--heading-3`, etc.
+
+**Semantic tokens** (stable API, encode design decisions):
+- Colour roles: `--bds-color_interactive`, `--bds-color_error`, `--bds-color_bg`, `--bds-color_on-bg`, `--bds-color_success`, `--bds-color_warning`
+- Active state: `--bdc-color_active`, `--bdc-color_on-active`, `--bdc-color_active--subtle`
+- Layout: `--bds-grid_gap`, `--bds-grid_template-columns`, `--bds-container_max-width`
+- Focus: `--bds-outline_default`, `--bds-outline_color`, `--bds-outline_offset`
+
+**Recommendation for component authors**:
+- Prefer semantic tokens over raw scale tokens where a semantic equivalent exists (e.g. use `--bds-color_interactive` not a specific blue palette token).
+- When referencing a raw scale token, wrap it inside a component-local variable so the value can be overridden without depending on the scale:
+  ```css
+  /* correct — consumer can override --card_padding without knowing the scale */
+  padding: var(--card_padding, var(--bds-space_m));
+
+  /* avoid — locks the consumer into the foundation scale */
+  padding: var(--bds-space_m);
+  ```
+- This two-level fallback pattern (`--component_property, --bds-scale_token`) keeps the component API stable even if the foundation scale changes.
+
 ## Import paths
 
 ```ts
@@ -265,6 +307,64 @@ Key patterns:
 7. Meet all accessibility requirements listed above
 8. After changes: `pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm lint:css`, `pnpm test`
 
+## Component token API surface
+
+Component-local CSS custom properties are **public API**. They form the theming and override surface that consumers depend on.
+
+**Versioning rules**:
+- **Removing or renaming** a component token is a **BREAKING CHANGE** requiring a major version bump.
+- **Adding** a new component token is a minor or patch change (additive, non-breaking).
+- **Changing a token's default fallback** is a minor change if it alters visual output, patch if corrective.
+
+The following table lists every component-local token extracted from `src/components/**/*.module.css`. Tokens prefixed with `--bds-*` (foundation) and `--bdc*` (shared border system) are excluded -- those are owned by the foundation or `bdc.css`, not by individual components. Internal coordination variables set via inline styles in TSX are also excluded.
+
+| 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` |
+| 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` |
+| 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` |
+| 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` |
+| Grid | `--grid_gap`, `--grid_columns` |
+| IconWrapper | `--icon-wrapper-radius`, `--icon-wrapper-color`, `--icon-wrapper_on-color` |
+| 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` |
+| 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` |
+| 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.
+
 ## MCP server
 
 A live version of this design system is available as an MCP server at: