@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/visually-hidden/visually-hidden.stories.js

@@ -0,0 +1,56 @@
+import { html } from 'lit';
+import './visually-hidden.js';
+
+export default {
+  title     : 'Atoms/Visually Hidden',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdVisuallyHidden** hides content from sight while keeping it available to
+screen readers.
+
+### Usage
+\`\`\`html
+<button>
+  <bd-close-icon></bd-close-icon>
+  <bd-visually-hidden>Close dialog</bd-visually-hidden>
+</button>
+
+<h2><bd-visually-hidden>Section: </bd-visually-hidden>Pricing</h2>
+\`\`\`
+
+### Props
+None. The content is slotted.
+
+### When to use it
+For text that a sighted user does not need because the visual design already
+says it, but that a screen reader user does — the name of an icon-only button,
+a table caption, or context a heading implies visually.
+
+### Not the same as hiding
+\`display: none\`, \`hidden\` and \`visibility: hidden\` remove content from
+everyone, assistive tech included. This clips it to a single pixel and keeps it
+in the accessibility tree, which is the opposite intent.
+
+It also stays focusable, so a skip link inside it can still be reached by Tab
+and revealed on focus.
+
+### Prefer a real label where one exists
+An icon-only button is usually better served by \`aria-label\` on the button
+itself than by hidden text inside it. Reach for this when the text must be part
+of the content — for instance when it needs to be translated with the page, or
+when it belongs to a heading or table rather than a control.
+        `
+      }
+    }
+  }
+};
+
+export const Default = () => html`
+    <p style="font-family: var(--typography-fontFamily-sans)">
+      Rating: 4.8
+      <bd-visually-hidden>out of 5 stars</bd-visually-hidden>
+    </p>
+  `;

package/src/stories/Button.stories.js

@@ -4,43 +4,43 @@ import { Button } from './Button';
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 export default {
-  title: 'Example/Button',
-  tags: ['autodocs'],
-  render: (args) => Button(args),
+  title   : 'Example/Button',
+  tags    : ['autodocs'],
+  render  : (args) => Button(args),
   argTypes: {
     backgroundColor: { control: 'color' },
-    size: {
+    size           : {
       control: { type: 'select' },
-      options: ['small', 'medium', 'large'],
-    },
+      options: ['small', 'medium', 'large']
+    }
   },
-  args: { onClick: fn() },
+  args: { onClick: fn() }
 };
 
 // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
 export const Primary = {
   args: {
     primary: true,
-    label: 'Button',
-  },
+    label  : 'Button'
+  }
 };
 
 export const Secondary = {
   args: {
-    label: 'Button',
-  },
+    label: 'Button'
+  }
 };
 
 export const Large = {
   args: {
-    size: 'large',
-    label: 'Button',
-  },
+    size : 'large',
+    label: 'Button'
+  }
 };
 
 export const Small = {
   args: {
-    size: 'small',
-    label: 'Button',
-  },
+    size : 'small',
+    label: 'Button'
+  }
 };

package/src/stories/Header.stories.js

@@ -3,22 +3,22 @@ import { fn } from '@storybook/test';
 import { Header } from './Header';
 
 export default {
-  title: 'Example/Header',
+  title : 'Example/Header',
   // This component will have an automatically generated Autodocs entry: https://storybook.js.org/web-components/vue/writing-docs/autodocs
-  tags: ['autodocs'],
+  tags  : ['autodocs'],
   render: (args) => Header(args),
-  args: {
-    onLogin: fn(),
-    onLogout: fn(),
-    onCreateAccount: fn(),
-  },
+  args  : {
+    onLogin        : fn(),
+    onLogout       : fn(),
+    onCreateAccount: fn()
+  }
 };
 export const LoggedIn = {
   args: {
     user: {
-      name: 'Jane Doe',
-    },
-  },
+      name: 'Jane Doe'
+    }
+  }
 };
 
 export const LoggedOut = {};

package/src/stories/Page.js

@@ -9,7 +9,7 @@ export const Page = ({ user, onLogin, onLogout, onCreateAccount }) => html`
       user,
       onLogin,
       onLogout,
-      onCreateAccount,
+      onCreateAccount
     })}
 
     <section class="storybook-page">

package/src/stories/Page.stories.js

@@ -2,19 +2,19 @@ import * as HeaderStories from './Header.stories';
 import { Page } from './Page';
 
 export default {
-  title: 'Example/Page',
-  render: (args) => Page(args),
+  title : 'Example/Page',
+  render: (args) => Page(args)
 };
 
 export const LoggedIn = {
   args: {
     // More on composing args: https://storybook.js.org/docs/writing-stories/args#args-composition
-    ...HeaderStories.LoggedIn.args,
-  },
+    ...HeaderStories.LoggedIn.args
+  }
 };
 
 export const LoggedOut = {
   args: {
-    ...HeaderStories.LoggedOut.args,
-  },
+    ...HeaderStories.LoggedOut.args
+  }
 };

package/src/tokens/borders.stories.js

@@ -0,0 +1,339 @@
+import { html } from 'lit';
+import { contrast, docsPage, refSection, resolve } from './story-chrome.js';
+
+import '../components/cards/card.js';
+import '../components/divider/divider-horizontal.js';
+import '../components/paragraph/paragraph.js';
+import '../components/tag/tag.js';
+
+export default {
+  title: 'Foundations/Shape/Borders',
+  tags : ['autodocs']
+};
+
+/* Measured, not transcribed: the ratios below are computed from the tokens as
+   the page renders, so a palette change moves them. */
+const ratio = (token, surface) => {
+  const a = resolve(token);
+  const b = resolve(surface);
+  if (!a || !b) return null;
+  try {
+    return Math.round(contrast(a, b) * 100) / 100;   // contrast() resolves colours itself
+  } catch {
+    return null;
+  }
+};
+
+const swatch = (token, surface, height = 'var(--spacing-40)') => html`
+  <div style="background:var(${surface});padding:var(--spacing-12);border-radius:var(--radius-lg)">
+    <div style="height:${height};border:var(--border-width-1) solid var(${token});border-radius:var(--radius-lg)"></div>
+  </div>`;
+
+const RESPONSIBILITIES = [
+  {
+    name : 'Content boundary',
+    token: '--color-border-container',
+    what : `The edge of a self-contained object — a card, a panel, a navigation band — drawn
+            only so the object is perceptible.`,
+    use: html`When a component has decided it wants an edge and that edge is describing an
+            <i>object</i>, not something you can operate.`,
+    avoid: html`On anything actionable. It is deliberately far below the 3:1 WCAG 1.4.11 asks
+            of a UI component, so a control outlined with it does not read as a control.`,
+    live: 'ComparisonPanel column, TrustPanel card, Bento tile, CompatibilityTable container, PageSwitcher band, AnchorNav band, TabList rail, Carousel item',
+    demo: html`
+      <bd-card-item title="Machine Learning">
+        <bd-p variant="small">A card that has chosen to carry an edge.</bd-p>
+      </bd-card-item>`
+  },
+  {
+    name : 'Control edge',
+    token: '--color-border-default / --color-action-primary',
+    what : 'The boundary of something the user operates.',
+    use  : html`On inputs, checkboxes, radios, and outlined buttons — anywhere the edge is part
+            of the affordance. These are the two roles that clear 3:1, and that is why.`,
+    avoid: html`As a decorative line. A control edge on something inert tells the reader they
+            can operate it.`,
+    live: 'bd-input, bd-checkbox, bd-radio, bd-switch, bd-button (outline variants, drawn as an inset shadow so the box never shifts)',
+    demo: html`
+      <input aria-label="Sample control" placeholder="A control edge"
+        style="padding:var(--spacing-12);border:var(--border-width-1) solid var(--color-border-default);border-radius:var(--radius-md);font:inherit;width:100%;max-width:280px;box-sizing:border-box" />`
+  },
+  {
+    name : 'Divider',
+    token: 'bd-divider-horizontal / --color-border-default',
+    what : 'A line separating adjacent regions of content. It bounds nothing.',
+    use  : html`Between sections, rows or list items. Reach for
+            <code>bd-divider-horizontal</code> when the line is a separator in its own right.`,
+    avoid: html`To outline an object. A border that goes all the way round is a boundary, not a
+            divider — see <i>Dividers are not borders</i> in the package README.`,
+    live: 'bd-divider-horizontal, CompatibilityTable row rules, Footer section rules, ProcessSteps step rules',
+    note: html`A divider names its line with a <b>border role</b>, not a text or surface role:
+            <code>borderColor()</code> in <code>shared/token-scales.js</code> maps the seven
+            names in <code>BORDER_ROLES</code> — default, subtle, strong, container, brand,
+            disabled and brand-subtle — and falls through to the colour scale for anything
+            else. <code>inverse</code> is deliberately not among them: the inverse border is
+            white at 12%, and a divider multiplies that by its own opacity prop, so the role
+            would arrive already halved.`,
+    demo: html`
+      <div>
+        <bd-p variant="small">One region.</bd-p>
+        <bd-divider-horizontal></bd-divider-horizontal>
+        <bd-p variant="small">The next region.</bd-p>
+      </div>`
+  },
+  {
+    name : 'Focus',
+    token: '--focus-outline-primary',
+    what : 'Keyboard focus indication. Never a border role.',
+    use  : html`Always through the focus system. The ring is a <code>box-shadow</code>, so it
+            follows the element's own corner and changes no layout; its radius comes from
+            <code>--focus-outline-radius</code>.`,
+    avoid: html`Never express focus by swapping a border colour. A colour change alone is not a
+            focus indicator, and a border-width change moves the layout.`,
+    live: '33 declarations across the package, all one token',
+    demo: html`
+      <button style="padding:var(--spacing-12) var(--spacing-16);border:var(--border-width-1) solid var(--color-border-default);border-radius:var(--radius-md);background:var(--color-neutral-0);font:inherit;box-shadow:var(--focus-outline-primary)">
+        The ring, shown at rest
+      </button>`
+  },
+  {
+    name : 'Status',
+    token: '--status-*-border / --status-*-accent',
+    what : 'An edge carrying validation, state or tone.',
+    use  : html`<code>-border</code> for a full hairline around a tinted chip;
+            <code>-accent</code> for the heavier rule that marks a message. Two roles, because
+            they are two jobs.`,
+    avoid: html`For decoration in a status colour. If the edge is not saying something about
+            state, it is one of the four responsibilities above.`,
+    live: 'bd-tag (all six tones, -border), bd-alert (four tones, -accent as a 4px rule), bd-input error and success states',
+    demo: html`
+      <div style="display:flex;gap:var(--spacing-8);flex-wrap:wrap">
+        <bd-tag tone="success">Success</bd-tag>
+        <bd-tag tone="warning">Warning</bd-tag>
+        <bd-tag tone="error">Error</bd-tag>
+        <bd-tag tone="info">Info</bd-tag>
+      </div>`
+  }
+];
+
+const block = r => html`
+  <div style="padding:var(--spacing-24) 0;border-top:var(--border-width-1) solid var(--color-border-container)">
+    <p style="margin:0 0 var(--spacing-8);font-family:var(--typography-fontFamily-mono);font-size:var(--typography-fontSize-xs);color:var(--color-text-muted)">
+      <b style="color:var(--color-text-primary)">${r.name}</b> · <code>${r.token}</code>
+    </p>
+    <p style="margin:0 0 var(--spacing-16);color:var(--color-text-secondary);max-width:70ch">${r.what}</p>
+    <div style="background:var(--color-surface-muted);padding:var(--spacing-24);border-radius:var(--radius-lg);margin-bottom:var(--spacing-16)">
+      ${r.demo}
+    </div>
+    <p style="margin:0 0 var(--spacing-4);font-size:var(--typography-fontSize-sm);max-width:70ch"><b>Use it</b> ${r.use}</p>
+    <p style="margin:0 0 var(--spacing-4);font-size:var(--typography-fontSize-sm);max-width:70ch"><b>Do not</b> ${r.avoid}</p>
+    <p style="margin:0;font-size:var(--typography-fontSize-sm);color:var(--color-text-muted);max-width:70ch"><b>Today:</b> ${r.live}</p>
+    ${r.note
+      ? html`<p style="margin:var(--spacing-8) 0 0;font-size:var(--typography-fontSize-sm);color:var(--color-text-secondary);max-width:70ch"><b>Note</b> ${r.note}</p>`
+      : ''}
+  </div>`;
+
+export const Borders = () =>
+  docsPage({
+    title: 'Borders',
+    lede : `Five things a line around something can mean. Foundations/Shape covers how wide a
+            border is and how round its corners are; this page is about which of the five it is,
+            because that is the question the token name answers and the colour value does not.`,
+    note: html`<b>Do not choose a border token because its numeric colour is closest to what
+            you see.</b> Choose the token whose responsibility matches the edge. Two declarations
+            that resolve to the same neutral are not the same role, and a role's value is what it
+            happens to be today — not what it means. This is the same rule the surface roles
+            carry, and it is here for the same reason: eight components chose
+            <code>--color-neutral-100</code> by eye because no role named what they were drawing.`,
+    children: html`
+      ${refSection({
+        name    : 'The five responsibilities',
+        meta    : `${RESPONSIBILITIES.length} roles`,
+        children: html`
+        <p style="max-width:70ch">
+          Ask what the line is doing before asking what it looks like. If you cannot tell
+          whether it is a boundary or a divider, ask whether deleting it would leave the thing
+          it touches still looking like one object: a boundary holds an object together, a
+          divider keeps two apart.
+        </p>
+        ${RESPONSIBILITIES.map(block)}`
+      })}
+
+      ${refSection({
+        name    : 'The hairline says how, not whether',
+        meta    : 'a distinction worth keeping',
+        children: html`
+        <p style="border-left:var(--border-width-4) solid var(--color-border-brand);padding-left:var(--spacing-16);max-width:70ch">
+          <b><code>--color-border-container</code> defines how a low-emphasis content boundary
+          is rendered. It does not decide whether a component should have a border.</b>
+        </p>
+        <p style="max-width:70ch">
+          That stays a component-level design decision, and the measurements say the components
+          genuinely disagree rather than drift. Six cards on
+          <code>--color-surface-container</code> carry no border; Bento carries 1px and the
+          Carousel item 2px on the same surface. The obvious explanation does not survive
+          contact with the numbers: the unbordered cards sit at <b>1.044:1</b> against their
+          backdrop and the bordered ones at <b>1.080:1</b>, so the bordered cards are the
+          <i>higher</i>-contrast group. Border presence does not track backdrop contrast, and it
+          does not track interactivity either — the Carousel item is draggable and opens a
+          modal, and Bento is inert.
+        </p>
+        <p style="max-width:70ch">
+          So there is no card-border token and no rule that cards must or must not have one.
+          When a component decides it wants a low-emphasis boundary, this is the role for it.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Measured, on light and on dark',
+        meta    : 'computed from the tokens as this page renders',
+        children: html`
+        <div class="table-scroll">
+          <table>
+            <caption>
+              Border roles against the surfaces they are used on. Only the two that bound a live
+              control clear the 3:1 WCAG 1.4.11 asks of a UI component, and the rest sit below
+              it deliberately.
+            </caption>
+            <thead>
+              <tr>
+                <th scope="col">Role</th>
+                <th scope="col">Responsibility</th>
+                <th scope="col">On surface-default</th>
+                <th scope="col">On surface-container</th>
+              </tr>
+            </thead>
+            <tbody>
+              ${[
+                ['--color-border-container', 'content boundary'],
+                ['--color-border-subtle', 'hairline between things that belong together'],
+                ['--color-border-disabled', 'exempt under WCAG 1.4.3'],
+                ['--color-border-default', 'control edge'],
+                ['--color-border-brand', 'control edge, brand'],
+                ['--color-border-strong', 'the heaviest neutral edge']
+              ].map(([t, why]) => html`
+                <tr>
+                  <td><code>${t.replace('--color-border-', '')}</code></td>
+                  <td>${why}</td>
+                  <td class="num">${ratio(t, '--color-surface-default') ?? '—'}</td>
+                  <td class="num">${ratio(t, '--color-surface-container') ?? '—'}</td>
+                </tr>`)}
+            </tbody>
+          </table>
+        </div>
+        <h3 style="font-size:var(--typography-fontSize-base);margin:var(--spacing-32) 0 var(--spacing-8)">
+          The same responsibility, on an inverse surface
+        </h3>
+        <p style="max-width:70ch">
+          <code>--color-border-container-inverse</code> is not a second role. It is the same
+          boundary on <code>--color-surface-inverse</code>, the way
+          <code>--color-text-inverse</code> is the same ink — and it exists because no neutral
+          border role can be quiet on a dark ground:
+          <code>--color-border-subtle</code> renders at <b>10.8:1</b> there, where the boundary
+          wants <b>1.42:1</b>. It is written as a proportion of
+          <code>--color-neutral-0</code> rather than a raw rgba, so the value stays traceable to
+          a token.
+        </p>
+        <div style="display:grid;gap:var(--spacing-16);grid-template-columns:repeat(auto-fit,minmax(220px,1fr));max-width:60ch">
+          <div>
+            <p style="margin:0 0 var(--spacing-8);font-family:var(--typography-fontFamily-mono);font-size:var(--typography-fontSize-xs);color:var(--color-text-muted)">
+              on --color-surface-default
+            </p>
+            ${swatch('--color-border-container', '--color-surface-default')}
+          </div>
+          <div>
+            <p style="margin:0 0 var(--spacing-8);font-family:var(--typography-fontFamily-mono);font-size:var(--typography-fontSize-xs);color:var(--color-text-muted)">
+              on --color-surface-inverse
+            </p>
+            ${swatch('--color-border-container-inverse', '--color-surface-inverse')}
+          </div>
+        </div>`
+      })}
+
+      ${refSection({
+        name    : 'Three comparisons that decide the token',
+        meta    : 'boundary vs edge, border vs divider, focus vs border',
+        children: html`
+        <h3 style="font-size:var(--typography-fontSize-base);margin:0 0 var(--spacing-8)">
+          Content boundary vs control edge
+        </h3>
+        <p style="max-width:70ch">
+          The same 1px line, twice. The left one describes an object; the right one describes
+          something you can operate, and clears 3:1 so that claim is legible. Choosing the
+          quieter one for a control is the error the token comment warns about.
+        </p>
+        <div style="display:grid;gap:var(--spacing-16);grid-template-columns:repeat(auto-fit,minmax(200px,1fr));max-width:60ch;margin-bottom:var(--spacing-32)">
+          <div style="padding:var(--spacing-16);border:var(--border-width-1) solid var(--color-border-container);border-radius:var(--radius-2xl)">
+            <bd-p variant="small">Content boundary — an object.</bd-p>
+          </div>
+          <div style="padding:var(--spacing-16);border:var(--border-width-1) solid var(--color-border-default);border-radius:var(--radius-md)">
+            <bd-p variant="small">Control edge — operable.</bd-p>
+          </div>
+        </div>
+
+        <h3 style="font-size:var(--typography-fontSize-base);margin:0 0 var(--spacing-8)">
+          Border vs divider
+        </h3>
+        <p style="max-width:70ch">
+          A border goes round and holds one thing together. A divider goes across and keeps two
+          things apart. A <code>border-top</code> that participates in a grid row is a boundary;
+          a line between two regions is <code>bd-divider-horizontal</code>. Do not convert one
+          into the other for the sake of reuse.
+        </p>
+        <div style="max-width:44ch;margin-bottom:var(--spacing-32)">
+          <div style="padding:var(--spacing-16);border:var(--border-width-1) solid var(--color-border-container);border-radius:var(--radius-2xl)">
+            <bd-p variant="small">Bounded object.</bd-p>
+            <bd-divider-horizontal></bd-divider-horizontal>
+            <bd-p variant="small">Two regions inside it, divided.</bd-p>
+          </div>
+        </div>
+
+        <h3 style="font-size:var(--typography-fontSize-base);margin:0 0 var(--spacing-8)">
+          Focus vs border
+        </h3>
+        <p style="max-width:70ch">
+          Focus is never a border role. The ring is a <code>box-shadow</code> drawn outside the
+          box, so it adds no width and moves no layout — measured across the package, no state
+          in any component changes a border width. A focus treatment that recoloured a border
+          would be invisible to anyone who cannot see the difference, and would fight whatever
+          the border was already saying.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Legitimate exceptions',
+        meta    : 'recorded, not tolerated',
+        children: html`
+        <ul style="max-width:70ch">
+          <li>
+            <b>Pricing Cards</b> used to keep a private <code>--border-card-grey</code> alias
+            at <code>--color-neutral-50</code>, and no longer do. The cards now sit on
+            <code>--color-surface-default</code> over a brand-tinted band and draw
+            <code>--border-width-1 solid --color-border-container</code>, which is the
+            tinted-section half of the ground-and-edge rule rather than an exception to it.
+            The private alias measured 1.07:1 against the card it bounded. The component's
+            architecture is still frozen by product decision; the edge was a colour, not
+            architecture.
+          </li>
+          <li>
+            <b>bd-button's outlined variants</b> draw their edge with an inset
+            <code>box-shadow</code> rather than a border, so the box does not change size
+            between states. That is the reason nothing in the package shifts on hover or focus.
+          </li>
+          <li>
+            <b>The AwardsFlex dot</b> keeps <code>--radius-full</code> on its focus ring: a
+            circular control needs a circular ring.
+          </li>
+          <li>
+            <b>Two on-dark dividers</b> — Terminal's separator line and ProcessSteps' step rule
+            — still carry a raw white alpha. They are the divider responsibility rather than the
+            boundary one, and DIVIDER has no inverse role yet.
+          </li>
+          <li>
+            <b><code>border: 0</code> in screen-reader-only helpers</b> is a clipping technique,
+            not a radius or a boundary decision, and is left alone by every rule here.
+          </li>
+        </ul>`
+      })}
+    `
+  });