@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/heading/heading.css.js

@@ -5,10 +5,21 @@ export default css`
     display: block;
   }
   @layer bd-components {
+    /* No vertical margin. A heading's spacing depends on what it sits above
+       and below, which this element cannot see, so it is the caller's to set —
+       through the padding and paddingBottom props, which resolve to spacing
+       steps in shared/token-scales.js. Six commented-out margin pairs used to
+       stand here recording an earlier answer; they were written with a //
+       prefix, which CSS does not recognise as a comment, so the parser was
+       discarding them through error recovery rather than honouring them.
+
+       The colour is set rather than inherited. Left to inherit, a heading took
+       whatever ink the page happened to carry, which is how bd-h, bd-display,
+       bd-p and bd-li ended up with four different blacks between them. */
     .bd-heading {
       margin: 0;
       padding: 0;
-      // color: var(--color-neutral-900);
+      color: var(--color-text-primary);
     }
 
     /* h1 */
@@ -18,8 +29,6 @@ export default css`
       line-height: var(--typography-heading-h1-lineHeight);
       letter-spacing: var(--typography-heading-h1-letterSpacing);
       font-family: var(--typography-heading-h1-fontFamily);
-      // margin-bottom: var(--spacing-24);
-      // margin-top: var(--spacing-32);
     }
 
     /* h2 */
@@ -29,8 +38,6 @@ export default css`
       line-height: var(--typography-heading-h2-lineHeight);
       letter-spacing: var(--typography-heading-h2-letterSpacing);
       font-family: var(--typography-heading-h2-fontFamily);
-      // margin-bottom: var(--spacing-20);
-      // margin-top: var(--spacing-28);
     }
 
     /* h3 */
@@ -40,8 +47,6 @@ export default css`
       line-height: var(--typography-heading-h3-lineHeight);
       letter-spacing: var(--typography-heading-h3-letterSpacing);
       font-family: var(--typography-heading-h3-fontFamily);
-      // margin-bottom: var(--spacing-16);
-      // margin-top: var(--spacing-24);
     }
 
     /* h4 */
@@ -51,8 +56,6 @@ export default css`
       line-height: var(--typography-heading-h4-lineHeight);
       letter-spacing: var(--typography-heading-h4-letterSpacing);
       font-family: var(--typography-heading-h4-fontFamily);
-      // margin-bottom: var(--spacing-12);
-      // margin-top: var(--spacing-20);
     }
 
     /* h5 */
@@ -62,8 +65,6 @@ export default css`
       line-height: var(--typography-heading-h5-lineHeight);
       letter-spacing: var(--typography-heading-h5-letterSpacing);
       font-family: var(--typography-heading-h5-fontFamily);
-      // margin-bottom: var(--spacing-8);
-      // margin-top: var(--spacing-16);
     }
 
     /* h6 */
@@ -73,10 +74,6 @@ export default css`
       line-height: var(--typography-heading-h6-lineHeight);
       letter-spacing: var(--typography-heading-h6-letterSpacing);
       font-family: var(--typography-heading-h6-fontFamily);
-      // margin-bottom: var(--spacing-6);
-      // margin-top: var(--spacing-12);
     }
-
-   
-
-`;
+  }
+`;

package/src/components/heading/heading.js

@@ -1,10 +1,26 @@
 import { LitElement, html } from "lit";
-import { tokens } from "../../tokens/tokens.js";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
 import headingCSS from "./heading.css.js";
+import {
+  spacingShorthand, spacing, fontWeight, color
+} from "../shared/token-scales.js";
 
 export class BdH extends LitElement {
   static properties = {
     as           : { type: String, reflect: true },
+    /**
+     * Which step of the heading type scale to render, when that has to differ
+     * from the semantic level. Defaults to following `as`, so passing nothing
+     * behaves exactly as before.
+     *
+     * The two were one axis: the tag chose the element AND the type scale, so
+     * a section that had to stop being an h1 for the document outline would
+     * have shrunk from 5xl to 4xl at the same time. Level is what the outline
+     * reads; size is what the page looks like, and they are not the same
+     * question. Accepts h1-h6 or 1-6.
+     */
+    visualLevel  : { type: String, attribute: "visual-level", reflect: true },
     ariaLevel    : { type: Number, attribute: "aria-level" },
     padding      : { type: String },
     paddingBottom: { type: String },
@@ -15,6 +31,7 @@ export class BdH extends LitElement {
   constructor() {
     super();
     this.as = "h1";
+    this.visualLevel = "";
     this.ariaLevel = null;
     this.padding = "";
     this.paddingBottom = "";
@@ -26,46 +43,44 @@ export class BdH extends LitElement {
     return ["h1", "h2", "h3", "h4", "h5", "h6"].includes(tag);
   }
 
-  _getValidFontWeight(weight) {
-    const validWeights = [
-      "100", "200", "300", "400", "500", "600", "700", "800", "900",
-      "normal", "bold", "lighter", "bolder"
-    ];
-    return validWeights.includes(weight) ? weight : "";
-  }
-
-  _getValidColor(color) {
-    if (!color) return "";
-    if (
-      color.startsWith("var(") ||
-      color.startsWith("#") ||
-      color.startsWith("rgb") ||
-      color.startsWith("hsl")
-    ) {
-      return color;
-    }
-    return "";
+  /** Accepts h1-h6 or a bare 1-6, and returns "" for anything else. */
+  _normaliseLevel(value) {
+    const v = String(value ?? "").trim()
+      .toLowerCase();
+    if (this._isValidHeadingTag(v)) return v;
+    return /^[1-6]$/.test(v) ? `h${v}` : "";
   }
 
+  /**
+   * Each prop is a step name, resolved to a token reference by
+   * shared/token-scales.js. A value that is not on its scale is dropped, so
+   * the heading keeps the styling its own CSS gives it.
+   */
   _computeStyles() {
-    const styles = [];
-
-    const validFontWeight = this._getValidFontWeight(this.fontWeight);
-    const validColor = this._getValidColor(this.color);
-
-    if (this.padding) styles.push(`padding: ${this.padding};`);
-    if (this.paddingBottom) styles.push(`padding-bottom: ${this.paddingBottom};`);
-    if (validFontWeight) styles.push(`font-weight: ${validFontWeight};`);
-    if (validColor) styles.push(`color: ${validColor};`);
+    const declarations = [
+      ["padding",        spacingShorthand(this.padding)],
+      ["padding-bottom", spacing(this.paddingBottom)],
+      ["font-weight",    fontWeight(this.fontWeight)],
+      ["color",          color(this.color)]
+    ];
 
-    return styles.join(" ");
+    return declarations
+      .filter(([, value]) => value)
+      .map(([property, value]) => `${property}: ${value};`)
+      .join(" ");
   }
 
 
   render() {
-    const tag = this._isValidHeadingTag(this.as) ? this.as : "h1";
+    /* An unrecognised `as` used to fall back to h1, so a typo produced a
+       page-level heading in a component that had no business owning one --
+       the loudest possible thing to get wrong silently. It falls back to h2
+       now: still a heading, never the page's. A missing `as` is unaffected,
+       because the property defaults to h1 and h1 is valid. */
+    const tag = this._normaliseLevel(this.as) || "h2";
+    const visual = this._normaliseLevel(this.visualLevel) || tag;
     const element = document.createElement(tag);
-    element.className = `bd-heading ${tag}`;
+    element.className = `bd-heading ${visual}`;
     if (this.ariaLevel) element.setAttribute("aria-level", this.ariaLevel);
 
     const styles = this._computeStyles();
@@ -76,7 +91,7 @@ export class BdH extends LitElement {
   }
 
 
-  static styles = [tokens, headingCSS];
+  static styles = [headingCSS];
 }
 
 customElements.define("bd-h", BdH);

package/src/components/heading/heading.stories.js

@@ -2,7 +2,7 @@ import { html } from 'lit';
 import './heading.js';
 
 export default {
-  title     : 'Components/Heading',
+  title     : 'Atoms/Heading',
   tags      : ['autodocs'],
   parameters: {
     docs: {
@@ -13,7 +13,7 @@ export default {
 ### Usage
 \`\`\`html
 <bd-h as="h1">Page Title</bd-h>
-<bd-h as="h3" color="#026DFF" font-weight="700" padding-bottom="16px">Section Title</bd-h>
+<bd-h as="h3" color="primary" fontWeight="bold" paddingBottom="16">Section Title</bd-h>
 \`\`\`
 
 ### Valid Heading Tags
@@ -45,23 +45,26 @@ export default {
     },
     padding: {
       control    : 'text',
-      description: 'CSS padding shorthand applied inline',
+      description: 'One to four spacing steps, e.g. `10 0`. Each part resolves to `var(--spacing-N)`; if any part is off the scale the whole value is dropped.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Spacing' }
     },
     paddingBottom: {
-      control    : 'text',
-      description: 'CSS padding-bottom applied inline',
+      control: { type: 'select' },
+      options: ['', ...['0', '1', '2', '4', '6', '8', '10', '12', '14', '16', '18', '20', '22', '24',
+        '28', '32', '36', '40', '44', '48', '52', '56', '64', '80', '96', '112', '128']],
+      description: 'A spacing step. Resolves to `var(--spacing-N)`.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Spacing' }
     },
     fontWeight: {
       control    : { type: 'select' },
-      options    : ['', '100', '200', '300', '400', '500', '600', '700', '800', '900', 'normal', 'bold', 'lighter', 'bolder'],
-      description: 'Font weight applied inline. Invalid values are ignored.',
+      options    : ['', 'light', 'normal', 'medium', 'semibold', 'bold'],
+      description: 'A weight step. Resolves to `var(--typography-fontWeight-*)`. The scale stops at `bold` (700) — there is no 800 or 900.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Typography' }
     },
     color: {
-      control    : 'color',
-      description: 'Text color. Must be a hex, rgb, hsl, or var() value.',
+      control    : { type: 'select' },
+      options    : ['', ...['primary', 'strong', 'muted', 'subtle', 'inverse', 'success', 'warning', 'error']],
+      description: 'A semantic colour role, not a CSS colour. Resolves to a palette token; anything else is dropped.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Typography' }
     }
   }
@@ -108,10 +111,10 @@ export const CustomColor = {
   name  : 'Custom Color',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:12px;">
-      <bd-h as="h2" color="#026DFF">Blue Heading</bd-h>
-      <bd-h as="h2" color="#E53935">Red Heading</bd-h>
-      <bd-h as="h2" color="#43A047">Green Heading</bd-h>
-      <bd-h as="h2" color="var(--color-neutral-1000)">Token Color</bd-h>
+      <bd-h as="h2" color="primary">primary — var(--color-blue-600)</bd-h>
+      <bd-h as="h2" color="error">error — var(--color-red-700)</bd-h>
+      <bd-h as="h2" color="success">success — var(--color-green-800)</bd-h>
+      <bd-h as="h2" color="strong">strong — var(--color-neutral-900)</bd-h>
     </div>
   `,
   parameters: { docs: { description: { story: 'Headings with hex colors and a CSS variable token. Bare color names like "blue" are rejected by `_getValidColor()`.' } } }
@@ -121,12 +124,11 @@ export const FontWeights = {
   name  : 'Font Weights',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:8px;">
-      <bd-h as="h3" fontWeight="300">Light (300)</bd-h>
-      <bd-h as="h3" fontWeight="400">Regular (400)</bd-h>
-      <bd-h as="h3" fontWeight="600">Semibold (600)</bd-h>
-      <bd-h as="h3" fontWeight="700">Bold (700)</bd-h>
-      <bd-h as="h3" fontWeight="800">Extrabold (800)</bd-h>
-      <bd-h as="h3" fontWeight="900">Black (900)</bd-h>
+      <bd-h as="h3" fontWeight="light">light (300)</bd-h>
+      <bd-h as="h3" fontWeight="normal">normal (400)</bd-h>
+      <bd-h as="h3" fontWeight="medium">medium (500)</bd-h>
+      <bd-h as="h3" fontWeight="semibold">semibold (600)</bd-h>
+      <bd-h as="h3" fontWeight="bold">bold (700)</bd-h>
     </div>
   `,
   parameters: { docs: { description: { story: 'Various font weights from light (300) to black (900). Invalid weights like "purple" are silently ignored.' } } }
@@ -136,10 +138,10 @@ export const CustomPadding = {
   name  : 'Custom Padding',
   render: () => html`
     <div style="outline:1px solid #eee; display:inline-block;">
-      <bd-h as="h3" padding="24px 40px">With Full Padding</bd-h>
+      <bd-h as="h3" padding="24 40">With Full Padding</bd-h>
     </div>
     <div style="outline:1px solid #eee; display:inline-block; margin-top:16px;">
-      <bd-h as="h3" paddingBottom="32px">With Padding Bottom Only</bd-h>
+      <bd-h as="h3" paddingBottom="32">With Padding Bottom Only</bd-h>
     </div>
   `,
   parameters: { docs: { description: { story: 'Demonstrates `padding` shorthand and `paddingBottom` applied inline.' } } }
@@ -151,7 +153,7 @@ export const AriaLevelOverride = {
     <p style="font-size:14px; margin-bottom:8px;">
       Visually renders as <code>h4</code> but has <code>aria-level="2"</code>.
     </p>
-    <bd-h as="h4" aria-level="2" color="#026DFF">
+    <bd-h as="h4" aria-level="2" color="primary">
       Visually h4, semantically level 2
     </bd-h>
   `,
@@ -169,8 +171,8 @@ export const InvalidTag = {
 export const InvalidColor = {
   name  : 'Invalid Color (silently ignored)',
   render: () => html`
-    <bd-h as="h3" color="blue">This uses the default color (blue is rejected)</bd-h>
-    <bd-h as="h3" color="#026DFF">This uses valid hex color</bd-h>
+    <bd-h as="h3" color="blue">A bare CSS keyword is not a role, so it is dropped and the heading keeps its own colour</bd-h>
+    <bd-h as="h3" color="primary">color="primary" resolves to var(--color-blue-600)</bd-h>
   `,
   parameters: { docs: { description: { story: 'Bare color name `"blue"` is rejected by `_getValidColor()` and falls back to the default color. `"#026DFF"` is accepted.' } } }
 };
@@ -178,7 +180,7 @@ export const InvalidColor = {
 export const Combined = {
   name  : 'Combined Props',
   render: () => html`
-    <bd-h as="h2" color="#026DFF" fontWeight="800" paddingBottom="16px">
+    <bd-h as="h2" color="primary" fontWeight="bold" paddingBottom="16">
       World-class security software
     </bd-h>
   `,

package/src/components/help-text/help-text.css.js

@@ -0,0 +1,21 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const helpTextCSS = css`
+  :host { display: block; margin-top: var(--form-help-text-default-marginTop); }
+
+  p {
+    margin: 0;
+    font-family: var(--form-help-text-default-fontFamily);
+    font-size: var(--form-help-text-default-fontSize);
+    font-weight: var(--form-help-text-default-fontWeight);
+    line-height: var(--form-help-text-default-lineHeight);
+    letter-spacing: var(--form-help-text-default-letterSpacing);
+    color: var(--form-help-text-default-color);
+  }
+
+  :host([tone='error']) p   { color: var(--form-help-text-error-color); }
+  :host([tone='success']) p { color: var(--form-help-text-success-color); }
+`;
+
+export default helpTextCSS;

package/src/components/help-text/help-text.js

@@ -0,0 +1,25 @@
+import { LitElement, html, nothing } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { helpTextCSS } from './help-text.css.js';
+
+export class BdHelpText extends LitElement {
+  static styles = [helpTextCSS];
+
+  static properties = {
+    tone: { type: String, reflect: true }
+  };
+
+  constructor() {
+    super();
+    this.tone = 'default';
+  }
+
+  render() {
+    return html`
+      <p role=${this.tone === 'error' ? 'alert' : nothing}><slot></slot></p>
+    `;
+  }
+}
+
+customElements.define('bd-help-text', BdHelpText);

package/src/components/help-text/help-text.stories.js

@@ -0,0 +1,66 @@
+import { html } from 'lit';
+import './help-text.js';
+
+export default {
+  title     : 'Atoms/Help Text',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdHelpText** is the small line under a form field — a hint, a format
+requirement, or a validation message.
+
+### Usage
+\`\`\`html
+<bd-label for="pw">Password</bd-label>
+<input id="pw" type="password">
+<bd-help-text>At least 12 characters.</bd-help-text>
+
+<bd-help-text tone="error">That password is too short.</bd-help-text>
+<bd-help-text tone="success">Strong password.</bd-help-text>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`tone\` | \`default\`, \`success\`, \`error\` | \`default\` |
+
+### Accessibility
+\`tone="error"\` adds \`role="alert"\`, so a validation message is announced as
+soon as it appears. The other tones are silent, which is right for a static
+hint that is read as part of the field.
+
+**Connect it to the field yourself.** This element does not wire up
+\`aria-describedby\`, so give the help text an \`id\` and point the input at it —
+otherwise a screen reader user reaches the field with no idea the hint exists:
+
+\`\`\`html
+<input id="pw" aria-describedby="pw-hint">
+<bd-help-text id="pw-hint">At least 12 characters.</bd-help-text>
+\`\`\`
+        `
+      }
+    }
+  },
+  argTypes: {
+    tone: {
+      control    : { type: 'select' },
+      options    : ['default', 'success', 'error'],
+      description: 'Which kind of message. `error` also announces itself via role="alert".',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+    }
+  }
+};
+
+export const Default = () => html`
+    <bd-help-text>We only use this for your licence key.</bd-help-text>
+  `;
+
+export const Error = () => html`
+    <bd-help-text tone="error">Enter a valid email address.</bd-help-text>
+  `;
+
+export const Success = () => html`
+    <bd-help-text tone="success">Looks good.</bd-help-text>
+  `;

package/src/components/highlight/highlight.css.js

@@ -1,24 +1,36 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+/* unsafeCSS is how a Lit css`` template accepts a computed string. The
+   value is not arbitrary: below() resolves a name from the closed
+   breakpoint set and throws on anything else, so the only strings that
+   reach here are the ones the scale produced. */
+import { below } from "../shared/token-scales.js";
 
 export default css`
  :host {
   display: block;
+  /* No type on this host. The headline is a bd-h and the sub-title a bd-p, and
+     each atom sets size, weight and leading on its own inner element, so a
+     weight, a size and a leading declared here reached no character of either.
+     Proved by forcing this host to 70px/5/100 in all three stories and watching
+     .bd-heading hold its heading-h3 role and the sub-title hold body-small,
+     whatever those roles currently resolve to — 32/41.6/600 and 14/20.3/400
+     when this was last measured, after the leading was derived from the font.
+     The numbers move with the roles; the point is that neither budged. The
+     .highlight-text spans are slotted into the bd-h, so they inherit through
+     the flattened tree from .bd-heading too. text-align stays: neither atom
+     sets it, so it does inherit through. */
   font-family: var(--typography-fontFamily-sans);
-  font-weight: var(--typography-heading-h1-fontWeight);
-  font-size: var(--typography-fontSize-3xl);
-  line-height: 1.3;
   text-align: center;
-  color: #000;
+  color: var(--color-text-primary);
+  /* no token: a centred title measure, deliberately narrower than the page
+     column (--layout-ensemble-max-width); nothing on the scale sits between
+     --content-width-readable and that column */
   max-width: 820px;
   margin: 0 auto;
-  // padding-top: var(--spacing-64)
 }
   
 .sub-title {
-  color: #006DFF;
-  font-family: var(--typography-fontFamily-sans);
-  font-weight: var(--typography-body-large-fontWeight);
-  font-size: 20px;
+  color: var(--color-text-brand);
   margin: 0 0 var(--spacing-24) 0;
 }
 
@@ -28,103 +40,113 @@ export default css`
 
   .highlight {
     display: inline;
-    background: #F1F7FE;
-    color: #000;
-    z-index: -1;
+    background: var(--color-surface-info);
+    color: var(--color-text-primary);
+    /* The three rungs of the ladder this atom stacks its own internals on:
+       the tint sits below the line, the text on it, the decorations above. */
+    z-index: var(--z-below);
     position: relative;
-margin-left: calc(var(--spacing-4) * -1);
-    margin-right: var(--spacing-2);
+margin-left: calc(-1 * var(--spacing-4));
+    margin-right: calc(-1 * var(--spacing-4));
   }
 
 .highlight-text {
-  position: relative; 
-  z-index: 1;        
+  position: relative;
+  z-index: var(--z-base);
   padding-left: var(--spacing-4);
-  padding-right: 0px;
+  padding-right: var(--spacing-4);
   box-decoration-break: clone;
   -webkit-box-decoration-break: clone;
 }
 
-  .highlight-right-anchor {
-    display: inline-block;
-    width: 1px;
-    height: 1em;
-    vertical-align: bottom;
+  /* Empty and inline on purpose: it takes the same content box as the text
+     beside it and has no width to break, so it rides along to whichever line
+     its end of the phrase lands on. An absolutely positioned child of
+     .highlight itself resolves against a single line fragment, which is why
+     both decorations piled onto the first line when the phrase wrapped. */
+  .highlight-anchor {
     position: relative;
-      margin-left: -12px;
-
   }
 
   .highlight-deco {
+    /* Local so the two insets below derive from the box rather than restating
+       a number per breakpoint. The bar is centred in this box, so pulling the
+       box out by half its spare width lands the bar on the background edge. */
+    --bd-highlight-deco-width: var(--spacing-8);
+    --bd-highlight-deco-inset: calc(
+      -1 * (var(--bd-highlight-deco-width) - var(--spacing-2)) / 2
+    );
+
     position: absolute;
-    width: var(--spacing-8);
-    height: 46px;
+    width: var(--bd-highlight-deco-width);
     display: flex;
     flex-direction: column;
     align-items: center;
     justify-content: flex-start;
     pointer-events: none;
-    z-index: 2;
+    z-index: var(--z-raised);
   }
 
   .highlight-deco.left {
-    left: -3px;
-    top: -4px;
+    left: var(--bd-highlight-deco-inset);
+    top: calc(-1 * var(--spacing-4));
+    bottom: 0;
   }
 
+  /* Mirrors .left against the other edge of the same box. It used to be
+     positioned against a 1px anchor span whose distance from that edge changed
+     with the surrounding text, which is why the bar drifted clear of the
+     background when the highlight was the last word. */
   .highlight-deco.right {
-    bottom: 0;
-    left: 3px;
-    top: -10px;
+    right: var(--bd-highlight-deco-inset);
+    top: 0;
+    bottom: calc(-1 * var(--spacing-4));
   }
 
+  /* no token: the brand decoration mark. blue-500 is the right step but no
+     role names it — --color-border-brand is a border, --status-brand-fill is a
+     chip background, and neither is an ornament. This needs a decoration role
+     before it can be spelled as one; inventing one for a single consumer is
+     what the token layer is trying to stop. */
   .highlight-svg-rect {
     width: var(--spacing-2);
-    height: 38px;
-    fill: #006DFF;
+    /* whatever the dot leaves, so the bar always ends on the background edge */
+    flex: 1;
+    /* no role: the deco bar, same decision as the ellipses below -- ornament flanking the
+       highlighted text, not a mark, so an ink role is the wrong family. 4.20:1 against
+       the blue-50 ground, over the 3:1 non-text bar. */
+    fill: var(--color-blue-500);
     margin: 0;
     display: block;
   }
 
   .highlight-svg-ellipse-top,
   .highlight-svg-ellipse-bottom {
-    width: var(--spacing-8);
-    height: var(--spacing-8);
-    fill: #006DFF;
+    flex: none;
+    width: var(--bd-highlight-deco-width);
+    height: var(--bd-highlight-deco-width);
+    /* no role: the two deco ellipses. These are ORNAMENT, not a mark and not a glyph in
+       a text flow -- highlight.js puts them inside <span class="highlight-deco left|right">
+       flanking <span class="highlight-text">, a bracket construct drawn around the
+       highlighted words. Every icon role candidate in this package is an INK role, and
+       ink is the wrong family for a bracket: naming one here would misdescribe these the
+       way calling the terminal's line-kind blues "brand" would have. They pass their bar
+       already -- 4.20:1 against the blue-50 ground, where 3:1 is the non-text minimum.
+       See plans/reports/phase-2-vocab-b-icon-colour.md. */
+    fill: var(--color-blue-500);
     display: block;
   }
 
-  @media (max-width: 600px) {
-  :host {
-    font-size: 20px;
-  }
-
-  .highlight {
-    margin-right: var(--spacing-2);
-  }
+  /* Narrower than sm. A media condition cannot read a custom property, so
+     below() interpolates the value; 600px was on no scale at all, and the
+     576px that replaced it still matched at exactly 576px, where sm begins. */
+  @media ${unsafeCSS(below('sm'))} {
 
   .highlight-deco {
-    height: var(--spacing-32);
-    width: var(--spacing-6);
+    --bd-highlight-deco-width: var(--spacing-6);
   }
 
-  .highlight-svg-rect {
-   var(--spacing-24);
-  }
 
-  .highlight-svg-ellipse-top,
-  .highlight-svg-ellipse-bottom {
-    width: var(--spacing-6);
-    height: var(--spacing-6);
-  }
-      .highlight-deco.right {
-    bottom: 0;
-    left: 3px;
-    top: -6px;
-  }
-    .highlight-text{
-    padding-right: 3px;
-    }
 }
 
 `;