@boostdev/design-system-components 2.12.1 → 2.14.0

package/dist/web-components/index.js

@@ -63,7 +63,7 @@ import {
 } from "./chunk-WIBAN7KP.js";
 import {
   BdsTabs
-} from "./chunk-F3ZDNHZZ.js";
+} from "./chunk-Z3BPJNEL.js";
 import {
   BdsToastProvider
 } from "./chunk-HRD3NOA3.js";
@@ -78,7 +78,7 @@ import {
 } from "./chunk-PXPPKCLT.js";
 import {
   BdsAccordionItem
-} from "./chunk-YFAXGRPR.js";
+} from "./chunk-6ZNQPSQJ.js";
 import {
   BdsButton
 } from "./chunk-XIZWAWMJ.js";
@@ -90,7 +90,7 @@ import {
 } from "./chunk-Z7XTADXX.js";
 import {
   BdsDrawer
-} from "./chunk-FUQEFHRC.js";
+} from "./chunk-SOYAOLKR.js";
 import {
   BdsDropdownMenu
 } from "./chunk-IDSM74LM.js";
@@ -112,13 +112,13 @@ import {
 import "./chunk-QPOKHLMQ.js";
 import {
   BdsSeparator
-} from "./chunk-SFZ6Q4BP.js";
+} from "./chunk-5HUAFCU6.js";
 import {
   BdsSkeleton
 } from "./chunk-EF7IVYTY.js";
 import {
   BdsTable
-} from "./chunk-JMCXAAFK.js";
+} from "./chunk-HBLJ4SLY.js";
 import {
   BdsCalendar,
   buildMonthGrid,

package/dist/web-components/interaction/bds-accordion-item.js

@@ -1,6 +1,6 @@
 import {
   BdsAccordionItem
-} from "../chunk-YFAXGRPR.js";
+} from "../chunk-6ZNQPSQJ.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsAccordionItem

package/dist/web-components/interaction/bds-drawer.js

@@ -1,6 +1,6 @@
 import {
   BdsDrawer
-} from "../chunk-FUQEFHRC.js";
+} from "../chunk-SOYAOLKR.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsDrawer

package/dist/web-components/interaction/bds-tabs.js

@@ -1,6 +1,6 @@
 import {
   BdsTabs
-} from "../chunk-F3ZDNHZZ.js";
+} from "../chunk-Z3BPJNEL.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsTabs

package/dist/web-components/ui/bds-separator.js

@@ -1,6 +1,6 @@
 import {
   BdsSeparator
-} from "../chunk-SFZ6Q4BP.js";
+} from "../chunk-5HUAFCU6.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsSeparator

package/dist/web-components/ui/bds-table.js

@@ -1,6 +1,6 @@
 import {
   BdsTable
-} from "../chunk-JMCXAAFK.js";
+} from "../chunk-HBLJ4SLY.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsTable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.12.1",
+  "version": "2.14.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",
@@ -338,7 +338,7 @@
     "changelog:unreleased": "pnpm exec git-cliff --unreleased"
   },
   "devDependencies": {
-    "@boostdev/design-system-foundation": "^2.2.0",
+    "@boostdev/design-system-foundation": "^2.3.0",
     "@boostdev/design-system-react-native": "0.2.0",
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@storybook/addon-docs": "8.6.14",

package/src/components/interaction/Drawer/Drawer.mdx

@@ -38,6 +38,7 @@ Slide-in panel from the left or right edge of the viewport. Use for navigation,
 <tbody>
 <tr><td>`--drawer_color`</td><td>`var(--bds-color_bg)`</td><td>Panel background colour</td></tr>
 <tr><td>`--drawer_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Text colour</td></tr>
+<tr><td>`--drawer_border-color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Header rule colour — the non-text member of the colour set (≥ 3:1)</td></tr>
 <tr><td>`--drawer_shadow`</td><td>`var(--bds-shadow_xl)`</td><td>Panel drop shadow</td></tr>
 <tr><td>`--drawer_close-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Close button border radius</td></tr>
 <tr><td>`--drawer_close-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Close button background on hover</td></tr>

package/src/components/interaction/Drawer/Drawer.module.css

@@ -98,7 +98,7 @@
     align-items: center;
     justify-content: space-between;
     padding: var(--bds-space_m) var(--bds-space_l);
-    border-block-end: 1px solid currentcolor;
+    border-block-end: 1px solid var(--drawer_border-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_on-bg))));
     flex-shrink: 0;
   }
 

package/src/components/interaction/DropdownMenu/DropdownMenu.mdx

@@ -46,6 +46,7 @@ Floating menu with a list of selectable actions, triggered by a button. Supports
 <tr><td>`--dropdown_color`</td><td>`var(--bds-color_bg)`</td><td>Menu background colour</td></tr>
 <tr><td>`--dropdown_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Menu text colour</td></tr>
 <tr><td>`--dropdown_shadow`</td><td>`var(--bds-shadow_m)`</td><td>Menu box shadow</td></tr>
+<tr><td>`--dropdown_separator-color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Separator line colour — the non-text member of the colour set (≥ 3:1)</td></tr>
 <tr><td>`--dropdown_item-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Menu item background on hover</td></tr>
 <tr><td>`--dropdown_item-color--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Menu item text colour on hover</td></tr>
 </tbody>

package/src/components/interaction/DropdownMenu/DropdownMenu.module.css

@@ -31,9 +31,8 @@
 
   .separator {
     border: none;
-    border-block-start: 1px solid currentcolor;
+    border-block-start: 1px solid var(--dropdown_separator-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_on-bg))));
     margin: var(--bds-space_xxs) 0;
-    opacity: 0.15;
   }
 
   .item {

package/src/components/ui/Accordion/Accordion.mdx

@@ -43,6 +43,7 @@ Vertically stacked sections that can be expanded and collapsed independently.
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
+<tr><td>`--accordion_divider-color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Colour of the rule between items — the non-text member of the colour set (≥ 3:1), not a ground colour</td></tr>
 <tr><td>`--accordion_border`</td><td>`none`</td><td>Container border</td></tr>
 <tr><td>`--accordion_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Container corner radius</td></tr>
 <tr><td>`--accordion_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Container box-shadow tail (layered after the frame border)</td></tr>

package/src/components/ui/Accordion/Accordion.module.css

@@ -13,7 +13,7 @@
   }
 
   .item {
-    border-block-end: 1px solid var(--bds-color_bg--subtle);
+    border-block-end: 1px solid var(--accordion_divider-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_bg--subtle))));
   }
 
   .item:last-child {

package/src/components/ui/Separator/Separator.mdx

@@ -33,7 +33,7 @@ Visual divider between content sections. Renders a semantic `<hr>` (horizontal)
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--separator_color`</td><td>`var(--bds-color_on-bg)`</td><td>Line colour</td></tr>
+<tr><td>`--separator_color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Line colour. A separator is not text, so it takes the non-text member of the colour set (≥ 3:1) rather than the text colour. Falls back to `--bds-color_on-bg--border` and then `--bds-color_on-bg` on foundations older than 2.3.0.</td></tr>
 <tr><td>`--separator_thickness`</td><td>`1px`</td><td>Line thickness (height for horizontal, width for vertical)</td></tr>
 <tr><td>`--separator_length`</td><td>`1em`</td><td>Minimum height of the vertical separator when rendered outside a flex/grid container. Inside a flex or grid container the separator still stretches to fill the cross axis (`align-self: stretch`) — this token only sets a floor for standalone usage.</td></tr>
 </tbody>

package/src/components/ui/Separator/Separator.module.css

@@ -1,7 +1,7 @@
 @layer boostdev.component {
   .separator {
     border: none;
-    background-color: var(--separator_color, var(--bds-color_on-bg));
+    background-color: var(--separator_color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_on-bg))));
   }
 
   .separator.--horizontal {

package/src/components/ui/Table/Table.mdx

@@ -40,6 +40,7 @@ Data table with optional sortable columns and caption.
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
+<tr><td>`--table_divider-color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Colour of the header underline and the row rules — the non-text member of the colour set (≥ 3:1), not a ground colour</td></tr>
 <tr><td>`--table_border`</td><td>`none`</td><td>Container border</td></tr>
 <tr><td>`--table_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Container corner radius</td></tr>
 <tr><td>`--table_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Container frame shadow (appended to the inset border box-shadow)</td></tr>

package/src/components/ui/Table/Table.module.css

@@ -41,7 +41,7 @@
     font-size: var(--table_header-font-size, var(--bds-font_size--body--s));
     color: var(--bds-color_on-bg--subtle);
     white-space: nowrap;
-    border-block-end: 1px solid var(--bds-color_bg--subtle);
+    border-block-end: 1px solid var(--table_divider-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_bg--subtle))));
   }
 
   .th.--sortable {
@@ -92,7 +92,7 @@
   }
 
   .tbody .tr {
-    border-block-end: 1px solid var(--bds-color_bg--subtle);
+    border-block-end: 1px solid var(--table_divider-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_bg--subtle))));
     transition: var(--bds-animation_transition);
   }
 

package/src/components/ui/Tabs/Tabs.mdx

@@ -74,6 +74,7 @@ Defaults: hover/active text resolves to `--bds-color_interactive_on-bg`; active
 </thead>
 <tbody>
 <tr><td>`--tab_padding`</td><td>`var(--bds-space_s) var(--bds-space_m)`</td><td>Padding of each tab button.</td></tr>
+<tr><td>`--tabs_divider-color`</td><td>`var(--bds-color_on-bg--as-surface)`</td><td>Colour of the rail under the tablist — the non-text member of the colour set (≥ 3:1), not a ground colour</td></tr>
 <tr><td>`--tabs_gap`</td><td>`var(--bds-space_xxs)`</td><td>Gap between tab buttons in the tablist.</td></tr>
 <tr><td>`--tabs_panel-padding`</td><td>`var(--bds-space_m)`</td><td>Block-start padding of the active panel.</td></tr>
 </tbody>

package/src/components/ui/Tabs/Tabs.module.css

@@ -6,7 +6,7 @@
 
   .tabList {
     display: flex;
-    border-block-end: 1px solid var(--bds-color_bg--subtle);
+    border-block-end: 1px solid var(--tabs_divider-color, var(--bds-color_on-bg--as-surface, var(--bds-color_on-bg--border, var(--bds-color_bg--subtle))));
     gap: var(--tabs_gap, var(--bds-space_xxs));
   }
 

package/src/stories/DesignSystem/Colors.mdx

@@ -56,6 +56,20 @@ Every colour token comes in surface–content pairs: for every `--bds-color_*` t
 }
 ```
 
+A set has a third member for anything you place on the surface that is **not** text — a divider, a
+hairline, a decorative fill. Those need 3:1, not 4.5:1, and a text-grade colour on a one-pixel rule
+shouts:
+
+```css
+.card    { background-color: var(--bds-color_primary); }
+.card h3 { color:            var(--bds-color_on-primary); }             /* text */
+.card hr { background-color: var(--bds-color_on-primary--as-surface); } /* not text */
+```
+
+`--as-surface` ships on `bg`, `primary`, `secondary` and `accent-1..3`. See
+[Token sets](?path=/docs/design-system-token-sets--docs) for why this decision belongs in the token
+layer rather than at the call site.
+
 ## Semantic colours
 
 These are the tokens you should use in component CSS. They adapt automatically to light and dark mode.

package/src/stories/DesignSystem/Overview.mdx

@@ -8,6 +8,9 @@ import { Meta } from '@storybook/blocks';
 It provides a complete set of CSS custom properties for colour, spacing, typography, grid, elevation, and motion —
 all responsive and theme-aware out of the box.
 
+New to the token layer? [Token sets](?path=/docs/design-system-token-sets--docs) explains the one
+rule the rest depends on: colours ship as sets, never as single values.
+
 ## Installation
 
 ```bash

package/src/stories/DesignSystem/TokenSets.mdx

@@ -0,0 +1,291 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Token sets" />
+
+export const Panel = ({ children, tone = 'neutral' }) => (
+  <div style={{
+    border: '1px solid var(--bds-color_on-bg--as-surface)',
+    borderRadius: 'var(--bds-border_radius--m)',
+    padding: '1rem',
+    background: tone === 'bad' ? 'var(--bds-color_error--subtle)' : tone === 'good' ? 'var(--bds-color_success--subtle)' : 'var(--bds-color_bg--subtle)',
+    color: tone === 'bad' ? 'var(--bds-color_on-error--subtle)' : tone === 'good' ? 'var(--bds-color_on-success--subtle)' : 'var(--bds-color_on-bg)',
+  }}>
+    {children}
+  </div>
+);
+
+export const Split = ({ children }) => (
+  <div style={{ display: 'grid', gap: '1rem', gridTemplateColumns: 'repeat(auto-fit, minmax(16rem, 1fr))', marginBlock: '1.5rem' }}>
+    {children}
+  </div>
+);
+
+export const Caption = ({ children }) => (
+  <div style={{ fontSize: '0.75rem', fontFamily: 'monospace', opacity: 0.7, marginBlockStart: '0.5rem' }}>
+    {children}
+  </div>
+);
+
+export const Notice = ({ surface, content, label }) => (
+  <div>
+    <div style={{ background: `var(${surface})`, color: `var(${content})`, padding: '1rem', borderRadius: 'var(--bds-border_radius--m)' }}>
+      <strong style={{ display: 'block', marginBlockEnd: '0.25rem' }}>Delivery confirmed</strong>
+      <span style={{ fontSize: '0.875rem' }}>Your parcel is on its way to Amersfoort.</span>
+    </div>
+    <Caption>{label}</Caption>
+  </div>
+);
+
+export const OnSurfaceDemo = ({ mark, label }) => (
+  <div>
+    <div style={{ background: 'var(--bds-color_primary)', color: 'var(--bds-color_on-primary)', padding: '1rem', borderRadius: 'var(--bds-border_radius--m)' }}>
+      <strong style={{ display: 'block' }}>Included in your plan</strong>
+      <hr style={{ border: 'none', blockSize: '1px', background: `var(${mark})`, marginBlock: '0.75rem' }} />
+      <span style={{ fontSize: '0.875rem' }}>Unlimited storage · Priority support</span>
+    </div>
+    <Caption>{label}</Caption>
+  </div>
+);
+
+# Token sets
+
+Every colour in this library was chosen by someone. The only question is when, and by whom.
+
+The designer can choose once, in the system: which roles exist, what they are called, and which
+content colour belongs on which surface. Or the developer chooses again on every call site, inside
+a component, under time pressure. That mostly goes well — and "mostly" is exactly the problem.
+
+This page is about the first option: how to record colour decisions so they do not have to be
+made again.
+
+## Using a token is not enough
+
+Both colours below come from the system. On the token level there is nothing to object to:
+
+```css
+.button {
+  /* from the system */
+  background: var(--bds-color_secondary);
+
+  /* also a token, but chosen here on the spot */
+  color: var(--bds-color_white);
+}
+```
+
+Nothing about the surface says the text should be white. Somebody decided that at the call site,
+and it holds until the brand colour moves one shade. Then every place where someone picked their
+own text colour has to be visited again.
+
+<Split>
+  <Notice surface="--bds-color_secondary" content="--bds-color_white" label="--bds-color_white — 2.1:1, fails AA" />
+  <Notice surface="--bds-color_secondary" content="--bds-color_on-secondary" label="--bds-color_on-secondary — 10:1, passes AA" />
+</Split>
+
+Both panels use tokens. Only the right one takes its content colour from the set, and only the
+right one is legible. So the rule is not "use tokens" — it is **who picks the combination: the
+system, or the developer on that line**.
+
+## Think in sets, not in single values
+
+You never add a single colour to this system. You add a set: a surface, the colour that is legible
+on it, and the variant for anything you place on top that is not text.
+
+| Member | Naming | Requirement |
+|---|---|---|
+| Surface | `--bds-color_primary` | — |
+| Content on it | `--bds-color_on-primary` | ≥ 4.5:1 (text, icons) |
+| Non-text mark on it | `--bds-color_on-primary--as-surface` | ≥ 3:1, and quieter than the content colour |
+
+`on-` is a position, not a hue: `on-primary` is what lies on `primary`. Four things follow from that:
+
+- **There are no exceptions.** If you take a surface from the system, you take its content colour
+  from the same set. One exception and the guarantee is worth nothing.
+- **The set switches together.** In dark mode the surface changes along with its content, so the
+  contrast cannot break.
+- **It is not only about text.** Icons and borders sit on that same surface and belong to the same
+  set.
+- **Primitives have no partner.** `--bds-color_white` says which colour something is, not what it
+  is for — so there is nothing for it to pair with.
+
+## A name is a design decision
+
+The name travels further than the colour. What is called `primary` in Figma is called `primary` in
+the CSS; that name is the contract between design and code.
+
+| Name | What goes wrong |
+|---|---|
+| `blue-500` | Says which colour it is, not what it is for. After a restyle the name is a lie. |
+| `button-color` | Too specific. The moment the same colour is needed on a label, somebody invents a second token. |
+| `color-2` | Says nothing. Everyone has to look it up, so everyone guesses. |
+| `primary` | Says which role the colour plays. Works on a button, a label and a border, and survives a restyle. |
+
+Renaming is expensive — a token name lives in Figma, in the code and in the documentation — so the
+naming happens early, and it is the designer's work, not the developer's.
+
+## `--as-surface`: the requirement follows from what you place
+
+`on-primary` is text-grade: high contrast, because letters may sit on it. But a divider, a badge or
+a decorative block is not text. WCAG asks 3:1 for non-text contrast, not 4.5:1 — and a text-grade
+colour on a one-pixel rule shouts.
+
+That is the third member of the set. Same set, different requirement, because you are placing
+something else:
+
+```css
+/* Text on primary: 4.5:1 required */
+.card    { background: var(--bds-color_primary); }
+.card h3 { color:      var(--bds-color_on-primary); }
+
+/* A mark on primary: 3:1 is enough */
+.card hr,
+.card .badge {
+  background: var(--bds-color_on-primary--as-surface);
+}
+```
+
+<Split>
+  <OnSurfaceDemo mark="--bds-color_on-primary" label="--bds-color_on-primary — text-grade, loud on a 1px rule" />
+  <OnSurfaceDemo mark="--bds-color_on-primary--as-surface" label="--bds-color_on-primary--as-surface — calmer, still ≥ 3:1" />
+</Split>
+
+The requirement follows from **what** you place, not from **who** places it. That saves another
+decision at the call site — which is why `Separator`, the `DropdownMenu` divider and the `Drawer`
+header rule all take `--as-surface` rather than a hand-rolled opacity over the text colour.
+
+`--as-surface` exists on the base rung of `bg`, `primary`, `secondary` and `accent-1..3`. It is a
+partner of the content side, so it is named `on-<x>--as-surface` and never on the surface side.
+One level deep, no further: beyond that it is design work, and the system covers the ordinary case.
+
+## Primitives do not leak into the CSS
+
+The source is JSON, not CSS — one machine-readable file in the W3C DTCG format, which Figma can
+import and export as well, so both sides can work from one source. Agree on which side holds the
+truth: Figma-first or code-first, both are fine, just not both at once.
+
+The generator is not a source but a translator. JSON in, CSS out, with the value already resolved:
+
+```jsonc
+// tokens/color/semantic.light.dtcg.json — the source
+{
+  "on-primary": {
+    "DEFAULT":    { "$type": "color", "$value": "{color.black}" },
+    "as-surface": { "$type": "color", "$value": "{color.blue.950}" }
+  }
+}
+```
+
+```css
+/* color.semantic.css — generated, this is what ships */
+:root {
+  --bds-color_on-primary: #000;
+  --bds-color_on-primary--as-surface: #162456;
+}
+
+/* The palette step does not exist here.
+   The reference was resolved at build time. */
+```
+
+What is not there cannot be used. No one has to agree on it or review it — reaching for a raw
+palette value is simply not possible at runtime.
+
+## The build guards the contrast
+
+Because the coupling sits in the naming, the pairs can be derived mechanically. Your token list
+*is* your test list — there is nothing separate to maintain:
+
+```ts
+// every on-<x> pairs with <x>          → ≥ 4.5:1
+// every on-<x>--as-surface pairs with <x> → ≥ 3:1
+const pairs = deriveContrastPairs(tokens);
+
+test.each(pairs)('$name meets its band', ({ a, b, band }) => {
+  expect(contrastRatio(map[a], map[b])).toBeGreaterThanOrEqual(band);
+});
+```
+
+Accessibility then stops being a finding in a report and becomes something the system checks about
+itself. Two notes on that:
+
+- **A rule like this is only enforceable once the coupling is in the naming.** "Every new
+  `--bds-color_X` needs a `--bds-color_on-X` that passes AA" is a test you can write; "please
+  remember to check contrast" is not.
+- **Your contrast checker can lie to you.** The common Figma plugins compute WCAG 2, and that
+  formula underrates saturated colours. Black on bright blue gets a green tick at 5.6:1 and still
+  reads poorly. For vivid colours, verify with APCA.
+
+## A different theme touches one layer only
+
+Components refer to semantic names. Those names do not change — only their values do:
+
+```css
+/* 1. Default: light */
+:root {
+  --bds-color_bg:    var(--neutral-white);
+  --bds-color_on-bg: var(--neutral-black);
+}
+
+/* 2. OS is dark and nobody explicitly chose light */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { … }
+}
+
+/* 3. Explicit choice. Beats the OS. */
+:root[data-theme="dark"] { … }
+```
+
+Mind the order: the media query comes **before** the manual choice, otherwise the OS overrules what
+the user set themselves. Surface and content come from the same theme block, so the guarantee
+travels into dark mode with them. None of this appears in your component.
+
+## The pattern is wider than colour
+
+A token set is not a naming trick. It is the acknowledgement that some values only make sense
+together — one without the other produces a wrong result. Typography is the clearest second case:
+
+```css
+/* Loose: three knobs, three chances to get it wrong */
+.title {
+  font-size:      var(--bds-font_size--heading-1);
+  line-height:    1.2;     /* invented here */
+  letter-spacing: -0.02em; /* invented here */
+}
+
+/* As a set: one decision with a name */
+.title {
+  font-size:      var(--bds-font_size--heading-1);
+  line-height:    var(--bds-font_line-height--heading);
+  letter-spacing: var(--bds-font_tracking--tight);
+}
+```
+
+A font size without its line height gives a broken rhythm; a display size at default tracking looks
+sloppy. Other candidates: a shadow that belongs to an elevation level, an icon size that belongs to
+a touch target. Same rule of thumb — ship them as a unit, because whatever can be set separately
+will eventually be set separately.
+
+## Who decides what
+
+<Split>
+  <Panel>
+    <strong>The designer</strong>
+    <p style={{ margin: '0.5rem 0 0' }}>Which roles exist, what they are called, and which content colour belongs on which surface. That last one is a design decision, not an implementation detail.</p>
+  </Panel>
+  <Panel>
+    <strong>The system</strong>
+    <p style={{ margin: '0.5rem 0 0' }}>That it cannot go wrong. The set is fixed, the contrast is tested, and the primitives are out of reach. What cannot be chosen cannot be chosen wrongly.</p>
+  </Panel>
+  <Panel>
+    <strong>The developer</strong>
+    <p style={{ margin: '0.5rem 0 0' }}>Which token fits here. Is this a warning or a confirmation? That is the question that remains — not which shade, and not which contrast.</p>
+  </Panel>
+</Split>
+
+A component in such a system picks no colour of its own. It asks for a semantic token and takes the
+content colour from the set, both from one source that design and code share. A new brand colour or
+a dark mode therefore costs not a single line inside the component.
+
+## Further reading
+
+- [Colours](?path=/docs/design-system-colors--docs) — the full token reference and palette
+- [Dark mode](?path=/docs/design-system-dark-mode--docs) — the three-state theming setup
+- [Typography](?path=/docs/design-system-typography--docs) — the type scale as sets

package/src/test/token-contract.spec.ts

@@ -84,3 +84,74 @@ describe('token contract', () => {
     }
   });
 });
+
+// Non-text marks — hairlines, dividers, decorative fills — take the `--as-surface`
+// member of the set (>= 3:1), never the text member (4.5:1) and never a
+// hand-rolled alpha over it. Foundations older than 2.3.0 fall back to
+// `--bds-color_on-bg--border`, which carries the same value under its old name.
+const NON_TEXT_MARKS: { file: string; rule: string }[] = [
+  { file: 'components/ui/Separator/Separator.module.css', rule: '.separator' },
+  { file: 'components/interaction/DropdownMenu/DropdownMenu.module.css', rule: '.separator' },
+  { file: 'components/interaction/Drawer/Drawer.module.css', rule: '.header' },
+  { file: 'components/ui/Accordion/Accordion.module.css', rule: '.item' },
+  { file: 'components/ui/Tabs/Tabs.module.css', rule: '.tabList' },
+  { file: 'components/ui/Table/Table.module.css', rule: '.th' },
+];
+
+describe('non-text marks use the as-surface member of the colour set', () => {
+  const srcRoot = join(__dirname, '../');
+
+  for (const { file, rule } of NON_TEXT_MARKS) {
+    it(`${file} ${rule}`, () => {
+      const css = readFileSync(join(srcRoot, file), 'utf-8');
+      const declaration = new RegExp(
+        `\\${rule}[^{]*{[^}]*var\\(--bds-color_on-bg--as-surface,\\s*var\\(--bds-color_on-bg--border,`,
+      );
+
+      expect(css, `${file} paints ${rule} without the as-surface fallback chain`).toMatch(
+        declaration,
+      );
+      expect(css, `${file} still softens ${rule} with a hand-rolled opacity`).not.toMatch(
+        new RegExp(`\\${rule}[^{]*{[^}]*opacity:`),
+      );
+    });
+  }
+});
+
+// A surface token on a hairline is the mirror of the same mistake: `bg--subtle`
+// on `bg` measures 1.10:1 in light and 1.72:1 in dark, well under the 3:1 a
+// non-text mark needs. Dividers must not be painted with a ground colour.
+// A ground colour is correct where the border is not separating anything: the
+// Loading spinner's ring is the track its coloured arc rotates against, and is
+// meant to recede. The contrast that matters there is arc-vs-track, not
+// track-vs-page.
+const GROUND_BORDER_EXEMPTIONS = ['Loading/Loading.module.css', 'bds-loading.ts'];
+
+describe('no component paints a hairline with a background token', () => {
+  const srcRoot = join(__dirname, '../');
+
+  it('component CSS and web component styles', () => {
+    const offenders: string[] = [];
+    const files = [
+      ...collectFiles(join(srcRoot, 'components'), '.module.css'),
+      ...collectFiles(join(srcRoot, 'web-components'), '.ts').filter((f) => !f.endsWith('.spec.ts')),
+    ];
+
+    for (const file of files) {
+      if (GROUND_BORDER_EXEMPTIONS.some((e) => file.endsWith(e))) continue;
+
+      const css = readFileSync(file, 'utf-8');
+      for (const [, side] of css.matchAll(
+        /border[\w-]*:\s*\d+px\s+solid\s+var\(--bds-color_(bg[\w-]*)\)/g,
+      )) {
+        offenders.push(`  --bds-color_${side} in ${relative(srcRoot, file)}`);
+      }
+    }
+
+    if (offenders.length > 0) {
+      expect.fail(
+        `Hairlines painted with a ground colour (needs --bds-color_on-X--as-surface):\n${offenders.join('\n')}`,
+      );
+    }
+  });
+});

package/src/web-components/interaction/BdsAccordion.mdx

@@ -79,6 +79,7 @@ Or in HTML without a bundler:
 
 | Property | Default | Description |
 |----------|---------|-------------|
+| `--accordion_divider-color` | `var(--bds-color_on-bg--as-surface)` | Colour of the rule between items — the non-text member of the colour set (≥ 3:1), not a ground colour |
 | `--accordion_border` | `none` | Container border |
 | `--accordion_radius` | `var(--bdc-outline_radius)` | Container corner radius |
 | `--accordion_shadow` | `var(--bdc-outline_shadow)` | Container box-shadow tail (layered after the frame border) |