@repobit/dex-system-design 1.0.0 → 2.0.0

package/src/components/label/label.js

@@ -4,6 +4,13 @@ import '../../tokens/tokens.js';
 import { labelCSS } from './label.css.js';
 import { resolveSize } from '../shared/prop-vocabulary.js';
 
+let labelIds = 0;
+
+/* Controls whose own <label for> would have worked: the ones a label can be
+   for. A custom element is not here -- see the note on _target. */
+const LABELABLE = new Set(["input", "select", "textarea", "button", "meter", "output", "progress"]);
+const ACTIVATES = new Set(["checkbox", "radio"]);
+
 export class BdLabel extends LitElement {
   static styles = [labelCSS];
 
@@ -17,6 +24,7 @@ export class BdLabel extends LitElement {
     super();
     this.size = 'md';
     this.required = false;
+    this.addEventListener('click', e => this._activate(e));
   }
 
   willUpdate(changed) {
@@ -24,9 +32,87 @@ export class BdLabel extends LitElement {
     if (changed.has('size')) this.size = resolveSize(this.size, 'md');
   }
 
+  /* WHY for IS DONE BY HAND.
+     The <label> this renders is in its own shadow root, and a for reference
+     resolves only in the tree it is written in, so <bd-label for="email">
+     pointed at nothing: the control went unnamed and a click on the label did
+     nothing. It now does what a native label's for does, for a native control
+     in the same tree as this element:
+
+       name       the control gets aria-labelledby pointing at this element,
+                  added to whatever it already lists, and taken back when for
+                  changes or this element leaves -- so the control is named by
+                  the label's text
+       activate   a click on the label focuses the control, and toggles it
+                  when it is a checkbox or a radio
+
+     The control may not exist yet when this renders -- it can come later in
+     the page, or be rendered after -- so until it is found the root is
+     watched for it. */
+  connectedCallback() {
+    super.connectedCallback();
+    this._link();
+  }
+
+  disconnectedCallback() {
+    this._unlink();
+    super.disconnectedCallback();
+  }
+
+  updated(changed) {
+    if (changed.has('for')) this._link();
+  }
+
+  /* The control, when for names one in this element's own tree. A custom
+     element is skipped: its real control is inside its own shadow root, where
+     aria-labelledby on the host does not reach -- label a bd-custom-input
+     with its own label prop. */
+  get _target() {
+    if (!this.for || !this.isConnected) return null;
+    const el = this.getRootNode().getElementById?.(this.for);
+    return el && LABELABLE.has(el.localName) ? el : null;
+  }
+
+  _link() {
+    this._unlink();
+    if (!this.for || !this.isConnected) return;
+    const target = this._target;
+    if (!target) {
+      // not there yet: watch for it, and stop as soon as it is
+      const root = this.getRootNode();
+      this._waiting = new MutationObserver(() => { if (this._target) this._link(); });
+      this._waiting.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['id'] });
+      return;
+    }
+    if (!this.id) this.id = `bd-label-${++labelIds}`;
+    const ids = (target.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean);
+    if (!ids.includes(this.id)) target.setAttribute('aria-labelledby', [...ids, this.id].join(' '));
+    this._linked = { target, id: this.id };
+  }
+
+  _unlink() {
+    this._waiting?.disconnect();
+    this._waiting = null;
+    if (!this._linked) return;
+    const { target, id } = this._linked;
+    const ids = (target.getAttribute('aria-labelledby') || '').split(/\s+/).filter(t => t && t !== id);
+    if (ids.length) target.setAttribute('aria-labelledby', ids.join(' '));
+    else target.removeAttribute('aria-labelledby');
+    this._linked = null;
+  }
+
+  _activate(e) {
+    const target = this._target;
+    if (!target || target.disabled) return;
+    // a link or a control slotted into the label keeps its own click
+    if (e.composedPath().some(n => n !== this && n.matches?.('a[href], button, input, select, textarea'))) return;
+    target.focus();
+    if (target.localName === 'input' && ACTIVATES.has(target.type)) target.click();
+  }
+
   render() {
     return html`
-      <label for=${this.for || nothing}>
+      <label>
         <slot></slot>${this.required
           ? html`<span class="required" aria-hidden="true">*</span>`
           : nothing}

package/src/components/label/label.stories.js

@@ -21,23 +21,32 @@ marker.
 ### Props
 | Prop | Values | Default |
 |---|---|---|
-| \`size\` | \`small\`, \`default\`, \`large\` | \`default\` |
+| \`size\` | \`sm\`, \`md\`, \`lg\` — \`small\` / \`default\` / \`large\` still resolve | \`md\` |
 | \`required\` | boolean — appends a \`*\` marker | \`false\` |
 | \`for\` | id of the control being labelled | \`''\` |
 
-### \`for\` does not cross the shadow boundary
-The \`for\` attribute is applied to a \`<label>\` inside this element's shadow
-root, and a \`for\` reference can only resolve within the same tree. **It will
-not associate with an \`<input id="…">\` in your page.**
+### What \`for\` does
+\`for\` names a native control in the same tree as the label — an
+\`<input>\`, \`<select>\` or \`<textarea>\` with that \`id\` — and behaves like a
+native label's \`for\`:
 
-Until that is addressed, associate the control by nesting or by
-\`aria-labelledby\`:
+- the control is **named by the label**: it gets \`aria-labelledby\` pointing at
+  this element, added to any it already has and removed again when \`for\`
+  changes or the label leaves the page. A label without an \`id\` is given one.
+- a **click on the label** focuses the control, and toggles it when it is a
+  checkbox or a radio.
+
+The control may come later in the page; the label waits for it.
 
 \`\`\`html
-<bd-label id="email-label">Email address</bd-label>
-<input aria-labelledby="email-label">
+<bd-label for="email" required>Email address</bd-label>
+<input id="email" type="email" required>
 \`\`\`
 
+It does **not** reach a design-system field such as \`bd-custom-input\`: that
+field's \`<input>\` is in its own shadow root, where nothing outside can name
+it. Give those fields their own \`label\` prop instead.
+
 ### The required marker is decorative
 The \`*\` carries \`aria-hidden="true"\`, so it is not announced. That is correct
 only if the control itself is marked \`required\` or \`aria-required\` — a screen
@@ -50,9 +59,9 @@ Set both.
   argTypes: {
     size: {
       control    : { type: 'select' },
-      options    : ['small', 'default', 'large'],
+      options    : ['sm', 'md', 'lg'],
       description: 'Type size of the label.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     },
     required: {
       control    : 'boolean',
@@ -61,7 +70,7 @@ Set both.
     },
     for: {
       control    : 'text',
-      description: 'Id of the labelled control. Note it cannot cross the shadow boundary — see the notes.',
+      description: 'Id of a native control in the same tree. It is named by this label and focused by a click on it. Does not reach inside bd-custom-input — see the notes.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Accessibility' }
     }
   }

package/src/components/link/link.css.js

@@ -14,13 +14,19 @@ import { css } from "lit";
  * text, and the atom's own bold variant already avoided it.
  */
 export default css`
+  /* Every axis here is the standalone role's. Weight used to be the one
+     exception -- it read --typography-link-default-fontWeight, the inline
+     role's 400 -- so a standalone link rendered 400 against the 500 its own
+     role, the Figma link/standalone style and the homepage all draw. The
+     inline role's weight now lives in the inline block below, with the rest
+     of that role. */
   .bd-link {
     display: inline-flex;
     align-items: center;
     gap: var(--spacing-4);
     font-family: var(--typography-fontFamily-sans);
     font-size: var(--typography-link-standalone-fontSize);
-    font-weight: var(--typography-link-default-fontWeight);
+    font-weight: var(--typography-link-standalone-fontWeight);
     line-height: var(--typography-link-standalone-lineHeight);
     color: var(--bd-link-color, var(--color-text-brand));
     text-decoration: none;
@@ -48,6 +54,7 @@ export default css`
   :host([inline]) .bd-link {
     display: inline;
     font-size: var(--typography-link-default-fontSize);
+    font-weight: var(--typography-link-default-fontWeight);
     line-height: var(--typography-link-default-lineHeight);
     letter-spacing: var(--typography-link-default-letterSpacing);
     font-family: var(--typography-link-default-fontFamily);
@@ -142,6 +149,35 @@ export default css`
     text-decoration: none;
   }
 
+  /* ---- arrow ------------------------------------------------------------
+     spacing/8 between the label and the arrow, the icon-to-label gap bd-back
+     and the md and lg buttons already use. The base row's spacing/4 was set
+     for text alone, and the Figma set measures 8.
+
+     The underline needs no rule of its own. The anchor is a flex container,
+     so the decoration propagates to its flex items and is drawn only where
+     there is text: under the label, not under the arrow, which is what the
+     Link arrow set draws. That was the set's open question, and it is
+     answered by the layout this atom already had rather than by a choice. */
+  .bd-link--arrow {
+    gap: var(--spacing-8);
+  }
+
+  /* a swapped icon is held to the step the default arrow is drawn at */
+  .bd-link--arrow ::slotted([slot="icon"]) {
+    height: var(--icon-sm-size);
+  }
+
+  /* inline returns the link to a run of text, so there is no row and the gap
+     goes inert; a start margin keeps the arrow off the last letter instead.
+     The icon has no text, so its baseline is its bottom edge and it sat on
+     the line about 4px high; middle centres it on the x-height. */
+  :host([inline]) .bd-link--arrow bd-arrow-icon,
+  :host([inline]) .bd-link--arrow ::slotted([slot="icon"]) {
+    margin-inline-start: var(--spacing-4);
+    vertical-align: middle;
+  }
+
   .bd-link--active {
     /* no role: a link in its active state -- a state or modifier weight, not a text-content
        type. See button.css.js's .button--bold for the argument. */
@@ -181,8 +217,15 @@ export default css`
   .bd-link:focus-visible {
     /* the one focus ring — see Foundations/Focus. A two-colour ring whose
        white inner band keeps it visible on a coloured or dark surface, which a
-       single-colour outline cannot do. */
-    outline: none;
+       single-colour outline cannot do. surface="dark" keeps it too: a link has
+       no fill or border, so its white band meets the hero directly, 4.53:1 on
+       blue-500 and more on every darker ground. */
+    /* 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);
     box-shadow: var(--focus-outline-primary);
     border-radius: var(--focus-outline-radius);
   }
@@ -209,6 +252,12 @@ export default css`
     cursor: default;
   }
 
+  /* An <a> with no href is not a link, so it does not get the hand: the
+     pointer would promise a destination there is none of. */
+  a.bd-link:not([href]) {
+    cursor: default;
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .bd-link {
       transition: none;

package/src/components/link/link.js

@@ -1,7 +1,9 @@
-import { LitElement, html } from "lit";
+import { LitElement, html, nothing } from "lit";
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import "../../tokens/tokens.js";
 import linkCSS from "./link.css.js";
+// the trailing mark when arrow is set; an atom, the same one bd-button uses
+import "../icons/arrow-icon.js";
 import { fontSize, color } from "../shared/token-scales.js";
 
 /**
@@ -47,12 +49,29 @@ class BdLink extends LitElement {
     /* The surface the link sits on, the same attribute bd-button uses. It
        replaces kind="light", which described the surface rather than the link
        and so could not be combined with any of the real kinds. */
-    surface    : { type: String,  reflect: true }
+    surface    : { type: String,  reflect: true },
+    /* A trailing arrow after the label: "Read more ->" on the homepage's post
+       cards and the four solution-splitter links. Drawn in the foundation
+       Figma file as Link arrow and Link arrow / dark; until now three
+       components hand-rolled it, each with a 12px chevron where the design
+       has the 16px shafted arrow. A modifier like underline rather than a
+       sixth variant, because every variant, state and surface takes it. */
+    arrow      : { type: Boolean, reflect: true },
+    /* Extra text a screen reader reads after the link's name, through
+       aria-describedby on the inner <a>, as on bd-button: the <a> is in this
+       shadow root, so a description from outside never reaches it. bd-tooltip
+       sets it on a bd-link trigger; a page can set it directly. */
+    description: { type: String }
   };
 
   constructor() {
     super();
-    this.href        = "#";
+    /* No destination unless one is given. This was "#", so a bd-link written
+       without an href was still a real link -- focusable, announced as a
+       link, and on activation a jump to the top of the page. Now it renders
+       an <a> with no href, which is not a link at all, and the missing
+       destination shows instead of hiding. */
+    this.href        = "";
     this.target      = "_self";
     this.variant     = "primary";
     this.kind        = "";
@@ -64,6 +83,8 @@ class BdLink extends LitElement {
     this.color       = "";
     this.active      = false;
     this.surface     = "light";
+    this.arrow       = false;
+    this.description = "";
   }
 
   willUpdate(changed) {
@@ -85,10 +106,24 @@ class BdLink extends LitElement {
       this.underline ? "bd-link--underline" : "",
       this.noUnderline ? "bd-link--no-underline" : "",
       this.active ? "bd-link--active" : "",
-      this.disabled  ? "bd-link--disabled"  : ""
+      this.disabled  ? "bd-link--disabled"  : "",
+      this.arrow ? "bd-link--arrow" : ""
     ].filter(Boolean).join(" ");
   }
 
+  /**
+   * The arrow is decorative: the label already says where the link goes, so
+   * the icon is hidden rather than named. It sits in a named slot so a page
+   * can swap the glyph, the way the Figma set swaps its icon property, and it
+   * is drawn in currentColor, so it takes the link's ink in every variant,
+   * state and surface without a rule of its own.
+   */
+  get _arrow() {
+    return this.arrow
+      ? html`<slot name="icon"><bd-arrow-icon size="sm" aria-hidden="true"></bd-arrow-icon></slot>`
+      : nothing;
+  }
+
   /**
    * font-size is a type-scale step and color is a semantic role; both are
    * resolved to token references by shared/token-scales.js, and anything off
@@ -122,27 +157,27 @@ class BdLink extends LitElement {
       .join("; ");
   }
 
+  /* No whitespace anywhere in these templates: not between the tags and the
+     slot, and not around the element either. The default flex row never
+     rendered it, but inline drops the row, and there each newline became a
+     real space inside the host -- measured at 3.5-4.5px past the text on
+     every inline link, so a link before a comma read "countries ,". */
   render() {
     if (this.disabled) {
-      return html`
-        <span part="link" class="${this._classes}" style="${this._inlineStyle}">
-          <slot></slot>
-        </span>
-      `;
+      return html`<span part="link" class="${this._classes}" style="${this._inlineStyle}"><slot></slot>${this._arrow}</span>`;
     }
 
-    return html`
-      <a
+    return html`<a
         part="link"
         class="${this._classes}"
         style="${this._inlineStyle}"
-        href="${this.href}"
-        target="${this.target}"
+        href="${this.href || nothing}"
+        target="${this.href ? this.target : nothing}"
+        aria-describedby="${this.description ? "description" : nothing}"
         @click="${this._handleClick}"
-      >
-        <slot></slot>
-      </a>
-    `;
+      ><slot></slot>${this._arrow}</a>${this.description
+        ? html`<span id="description" hidden>${this.description}</span>`
+        : nothing}`;
   }
 
   _handleClick(e) {

package/src/components/link/link.stories.js

@@ -1,5 +1,7 @@
 import { html } from 'lit';
 import './link.js';
+import '../icons/arrow-right-icon.js';
+import '../visually-hidden/visually-hidden.js';
 
 export default {
   title     : 'Atoms/Link',
@@ -53,6 +55,27 @@ They are two booleans for one axis, which is one more than the axis needs.
 depends on CSS order rather than on intent. Prefer whichever one differs from
 your \`kind\`'s default and leave the other alone.
 
+### arrow
+A trailing arrow after the label, for a standalone call to action — "Read
+more" on a post card, the links in a solution splitter. It is a modifier like
+\`underline\`, so every variant, state and \`surface\` takes it, and the arrow
+follows the link's ink in all of them.
+
+\`\`\`html
+<bd-link href="/blog/post" arrow>Read more</bd-link>
+<bd-link href="/business" variant="bold" arrow>For Small Business</bd-link>
+\`\`\`
+
+- The arrow is \`bd-arrow-icon\`, the only true shafted arrow, at the icon
+  scale's \`sm\` step (16px), with \`spacing/8\` before it.
+- It is decorative and hidden from assistive technology. The label has to say
+  where the link goes; "Read more" alone on a page of cards needs more context.
+- Slot any \`bd-*-icon\` into \`slot="icon"\` to swap the glyph. It is held to
+  the same 16px.
+- The hover underline runs under the label and not under the arrow. Nothing
+  sets that: the link is a flex row, and a decoration is only drawn where there
+  is text.
+
 ### active
 Marks the link as the current destination, for a nav or breadcrumb. It is
 styling only — pair it with \`aria-current="page"\` on the element for the state
@@ -67,8 +90,8 @@ to be announced.
   argTypes: {
     href: {
       control    : 'text',
-      description: 'The anchor href URL',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '#' }, category: 'Navigation' }
+      description: 'Where the link goes. Without one it renders an <a> with no href, which is not a link — not focusable, not announced as one.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Navigation' }
     },
     target: {
       control    : { type: 'select' },
@@ -102,6 +125,11 @@ to be announced.
       description: 'Marks the link as the current one, e.g. in a nav. Adds `bd-link--active`.',
       table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
     },
+    arrow: {
+      control    : 'boolean',
+      description: 'A trailing 16px arrow after the label, for a standalone call to action. Decorative: the label must say where the link goes. Slot a `bd-*-icon` into `slot="icon"` to swap it.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'Appearance' }
+    },
     inline: {
       control    : 'boolean',
       description: 'The link is text inside a sentence: size, leading, tracking and family come from the sentence (the `--typography-link-default-*` role, all `inherit`). Without it the link renders 1rem whatever surrounds it. Suppresses `fontSize`.',
@@ -136,6 +164,7 @@ const defaultArgs = {
   active     : false,
   disabled   : false,
   inline     : false,
+  arrow      : false,
   fontSize   : '',
   color      : ''
 };
@@ -152,6 +181,7 @@ const render = (args) => html`
     ?active="${args.active}"
     ?inline="${args.inline}"
     ?disabled="${args.disabled}"
+    ?arrow="${args.arrow}"
   >Click this link</bd-link>
 `;
 
@@ -252,12 +282,93 @@ export const NavigationLinks = {
   parameters: { docs: { description: { story: 'Light kind links used as navigation items on a dark background.' } } }
 };
 
+// ─── Arrow ─────────────────────────────────────────────────────────────────
+
+const ARROW_VARIANTS = ['primary', 'secondary', 'subtle', 'bold', 'danger'];
+const arrowRow = 'display:flex; gap:var(--spacing-32); flex-wrap:wrap; align-items:center;';
+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 Arrow = {
+  name  : 'Arrow — every variant',
+  render: () => html`
+    ${caption('arrow — the arrow follows the link\'s ink in every variant')}
+    <div style="${arrowRow}">
+      ${ARROW_VARIANTS.map(v => html`<bd-link href="#" variant="${v}" arrow>Read more</bd-link>`)}
+    </div>
+    ${caption('arrow with underline at rest — the underline runs under the label, not the arrow, exactly as on hover')}
+    <div style="${arrowRow}">
+      ${ARROW_VARIANTS.map(v => html`<bd-link href="#" variant="${v}" arrow underline>Read more</bd-link>`)}
+    </div>
+    ${caption('disabled — the arrow takes the disabled ink with the label')}
+    <div style="${arrowRow}">
+      ${ARROW_VARIANTS.map(v => html`<bd-link href="#" variant="${v}" arrow disabled>Read more</bd-link>`)}
+    </div>
+  `,
+  parameters: { docs: { description: { story: '16px `bd-arrow-icon` after the label with `spacing/8` before it. Hover any link to see the underline stop at the label.' } } }
+};
+
+export const ArrowOnDark = {
+  name  : 'Arrow — on a dark surface',
+  render: () => html`
+    ${[['surface-brand', 'var(--color-surface-brand)'], ['neutral-950', 'var(--color-neutral-950)']].map(([label, bg]) => html`
+      ${caption(`${label} — surface="dark"`)}
+      <div style="background:${bg};padding:var(--spacing-24);border-radius:var(--radius-md);${arrowRow}">
+        ${ARROW_VARIANTS.slice(0, 4).map(v => html`<bd-link href="#" variant="${v}" surface="dark" arrow>Explore enterprise AI</bd-link>`)}
+      </div>
+    `)}
+  `,
+  parameters: { docs: { description: { story: 'The same as Link arrow / dark in the Figma file: on a dark surface every variant collapses onto text/inverse, and the arrow goes with it.' } } }
+};
+
+export const ArrowOwnIconAndInline = {
+  name  : 'Arrow — swapped icon, and inline',
+  render: () => html`
+    ${caption('slot="icon" swaps the glyph and holds it at 16px — here the chevron, for a link that steps into a list rather than leaving the page')}
+    <div style="${arrowRow}">
+      <bd-link href="#" arrow>See all products<bd-arrow-right-icon slot="icon"></bd-arrow-right-icon></bd-link>
+    </div>
+    ${caption('inline — there is no row in a sentence, so a start margin keeps the arrow off the last letter')}
+    <p style="max-width:480px;margin:0;font:var(--typography-body-regular-fontWeight) var(--typography-body-regular-fontSize)/var(--typography-body-regular-lineHeight) var(--typography-fontFamily-sans);color:var(--color-text-primary)">
+      Bitdefender protects millions <bd-link href="#" inline arrow>across 170+ countries</bd-link>, combining deep security expertise with AI innovation.
+    </p>
+  `,
+  parameters: { docs: { description: { story: 'A swapped icon is held to the default arrow\'s step. Inline is supported, but the arrow is made for a standalone call to action, not a link inside a sentence.' } } }
+};
+
+export const ArrowOnTheHomepage = {
+  name  : 'Arrow — as the homepage uses it',
+  render: () => html`
+    ${caption('post card — primary')}
+    <div style="max-width:384px;padding:var(--spacing-24);border:var(--border-width-1) solid var(--color-border-container);border-radius:var(--radius-2xl);display:flex;flex-direction:column;gap:var(--spacing-16);">
+      <p style="margin:0;font:var(--typography-heading-h5-fontWeight) var(--typography-heading-h5-fontSize)/var(--typography-heading-h5-lineHeight) var(--typography-fontFamily-sans);color:var(--color-text-primary)">
+        They Wear Our Faces: How Scammers Are Using AI to Swindle American Families
+      </p>
+      <bd-link href="#" arrow>Read more<bd-visually-hidden> about scammers using AI</bd-visually-hidden></bd-link>
+    </div>
+    ${caption('solution splitter — bold')}
+    <div style="display:grid;grid-template-columns:repeat(4, minmax(0, 1fr));gap:var(--spacing-24);max-width:1200px;">
+      ${[['For Individuals', 'AI-powered security, privacy, and scam protection for everyday digital life.'],
+        ['For Small Business', 'Effective protection for users, devices, and business operations.'],
+        ['For Enterprise', 'Advanced cybersecurity for prevention, detection, and response.'],
+        ['For MSPs', 'Security built for managed service providers and the customers they protect.']].map(([title, body]) => html`
+        <div style="display:flex;flex-direction:column;gap:var(--spacing-12);">
+          <bd-link href="#" variant="bold" arrow>${title}</bd-link>
+          <p style="margin:0;font:var(--typography-body-small-fontWeight) var(--typography-body-small-fontSize)/var(--typography-body-small-lineHeight) var(--typography-fontFamily-sans);color:var(--color-text-primary)">${body}</p>
+        </div>
+      `)}
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'Read more on a post card carries visually hidden context, because a page of cards would otherwise read out several identical “Read more” links. The splitter links name their destination already.' } } }
+};
+
 export const Playground = {
   name      : '🛝 Playground',
   args      : { ...defaultArgs },
   render,
   parameters: {
     controls: { disable: false },
-    docs    : { description: { story: 'Interactive playground, and the only story wired to args. Every control here reaches the element: href, target, kind, underline, no-underline, active, disabled, inline, font-size and color.' } }
+    docs    : { description: { story: 'Interactive playground, and the only story wired to args. Every control here reaches the element: href, target, kind, underline, no-underline, active, disabled, inline, arrow, font-size and color.' } }
   }
 };

package/src/components/list/list-item/list-item.css.js

@@ -76,17 +76,15 @@ export default css`
     border-radius: var(--radius-full);
   }
 
-  /* Number List */
-  .bd-list-item.number {
-    counter-increment: bd-list-counter;
-  }
-
+  /* Number List. The number comes from list-item.js, on the marker's
+     data-number: a CSS counter cannot count across shadow roots, so each
+     item's counter only ever reached 1. */
   .bd-list-item.number .bd-list-item-marker {
     margin-top: 0; /* text — se aliniază natural pe linia de bază, nu geometric */
   }
 
   .bd-list-item.number .bd-list-item-marker::before {
-    content: counter(bd-list-counter) ".";
+    content: attr(data-number);
       /* no role: a marker glyph, not running prose. The number or bullet in
          front of a list item is a symbol sized and weighted to sit against the
          text beside it, the same category typography rule 7 already covers for