@boostdev/design-system-components 2.13.0 → 2.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.13.0",
+  "version": "2.14.1",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",

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/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/TokenSets.mdx

@@ -149,8 +149,28 @@ something else:
 </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.
+decision at the call site — which is why every rule this library draws takes `--as-surface`:
+`Separator`, the `DropdownMenu` divider, the `Drawer` header rule, the line between `Accordion`
+items, the rail under the `Tabs` tablist, and the `Table`'s header underline and row rules. None of
+them softens a text colour with a hand-rolled opacity, and none picks a shade at the call site.
+
+### Both ways of getting it wrong
+
+Without a name for the non-text member, the two colours nearest to hand are the text colour and the
+ground colour — and both are wrong, in opposite directions. This library shipped one of each:
+
+| | On a 1px rule against `bg` | |
+|---|---|---|
+| `--bds-color_on-bg` (text) | 21:1 light, 16:1 dark | far too loud — reads as a hard edge |
+| `--bds-color_bg--subtle` (ground) | 1.1:1 light, 1.7:1 dark | far too faint — separates nothing |
+| `--bds-color_on-bg--as-surface` | 4.8:1 light, 6.8:1 dark | over the 3:1 band, under the text colour |
+
+The first is the tempting mistake, because the text colour is right there in the set and obviously
+visible. The second is the tidy-looking mistake, because a ground colour feels appropriately quiet.
+They come from the same gap: no third member, so the choice falls to whoever writes the line.
+
+Both directions are checked in CI, not by review. A hairline may not be painted with an
+`--bds-color_on-*` token, and it may not be painted with a `--bds-color_bg*` token either.
 
 `--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.

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

@@ -93,6 +93,9 @@ 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', () => {
@@ -114,3 +117,41 @@ describe('non-text marks use the as-surface member of the colour set', () => {
     });
   }
 });
+
+// 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) |

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

@@ -96,6 +96,7 @@ across every state; set `--tab_color--active` to theme only the selected tab.
 
 | Property | Description |
 |----------|-------------|
+| `--tabs_divider-color` | Colour of the rail under the tablist (default: `--bds-color_on-bg--as-surface`, the non-text member of the set — ≥ 3:1, not a ground colour) |
 | `--tab_color` | Tab text colour override (all states) |
 | `--tab_border-color` | Tab bottom-border colour override (all states) |
 | `--tab_color--active` | Text colour override for the selected tab |

package/src/web-components/interaction/bds-accordion-item.ts

@@ -39,7 +39,7 @@ export class BdsAccordionItem extends LitElement {
 
     :host {
       display: block;
-      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))));
     }
 
     :host(:last-child) {

package/src/web-components/interaction/bds-tabs.ts

@@ -43,7 +43,7 @@ export class BdsTabs extends LitElement {
 
     .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(--bds-space_xxs);
     }
   `;

package/src/web-components/ui/BdsTable.mdx

@@ -56,6 +56,7 @@ import '@boostdev/design-system-components/web-components';
 
 | Property | Description |
 |----------|-------------|
+| `--table_divider-color` | Colour of the header underline and row rules (default: `--bds-color_on-bg--as-surface`, the non-text member of the set — ≥ 3:1, not a ground colour) |
 | `--table_border` | Wrapper border (default: `none`) |
 | `--table_radius` | Wrapper corner radius (default: `var(--bdc-outline_radius)`, itself set to `var(--bds-border_radius--s)` on the wrapper) |
 | `--table_row-bg--hover` | Row background on hover, pointer devices only (default: `var(--bds-color_bg--subtle)`) |

package/src/web-components/ui/bds-table.ts

@@ -20,13 +20,13 @@ const tableLightDomCss = `
       font-size: var(--bds-font_size--body--s);
       text-align: start;
       color: var(--bds-color_on-bg--subtle);
-      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))));
       white-space: nowrap;
     }
 
     bds-table > table td {
       padding: var(--bds-space_s) var(--bds-space_m);
-      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))));
       vertical-align: middle;
     }