@boostdev/design-system-components 1.1.2 → 1.2.0

package/AGENTS.md

@@ -92,7 +92,7 @@ For **border colours** that should match surrounding text/icon colour, use `curr
 
 ### 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:
+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:
 
 ```css
 .myElement {
@@ -100,19 +100,22 @@ Components use `outline` (not `border`) for all visual frame edges via `--bdc_*`
   --bdc_color: currentcolor;
   --bdc-outline_radius: var(--bds-border_radius--xs);
 
-  outline: var(--bdc-outline_width) solid var(--bdc_color);
-  outline-offset: var(--bdc-outline_offset);
   border-radius: var(--myComponent_radius, var(--bdc-outline_radius));
-  box-shadow: var(--myComponent_shadow, var(--bdc-outline_shadow));
+  box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color),
+              var(--myComponent_shadow, var(--bdc-outline_shadow));
   transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing);
 }
 
-.myElement:focus {
-  --bdc_color: var(--bdc_color--focus); /* transitions smoothly */
+.myElement:focus-visible {
+  outline: var(--bds-outline_default);
+  outline-offset: var(--bds-outline_offset);
 }
 ```
 
-Focus state uses `--bdc_color--focus` (= `--bds-color_interactive`) for mouse focus, and `var(--bds-outline_default)` for `:focus-visible` keyboard focus.
+- The `--bdc_color` `<color>` registered property enables smooth CSS transitions on the inset shadow colour.
+- 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`.
 
 ### Two-level fallback for active/selected state
 
@@ -192,10 +195,10 @@ References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https:/
 
 ## Key decisions
 
-- **Button variants**: `default` (filled) and `ghost` (transparent, outlined). Renamed from `primary`/`secondary`.
+- **Button variants**: `default` (filled) and `outline` (transparent, outlined). `ghost` is a deprecated alias for `outline` — use `outline` for new code.
 - **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-outline_width`, `--bdc-outline_offset`, `--bdc-outline_radius`, `--bdc-outline_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-outline_offset: -1px`** (inset) makes outline appear like a traditional inset border. Switch uses `var(--bds-outline_offset)` (2px outside) — keep distinct.
+- **`bdc` border token system**: All component frame borders use `box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color)` (not `outline` or `border`). `outline` is reserved exclusively for `:focus-visible` rings. `--bdc_color` is registered as `<color>` with `@property`, enabling smooth `transition: --bdc_color` animations. The neutral `--bdc-outline_shadow` default is `0 0 0 0 transparent` (not `none` — `none` breaks comma-separated box-shadow).
+- **Focus rings**: all components use `outline: var(--bds-outline_default)` + `outline-offset: var(--bds-outline_offset)` on `:focus-visible`. The `--bds-outline_default` is overridden in `bdc.css` to `2px solid var(--bds-color_interactive)` at 2px offset.
 - **Backdrop token**: `var(--color_backdrop, rgb(0 0 0 / 50%))` — never hardcode rgba. (`--color_backdrop` is a library hook token, not a foundation token.)
 - **`bds-popover` Invoker Commands API**: `<button commandfor="<id>" command="--toggle|--open|--close">` declaratively controls the popover. Handled via a `command` event listener on the host (light DOM) in `connectedCallback`/`disconnectedCallback`. Use an arrow-function handler for stable `removeEventListener` reference.
 - **State guard in open/close methods**: `_open()` and `_close()` on stateful web components must return early if already in the target state, to prevent dispatching redundant events to listeners.