@boostdev/design-system-components 1.0.2 → 1.1.0

package/AGENTS.md

@@ -39,12 +39,12 @@ Component-scoped variables use **inline fallbacks**, not top-level declarations.
   border: 1px solid var(--input_border-color, currentcolor);
 }
 .input:focus {
-  --input_border-color: var(--bds-interactive);
+  --input_border-color: var(--bds-color_interactive);
 }
 
 /* ❌ wrong — declaring defaults at the element level */
 .input {
-  --input_border-color: var(--bds-on-bg);
+  --input_border-color: var(--bds-color_on-bg);
   border: 1px solid var(--input_border-color);
 }
 ```
@@ -73,7 +73,7 @@ Components use `outline` (not `border`) for all visual frame edges via `--bdc_*`
 }
 ```
 
-Focus state uses `--bdc_color--focus` (= `--bds-interactive`) for mouse focus, and `var(--bds-outline_default)` for `:focus-visible` keyboard focus.
+Focus state uses `--bdc_color--focus` (= `--bds-color_interactive`) for mouse focus, and `var(--bds-outline_default)` for `:focus-visible` keyboard focus.
 
 ### Two-level fallback for active/selected state
 
@@ -81,20 +81,22 @@ 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-active));
-border-color:     var(--checkbox_color-active, var(--bds-active));
-border: solid     var(--checkbox_color-on-active, var(--bds-on-active));
+background-color: var(--checkbox_color-active, var(--bds-color_green));
+border-color:     var(--checkbox_color-active, var(--bds-color_green));
+border: solid     var(--checkbox_color-on-active, var(--bdc-color_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)`.
+- Token names use `--bds-` prefix (e.g. `--bds-color_bg`, `--bds-space_m`). Color tokens always include the `color_` group segment: `var(--bds-color_bg)` not `var(--bds-bg)`. The old short names (without `color_`) exist as deprecated aliases and will be removed in the next major version.
 - Colour surfaces always pair with their `on-` content token
 - 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`)
+- Shadow: use elevation scale (`--bds-shadow_s` … `--bds-shadow_2xl`). Shadows use `--bds-shadow_color-rgb` internally — override this token to theme shadow colour.
 - Z-index: use named role tokens, never raw integers
+- Focus-visible outlines: use `--bds-outline_default` (2px dotted, adapts to dark mode). `--bds-outline_color` is the colour token; `--bds-outline_offset` is the offset (2px outside). These are distinct from the inset `--bdc-outline_*` border system.
+- Dark mode: foundation tokens adapt automatically via `[data-theme="dark"]` attribute or `prefers-color-scheme: dark`. No extra CSS needed in components.
 
 ### Semantic tokens for state colours
 
@@ -102,20 +104,20 @@ Prefer semantic tokens over palette tokens. Key tokens for component states:
 
 | Token | Meaning | Used in |
 |-------|---------|---------|
-| `--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 |
+| `--bdc-color_active` | Active / checked / filled state (= `--bds-color_green` 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 |
+| `--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_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:
 ```css
-box-shadow: var(--component_focus-ring, 0 0 0 2px rgb(from var(--bds-interactive) r g b / 20%));
+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-error` for `--bds-interactive`.
+Error focus rings substitute `--bds-color_error` for `--bds-color_interactive`.
 
 ## Import paths