@repobit/dex-system-design 1.0.1 → 2.0.0

package/src/components/pagination-dots/pagination-dots.css.js

@@ -0,0 +1,161 @@
+import { css } from "lit";
+
+/**
+ * Styled entirely from src/tokens/tokens.js -- see CLAUDE.md, "The foundation
+ * rule".
+ *
+ * The geometry is dimension, not spacing, on purpose: a dot is a fixed mark
+ * and should not grow when a reader enlarges their text. The gap around each
+ * dot is spacing, because it is padding, and padding is allowed to grow. So a
+ * larger root font makes the targets wider and leaves the dots as drawn.
+ */
+export default css`
+  :host {
+    display: inline-flex;
+  }
+
+  .dots {
+    display: flex;
+    align-items: center;
+    /* Each button carries its own target, so the space between two dots comes
+       from the boxes. A gap on top would push them apart without making
+       either easier to hit. */
+  }
+
+  /* ---- dots ---------------------------------------------------------------
+     The target. 24px tall for WCAG 2.5.8, and the dot plus 8px either side
+     wide: 24 for a resting dot, 56 for the current pill. The dot is drawn
+     inside it rather than being it. */
+  .dot {
+    display: grid;
+    place-items: center;
+    height: var(--dimension-24);
+    margin: 0;
+    padding: 0 var(--spacing-8);
+    border: none;
+    background: transparent;
+    cursor: pointer;
+  }
+
+  /* The mark is a real element rather than a ::before, because the current
+     one holds the progress fill and a Web Animation needs an element to run
+     on. */
+  .mark {
+    position: relative;
+    display: block;
+    overflow: hidden;
+    width: var(--dimension-8);
+    height: var(--dimension-8);
+    border-radius: var(--radius-full);
+    /* no role: a resting slide mark. No semantic role names an inactive
+       indicator, and it has to clear the 3:1 WCAG 1.4.11 asks of a control's
+       only visual: neutral-500 measures 4.81 on the page and 4.46 on the
+       blue-50 info tint the homepage puts it on. The design's 30% neutral-900
+       measures 1.94 there; neutral-300, which bd-awards-flex used to draw,
+       2.10; and neutral-450 would clear it but exists for the dark theme only. */
+    background: var(--color-neutral-500);
+    transition: width var(--transition-duration-normal) var(--transition-easing-ease),
+      background var(--transition-duration-normal) var(--transition-easing-ease);
+  }
+
+  .dot:hover .mark {
+    /* no role: the same mark under the pointer, one step darker */
+    background: var(--color-neutral-600);
+  }
+
+  /* The progress. Scaled rather than sized, so the fill is drawn by the
+     compositor and never re-lays the row out. Without autoplay the current
+     fill is whole, which is the pill as it always was; with it, the atom's
+     Web Animation runs this from 0 to 1 over the delay and the end of the
+     animation is the change of slide. */
+  .fill {
+    position: absolute;
+    inset: 0;
+    background: var(--indicator-color);
+    transform: scaleX(0);
+    transform-origin: left center;
+  }
+
+  :host(:dir(rtl)) .fill {
+    transform-origin: right center;
+  }
+
+  /* The current slide. The pill is the design's shape. The colour is the
+     indicator role, the one every current-item mark in the package shares --
+     the tab and nav underlines -- so they cannot drift apart. The design draws
+     it neutral-900 as an unbound value; using that would make this the one
+     current mark in the system that is not the indicator. */
+  .dot[aria-current="true"] {
+    cursor: default;
+  }
+
+  /* The current pill is also the autoplay track: the indicator colour at a
+     fifth, laid over whatever surface the dots sit on, inside an indicator
+     edge. Translucent rather than a colour of its own, so it belongs to every
+     ground -- a white track read as a hole on the awards tint and on a band.
+     It was the resting grey before that, and the blue fill could not be seen
+     on it: blue-500 on neutral-500 is 1.06:1.
+     .
+     The edge is 2px, drawn as an outline pulled inside the box rather than as
+     a border. At 1px it was faint at 1x density, and that is the moment it
+     matters most: the start of each slide, when nothing has filled yet and
+     the edge alone marks the pill. A 2px border would have taken the 2px out
+     of the box and left the fill a 4px sliver; an outline takes no room, and
+     it paints above the fill in the fill's own colour, so the fill keeps the
+     full 8px and the two merge where they meet. Under a forced palette the
+     outline is repainted in a system colour and still draws.
+     .
+     Measured: the fill against the track is 3.10:1 or better on the page,
+     the container, the subtle band and the awards tint; the edge against the
+     ground 4.05:1 or better. When the fill is whole the edge and fill are one
+     colour, which is the solid pill a dots row without autoplay shows. */
+  .dot[aria-current="true"] .mark {
+    width: var(--dimension-40);
+    background: color-mix(in srgb, var(--indicator-color) 20%, transparent);
+    outline: var(--border-width-2) solid var(--indicator-color);
+    outline-offset: calc(-1 * var(--border-width-2));
+  }
+
+  .dot[aria-current="true"] .fill {
+    transform: scaleX(1);
+  }
+
+  /* ---- focus ------------------------------------------------------------
+     the one focus ring -- see Foundations/Focus. It follows the target, not
+     the mark, so keyboard focus shows the size the button really is. */
+  .dot:focus {
+    outline: none;
+  }
+
+  .dot:focus-visible {
+    box-shadow: var(--focus-outline-primary);
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
+    border-radius: var(--radius-full);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .mark {
+      transition: none;
+    }
+  }
+
+  /* A forced palette repaints backgrounds, which would erase every dot.
+     Borders survive it, so a resting dot is drawn as a ring, and the fill is
+     kept out of the repaint and drawn in the highlight colour -- so the
+     current pill still shows, and so does the time it has left. */
+  @media (forced-colors: active) {
+    .mark {
+      box-sizing: border-box;
+      border: var(--border-width-1) solid currentColor;
+    }
+    .fill {
+      forced-color-adjust: none;
+      background: Highlight;
+    }
+  }
+`;

package/src/components/pagination-dots/pagination-dots.js

@@ -0,0 +1,202 @@
+import { LitElement, html, nothing } from "lit";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
+import paginationDotsCSS from "./pagination-dots.css.js";
+
+/**
+ * Which of a run of slides is showing, and a way to go to another: the
+ * package's one set of slide dots. Drawn in the foundation Figma file as
+ * Pagination dot and Pagination dots.
+ *
+ * bd-awards-flex and bd-carousel-section each used to draw their own -- a dot
+ * row that claimed to be a tablist, and a pair of <img role="button"> arrows --
+ * and the two had drifted apart on contrast, semantics and names. The carousel
+ * that owns the slides stays the owner of the slides: it sets current, and
+ * listens for bd-change.
+ *
+ * SEMANTICS. A group of buttons, the current one marked aria-current. Not a
+ * tablist: a tab needs a tabpanel it controls, and this atom does not own or
+ * know the panels. Each button is named for what it does ("Go to slide 2"),
+ * and the group for what it moves through. Both names are attributes, so a
+ * page in another language can say them.
+ *
+ * TARGET SIZE. A dot is 8px and the design spaces them 8px apart. Clickable at
+ * that size they fail WCAG 2.5.8, so each button is a 24px target with the dot
+ * drawn inside it. The dots end up 16px apart instead of 8; the part you can
+ * hit grows and the dots do not.
+ *
+ * AUTOPLAY. With autoplay set, the atom advances itself every delay ms and the
+ * current pill fills as the time runs: the progress IS the clock, so the fill
+ * and the change of slide cannot drift apart. That is why the timer lives here
+ * and not in the carousel. Every advance fires bd-change, exactly as a click.
+ *
+ * Stopping it. WCAG 2.2.2 wants a way to stop anything that moves on its own,
+ * and there is no pause button, so the dots are the mechanism: picking one
+ * stops autoplay for good (paused), because a visitor who chose a slide has
+ * said which one they want to read. The clock also holds -- transiently --
+ * while the pointer or focus is on the dots, or while the owner sets held for
+ * its own slides. Under prefers-reduced-motion it never starts.
+ *
+ * count below 2 renders nothing: one page has nothing to move to.
+ */
+const MIN_DELAY = 1000;
+
+class BdPaginationDots extends LitElement {
+  static styles = [paginationDotsCSS];
+
+  static properties = {
+    count    : { type: Number },
+    current  : { type: Number, reflect: true },
+    label    : { type: String },
+    itemLabel: { type: String, attribute: "item-label" },
+    autoplay : { type: Boolean, reflect: true },
+    delay    : { type: Number },
+    paused   : { type: Boolean, reflect: true },
+    held     : { type: Boolean },
+    _selfHeld: { state: true }
+  };
+
+  constructor() {
+    super();
+    this.count = 0;
+    // 1-based, like the names the buttons announce
+    this.current = 1;
+    this.label = "Slides";
+    this.itemLabel = "Go to slide";
+    this.autoplay = false;
+    this.delay = 4000;
+    this.paused = false;
+    this.held = false;
+    this._selfHeld = false;
+    this._progress = null;
+    this._announced = undefined;
+    this._onMotionChange = () => { if (this._motionQuery.matches) this.paused = true; };
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Watched rather than read once, so turning the setting on mid-visit stops it.
+    if (typeof window !== "undefined" && window.matchMedia) {
+      this._motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+      if (this._motionQuery.matches) this.paused = true;
+      this._motionQuery.addEventListener("change", this._onMotionChange);
+    }
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._motionQuery?.removeEventListener("change", this._onMotionChange);
+    this._stopProgress();
+  }
+
+  /** count is a whole number of dots, and current always names one of them. */
+  willUpdate(changed) {
+    if (!changed.has("count") && !changed.has("current")) return;
+    const count = Math.max(0, Math.floor(Number(this.count) || 0));
+    if (count !== this.count) this.count = count;
+    const current = Math.min(Math.max(1, Math.floor(Number(this.current) || 1)), Math.max(1, count));
+    if (current !== this.current) this.current = current;
+  }
+
+  updated(changed) {
+    // A new slide, a new clock or autoplay switched: the fill starts again.
+    if (["count", "current", "autoplay", "delay"].some(k => changed.has(k))) this._startProgress();
+    this._syncProgress();
+    this._announcePlayState();
+  }
+
+  get _running() {
+    return this.autoplay && this.count > 1;
+  }
+
+  get _moving() {
+    return this._running && !this.paused && !this.held && !this._selfHeld;
+  }
+
+  /* One Web Animation per slide, on the current pill's fill. Its finish is the
+     advance; pausing it is pausing the clock, and the fill holds where it
+     stopped rather than snapping back. */
+  _startProgress() {
+    this._stopProgress();
+    if (!this._running) return;
+    const fill = this.renderRoot.querySelector('.dot[aria-current="true"] .fill');
+    if (!fill?.animate) return;
+    const delay = Math.max(MIN_DELAY, Number(this.delay) || 0);
+    const progress = fill.animate(
+      [{ transform: "scaleX(0)" }, { transform: "scaleX(1)" }],
+      { duration: delay, easing: "linear", fill: "forwards" }
+    );
+    this._progress = progress;
+    progress.finished.then(() => {
+      if (this._progress !== progress) return;
+      this._select(this.current >= this.count ? 1 : this.current + 1);
+    }, () => {});
+  }
+
+  _stopProgress() {
+    const progress = this._progress;
+    this._progress = null;
+    progress?.cancel();
+  }
+
+  _syncProgress() {
+    const progress = this._progress;
+    if (!progress) return;
+    if (this._moving && progress.playState === "paused") progress.play();
+    else if (!this._moving && progress.playState === "running") progress.pause();
+  }
+
+  /* bd-toggle whenever the slides start or stop moving, for whatever reason.
+     An owner needs it for its live region -- slides that change on their own
+     must not be announced, and slides that change because the visitor asked
+     must be -- and only this atom knows about the holds it places itself.
+     Fired once on first render too, so the owner starts in step. */
+  _announcePlayState() {
+    const state = `${this.paused}|${this._moving}`;
+    if (state === this._announced) return;
+    this._announced = state;
+    this.dispatchEvent(new CustomEvent("bd-toggle", {
+      detail  : { paused: this.paused, moving: this._moving },
+      bubbles : true,
+      composed: true
+    }));
+  }
+
+  _select(n) {
+    if (n === this.current) return;
+    this.current = n;
+    this.dispatchEvent(new CustomEvent("bd-change", {
+      detail  : { current: n },
+      bubbles : true,
+      composed: true
+    }));
+  }
+
+  // The visitor's pick: it moves, and it stops autoplay for good.
+  _pick(n) {
+    if (this._running) this.paused = true;
+    this._select(n);
+  }
+
+  render() {
+    if (this.count < 2) return nothing;
+    const pages = Array.from({ length: this.count }, (_, i) => i + 1);
+    return html`<div
+        class="dots"
+        role="group"
+        aria-label="${this.label}"
+        @pointerenter=${() => { this._selfHeld = true; }}
+        @pointerleave=${() => { this._selfHeld = this.renderRoot.contains(this.renderRoot.activeElement); }}
+        @focusin=${() => { this._selfHeld = true; }}
+        @focusout=${e => { this._selfHeld = this.renderRoot.contains(e.relatedTarget) || this.matches(":hover"); }}
+      >${pages.map(n => html`<button
+          type="button"
+          class="dot"
+          aria-label="${this.itemLabel} ${n}"
+          aria-current="${n === this.current ? "true" : nothing}"
+          @click=${() => this._pick(n)}
+        ><span class="mark"><span class="fill"></span></span></button>`)}</div>`;
+  }
+}
+
+customElements.define("bd-pagination-dots", BdPaginationDots);

package/src/components/pagination-dots/pagination-dots.stories.js

@@ -0,0 +1,171 @@
+import { html } from 'lit';
+import './pagination-dots.js';
+
+export default {
+  title     : 'Atoms/Pagination Dots',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`<bd-pagination-dots>\` is the package's one set of slide dots: which slide
+is showing, and a way to go to another. \`bd-awards-flex\` and
+\`bd-carousel-section\` both use it.
+
+\`\`\`html
+<bd-pagination-dots count="5" current="1"></bd-pagination-dots>
+<bd-pagination-dots count="5" current="1" autoplay delay="4000"></bd-pagination-dots>
+\`\`\`
+
+The carousel that owns the slides stays their owner. It sets \`current\`, and
+listens for \`bd-change\`, whose \`detail.current\` is the slide to show --
+picked by a dot or by the autoplay clock.
+
+- **A group of buttons**, the current one marked \`aria-current\`. Not a
+  tablist: a tab needs a panel it controls, and this atom does not own the
+  panels.
+- **Two names, both attributes.** \`label\` names the group (default
+  "Slides") and \`item-label\` starts each button's name (default "Go to
+  slide", so "Go to slide 2"). A page in another language sets both.
+- **Every dot is a 24px target.** The dot is drawn inside it, so the dots sit
+  16px apart rather than the design's 8. At 8 they would fail WCAG 2.5.8.
+- **The current dot is a 40px pill** in the indicator colour, the same
+  colour as every other current-item mark in the package. The design draws it
+  neutral-900; that would make it the only current mark that is not the
+  indicator.
+- **A resting dot is neutral-500**, the lightest step that clears 3:1 on
+  every light ground it can sit on. The design's faint grey measures 1.94:1.
+- **\`autoplay\` puts the clock in the pill.**- **\`autoplay\` puts the clock in the pill.** The atom advances itself every
+  \`delay\` ms, wrapping after the last slide. The current pill is the
+  progress: a white track inside an indicator-colour edge, which the
+  indicator fills as the time runs, so the fill and the change of slide are
+  one event and cannot drift apart. Without autoplay the pill is filled whole.
+- **The dots are how it stops** (WCAG 2.2.2). Picking one stops autoplay for
+  good and sets \`paused\`. The clock also holds while the pointer or focus is
+  on the dots, or while the owner sets \`held\` -- the carousel does that for
+  its own slides. Under \`prefers-reduced-motion\` it never starts.
+- **\`bd-toggle\`** fires when the slides start or stop moving, with
+  \`detail.paused\` and \`detail.moving\`. An owner uses it for its live
+  region: off while slides change by themselves, polite once they are still.
+- **\`count\` below 2 renders nothing.** One page has nowhere to go.
+        `
+      }
+    }
+  },
+  argTypes: {
+    count: {
+      control    : { type: 'number', min: 0, max: 12, step: 1 },
+      description: 'How many dots. Below 2 nothing renders.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: '0' } }
+    },
+    current: {
+      control    : { type: 'number', min: 1, max: 12, step: 1 },
+      description: 'Which dot is current, 1-based. Held between 1 and `count`.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: '1' } }
+    },
+    label: {
+      control    : 'text',
+      description: 'The group\'s accessible name: what the dots move through.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'Slides' } }
+    },
+    itemLabel: {
+      control    : 'text',
+      description: 'Starts each button\'s accessible name; the dot\'s number follows it.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'Go to slide' } }
+    },
+    autoplay: {
+      control    : 'boolean',
+      description: 'Advance every `delay` ms, with the progress in the current pill. Picking a dot stops it.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    delay: {
+      control    : { type: 'number', min: 1000, step: 500 },
+      description: 'Milliseconds per slide under autoplay. Held at 1000 or more.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: '4000' } }
+    },
+    paused: {
+      control    : 'boolean',
+      description: 'Autoplay stopped for good. Set when the visitor picks a dot.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    }
+  }
+};
+
+const caption = text => html`
+  <p style="margin:var(--spacing-24) 0 var(--spacing-8);font:var(--typography-fontSize-xs)/1.4 var(--typography-fontFamily-sans);color:var(--color-text-muted)">${text}</p>
+`;
+
+export const Default = {
+  name  : 'Default — as the homepage uses it',
+  render: () => html`
+    <div style="background:var(--color-surface-info);padding:var(--spacing-32);border-radius:var(--radius-3xl);display:flex;justify-content:center;">
+      <bd-pagination-dots count="5" current="1" label="Awards"></bd-pagination-dots>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'Five slides on the awards carousel\'s info tint. Each dot is a 24px target; tab through them to see the ring follow the target, not the dot.' } } }
+};
+
+export const Counts = {
+  name  : 'Counts',
+  render: () => html`
+    ${[2, 3, 4, 5, 8].map(count => html`
+      ${caption(`count="${count}"`)}
+      <bd-pagination-dots count="${count}" current="2"></bd-pagination-dots>
+    `)}
+    ${caption('count="1" — renders nothing, because one page has nowhere to go')}
+    <bd-pagination-dots count="1"></bd-pagination-dots>
+  `,
+  parameters: { docs: { description: { story: 'The same atom at every count the homepage could need, current on the second dot.' } } }
+};
+
+export const OnGrounds = {
+  name  : 'On every light ground',
+  render: () => html`
+    ${[['page — surface/default', 'var(--color-surface-default)'], ['card — surface/container', 'var(--color-surface-container)'], ['band — surface/subtle', 'var(--color-surface-subtle)'], ['awards — surface/info', 'var(--color-surface-info)']].map(([label, bg]) => html`
+      ${caption(label)}
+      <div style="background:${bg};padding:var(--spacing-16) var(--spacing-24);border-radius:var(--radius-md);display:inline-flex;">
+        <bd-pagination-dots count="5" current="3"></bd-pagination-dots>
+      </div>
+    `)}
+  `,
+  parameters: { docs: { description: { story: 'The resting dot clears 3:1 on all four (WCAG 1.4.11), at 4.29:1 or better; the current pill, the indicator role, at 4.05:1 or better.' } } }
+};
+
+export const Interactive = {
+  name  : 'Picking a dot',
+  render: () => html`
+    <bd-pagination-dots
+      count="5"
+      current="1"
+      @bd-change=${e => { e.currentTarget.nextElementSibling.textContent = `bd-change — detail.current is ${e.detail.current}`; }}
+    ></bd-pagination-dots>
+    <p style="margin:var(--spacing-12) 0 0;font:var(--typography-fontSize-sm)/1.5 var(--typography-fontFamily-sans);color:var(--color-text-secondary)" aria-live="polite">Pick a dot.</p>
+  `,
+  parameters: { docs: { description: { story: 'The atom moves its own current dot and fires `bd-change`. Picking the current dot does nothing and fires nothing.' } } }
+};
+
+export const Autoplay = {
+  name  : 'Autoplay — the pill is the clock',
+  render: () => html`
+    <div style="background:var(--color-surface-info);padding:var(--spacing-32);border-radius:var(--radius-3xl);display:flex;justify-content:center;">
+      <bd-pagination-dots count="3" current="1" label="Awards" autoplay delay="4000"></bd-pagination-dots>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'As bd-awards-flex uses it. The current pill fills over four seconds and the slide changes when it is full. Point at the dots or tab into them and the fill holds where it is; pick one and autoplay stops for good.' } } }
+};
+
+export const Playground = {
+  name  : '🛝 Playground',
+  args  : { count: 5, current: 1, label: 'Slides', itemLabel: 'Go to slide', autoplay: false, delay: 4000, paused: false },
+  render: args => html`
+    <bd-pagination-dots
+      count="${args.count}"
+      current="${args.current}"
+      label="${args.label}"
+      item-label="${args.itemLabel}"
+      ?autoplay=${args.autoplay}
+      delay="${args.delay}"
+      ?paused=${args.paused}
+    ></bd-pagination-dots>
+  `
+};

package/src/components/paragraph/paragraph.css.js

@@ -1,4 +1,5 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   /* --color-text-primary, not --color-neutral-1000. Body copy was set in pure
@@ -52,4 +53,39 @@ export default css`
     line-height: var(--typography-body-lead-lineHeight);
     letter-spacing: var(--typography-body-lead-letterSpacing);
   }
+
+  /* The eyebrow: a short label above a section title. It takes the
+     label-large role -- the role whose job is a short label rather than
+     running text -- which is 16px at 1.5 like body-regular and Medium 500
+     where body-regular is 400. Brand ink is part of the pattern: all five
+     eyebrows in the package and every one on the homepage are text-brand.
+     A color attribute still wins, for an eyebrow on a dark band. */
+  :host([variant="eyebrow"]) p {
+    font-size: var(--typography-label-large-fontSize);
+    font-weight: var(--typography-label-large-fontWeight);
+    line-height: var(--typography-label-large-lineHeight);
+    letter-spacing: var(--typography-label-large-letterSpacing);
+    font-family: var(--typography-label-large-fontFamily);
+    color: var(--color-text-brand);
+  }
+
+  /* Below lg the eyebrow steps down to label-default: 14px, the same Medium
+     500 at 1.5. The homepage draws it 14 on the 390 and 768 frames and 16 on
+     desktop, so the step sits at lg, which is also where every fluid role in
+     the system stops growing. A step between two declared roles rather than a
+     fluid size, because the label family has no fluid role, and one for a
+     single variant would be a new token where two existing roles already
+     answer both ends exactly. */
+  @media ${unsafeCSS(below("lg"))} {
+    :host([variant="eyebrow"]) p {
+      font-size: var(--typography-label-default-fontSize);
+      font-weight: var(--typography-label-default-fontWeight);
+      line-height: var(--typography-label-default-lineHeight);
+      letter-spacing: var(--typography-label-default-letterSpacing);
+    }
+  }
+
+
+  
+
 `;

package/src/components/paragraph/paragraph.js

@@ -6,8 +6,21 @@ import {
 } from "../shared/token-scales.js";
 import paragraphCSS from "./paragraph.css.js";
 
-/** The five body roles the stylesheet carries. */
-const VARIANTS = ["xsmall", "small", "regular", "large", "lead"];
+/**
+ * The five body roles the stylesheet carries, and the eyebrow.
+ *
+ * eyebrow is the short brand-ink label above a section title. It reads the
+ * label-large role -- 16px, Medium 500, 1.5 -- from lg up, and label-default
+ * (14px, the same weight and leading) below lg, rather than a role of its
+ * own, so it adds no token. It exists because five components drew the pattern
+ * and disagreed on weight: bento-grid and header-code at the body role's 400,
+ * trust-panel twice and agent-endpoints at a semibold 600 passed through
+ * font-weight, and the homepage design at 500. The phase-1 eyebrow
+ * investigation found no role was needed while every eyebrow resolved
+ * through body-regular; once three of them reached past it for a weight, one
+ * spelling became the thing that keeps them together.
+ */
+const VARIANTS = ["xsmall", "small", "regular", "large", "lead", "eyebrow"];
 
 export class BdP extends LitElement {
   static properties = {
@@ -21,6 +34,10 @@ export class BdP extends LitElement {
     fontWeight   : { type: String, attribute: "font-weight" },
     fontSize     : { type: String, attribute: "font-size" },
     letterSpacing: { type: String, attribute: "letter-spacing" },
+    /* A semantic role, the same closed set bd-h and bd-display take. Without
+       it a paragraph's ink could only come from the composing component's
+       CSS, so a page could not say an eyebrow is brand-blue or a lead on a
+       brand band is white. */
     color        : { type: String }
   };