@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/atoms.stories.js

@@ -0,0 +1,342 @@
+import { html } from 'lit';
+import { docsPage, readAllCssText, refSection, resolve } from '../tokens/story-chrome.js';
+
+// every atom rendered below
+import './heading/heading.js';
+import './paragraph/paragraph.js';
+import './display/display.js';
+import './link/link.js';
+import './highlight/highlight.js';
+import './list/list-item/list-item.js';
+import './button/button.js';
+import './back/back.js';
+import './input/input.js';
+import './dropdown/dropdown.js';
+import './checkbox/checkbox.js';
+import './radio/radio.js';
+import './image/image.js';
+import './badge/badge.js';
+import './divider/divider-horizontal.js';
+import './divider/divider-vertical.js';
+import './icons/plus-icon.js';
+import './icons/globe-icon.js';
+import './icons/close-icon.js';
+import './label/label.js';
+import './help-text/help-text.js';
+import './caption/caption.js';
+import './code/code.js';
+import './annotation/annotation.js';
+import './blockquote/blockquote.js';
+import './textarea/textarea.js';
+import './switch/switch.js';
+import './fieldset/fieldset.js';
+import './tag/tag.js';
+import './avatar/avatar.js';
+import './spinner/spinner.js';
+import './progress/progress.js';
+import './tooltip/tooltip.js';
+import './alert/alert.js';
+import './skeleton/skeleton.js';
+import './video/video.js';
+import './visually-hidden/visually-hidden.js';
+import './picture/picture.js';
+
+export default {
+  title: 'Atoms/Overview',
+  tags : ['autodocs']
+};
+
+const styles = html`
+  <style>
+    .atom-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+      gap: var(--spacing-16);
+    }
+
+    .atom {
+      border: var(--border-width-1) solid var(--color-neutral-100);
+      border-radius: var(--radius-md);
+      overflow: hidden;
+    }
+
+    .atom-head {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      gap: var(--spacing-8);
+      padding: var(--spacing-8) var(--spacing-12);
+      background: var(--color-neutral-50);
+      border-bottom: var(--border-width-1) solid var(--color-neutral-100);
+    }
+
+    .atom-name {
+      font-weight: var(--typography-fontWeight-semibold);
+      font-size: var(--typography-fontSize-sm);
+    }
+
+    .atom-tags {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-500);
+      text-align: right;
+      overflow-wrap: anywhere;
+    }
+
+    /* specimens vary wildly in size, so give each one a settled floor */
+    .atom-body {
+      padding: var(--spacing-16) var(--spacing-12);
+      min-height: var(--spacing-64);
+      display: flex;
+      align-items: center;
+      gap: var(--spacing-8);
+      flex-wrap: wrap;
+    }
+
+    .gap-table td:first-child,
+    .gap-table th:first-child {
+      white-space: nowrap;
+    }
+
+    .where {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+    }
+
+    .where[data-state='blog'] { color: var(--color-blue-700); }
+    .where[data-state='tokens'] { color: var(--color-green-800); }
+    .where[data-state='none'] { color: var(--color-neutral-500); }
+
+    .count {
+      font-weight: var(--typography-fontWeight-semibold);
+    }
+  </style>
+`;
+
+/* ============================================================
+   What we have
+   ============================================================ */
+
+const ATOMS = [
+  ['Heading', 'typography', ['bd-h'],
+    html`<bd-h as="h4">Heading</bd-h>`],
+  ['Paragraph', 'typography', ['bd-p'],
+    html`<bd-p variant="regular">Body copy in a paragraph.</bd-p>`],
+  ['Display', 'typography', ['bd-display'],
+    html`<bd-display variant="sm">Display</bd-display>`],
+  ['Link', 'typography', ['bd-link'],
+    html`<bd-link href="#">A text link</bd-link>`],
+  ['Highlight', 'typography', ['bd-highlight'],
+    html`<bd-highlight>Highlighted</bd-highlight>`],
+  ['List item', 'typography', ['bd-li'],
+    html`<bd-li>A single list item</bd-li>`],
+  ['Button', 'action', ['bd-button', 'bd-button-link', 'bd-contact-button'],
+    html`<bd-button size="sm" variant="primary">Button</bd-button>`],
+  ['Back', 'action', ['bd-back'],
+    html`<bd-back label="Back"></bd-back>`],
+  ['Input', 'form', ['bd-custom-input', 'bd-custom-input-clipboard'],
+    html`<bd-custom-input label="Email" placeholder="you@example.com"></bd-custom-input>`],
+  ['Dropdown', 'form', ['bd-custom-dropdown'],
+    html`<bd-custom-dropdown label="Plan"></bd-custom-dropdown>`],
+  ['Checkbox', 'form', ['bd-checkbox'],
+    html`<bd-checkbox label="Remember me"></bd-checkbox>`],
+  ['Radio', 'form', ['bd-radio', 'bd-toggle-radio'],
+    html`<bd-radio name="p" value="a" label="Option"></bd-radio>`],
+  ['Image', 'media', ['bd-img'],
+    html`<bd-img src="/images/bd-header-img.jpg" alt="" width="120" height="70"></bd-img>`],
+  ['Picture', 'media', ['bd-picture'],
+    html`<span class="atom-tags">responsive &lt;picture&gt; with sources</span>`],
+  ['Icon', 'media', ['12 × bd-*-icon'],
+    html`<bd-plus-icon size="md"></bd-plus-icon>
+        <bd-globe-icon size="md"></bd-globe-icon>
+        <bd-close-icon size="md"></bd-close-icon>`],
+  ['Brand mark', 'media', ['8 × wordmark / award'],
+    html`<span class="atom-tags">fixed colour and aspect — off the icon scale</span>`],
+  ['Badge', 'feedback', ['bd-badge'],
+    html`<bd-badge tone="primary" variant="fill">New</bd-badge>
+         <bd-badge tone="success">Save 44%</bd-badge>
+         <bd-badge mode="count" tone="error" variant="fill">3</bd-badge>
+         <bd-badge mode="dot" tone="warning" variant="fill"></bd-badge>`],
+  ['Divider', 'separation', ['bd-divider-horizontal', 'bd-divider-vertical'],
+    html`<span style="display:block;width:100%"><bd-divider-horizontal></bd-divider-horizontal></span>`],
+  ['Label', 'form', ['bd-label'],
+    html`<bd-label required>Email address</bd-label>`],
+  ['Help text', 'form', ['bd-help-text'],
+    html`<bd-help-text tone="error">Enter a valid email address.</bd-help-text>`],
+  ['Textarea', 'form', ['bd-textarea'],
+    html`<bd-textarea rows="2" placeholder="Tell us more"></bd-textarea>`],
+  ['Switch', 'form', ['bd-switch'],
+    html`<bd-switch checked label="Real-time protection"></bd-switch>`],
+  ['Fieldset', 'form', ['bd-fieldset'],
+    html`<bd-fieldset legend="Alerts"><bd-switch label="Email"></bd-switch></bd-fieldset>`],
+  ['Caption', 'typography', ['bd-caption'],
+    html`<bd-caption>Source: Bitdefender Labs</bd-caption>`],
+  ['Code', 'typography', ['bd-code'],
+    html`<bd-code>var(--radius-md)</bd-code>`],
+  ['Blockquote', 'typography', ['bd-blockquote'],
+    html`<bd-blockquote attribution="Bitdefender Labs">Threats move fast.</bd-blockquote>`],
+  ['Annotation', 'typography', ['bd-footnote', 'bd-citation', 'bd-sup', 'bd-sub'],
+    html`<span style="font-family: var(--typography-fontFamily-sans)">99.8%<bd-footnote href="#n">1</bd-footnote>
+        · <bd-citation href="#">Report</bd-citation> · mc<bd-sup>2</bd-sup></span>`],
+  ['Tag', 'feedback', ['bd-tag'],
+    html`<bd-tag tone="brand">Brand</bd-tag> <bd-tag tone="success">Success</bd-tag>`],
+  ['Alert', 'feedback', ['bd-alert'],
+    html`<bd-alert tone="warning" heading="Check this.">Two devices are out of date.</bd-alert>`],
+  ['Spinner', 'feedback', ['bd-spinner'],
+    html`<bd-spinner></bd-spinner>`],
+  ['Progress', 'feedback', ['bd-progress'],
+    html`<span style="display:block;width:100%"><bd-progress value="64" label="Scan"></bd-progress></span>`],
+  ['Tooltip', 'feedback', ['bd-tooltip'],
+    html`<bd-tooltip text="Blocks trackers"><bd-badge>Hover</bd-badge></bd-tooltip>`],
+  ['Skeleton', 'feedback', ['bd-skeleton'],
+    html`<span style="display:block;width:100%"><bd-skeleton lines="2"></bd-skeleton></span>`],
+  ['Avatar', 'media', ['bd-avatar'],
+    html`<bd-avatar name="Ada Lovelace"></bd-avatar>`],
+  ['Video', 'media', ['bd-video'],
+    html`<span class="atom-tags">&lt;video&gt; with poster and controls</span>`],
+  ['Visually hidden', 'utility', ['bd-visually-hidden'],
+    html`<span class="atom-tags">in the a11y tree, out of view</span>`]
+];
+
+/* The headline count is ATOMS.length, so a name listed twice inflates it and
+   renders a duplicate card. That is exactly what happened: bd-picture was
+   added a second time and the section claimed 37 atoms where 36 exist.
+   Nothing checked, because a duplicate is a perfectly valid array. */
+const duplicateAtoms = ATOMS.map(([name]) => name)
+  .filter((name, i, all) => all.indexOf(name) !== i);
+if (duplicateAtoms.length) {
+  console.warn(`Atoms/Overview lists ${duplicateAtoms.length} atom(s) twice: ${duplicateAtoms.join(', ')}`
+    + ' — the card grid and the headline count are both wrong until this is fixed.');
+}
+
+
+/* ============================================================
+   What is missing
+   ============================================================ */
+
+const GAPS = [
+  // atom, category, state, why
+  ['Keyboard key', 'utility', 'none', 'deliberately skipped — no product surface documents shortcuts yet']
+];
+
+const STATE_LABEL = { tokens: 'tokens only', blog: 'blog only', none: 'not built' };
+
+/** Tokens belonging to an atom that was never built, counted from the loaded CSS. */
+function orphanTokenCount() {
+  const css = readAllCssText();
+  const groups = [
+    'typography-caption', 'typography-code', 'form-help-text', 'footnote', 'citation', 'math'
+  ];
+  return groups.reduce(
+    (total, g) => total + (css.match(new RegExp(`--${g}-[A-Za-z0-9-]+\\s*:`, 'g')) || []).length,
+    0
+  );
+}
+
+export const Overview = () => {
+  return html`
+    ${styles}
+    ${docsPage({
+      title: 'Atoms',
+      lede : html`The smallest useful pieces of the system. An atom here renders one UI primitive,
+        is not built out of other <code>bd-*</code> components, and would mean nothing broken down
+        further. Anything composed of atoms stays under <b>Components</b>.`,
+      note: html`<b>${ATOMS.length}</b> atoms, every one styled only from design tokens —
+        <code>npm run lint:tokens</code> fails on a literal. <b>${orphanTokenCount()}</b> tokens
+        that previously had no component to use them now do: caption, code, help text, footnote,
+        citation and maths notation were fully specified in the token layer and never built.`,
+      children: html`
+        ${refSection({
+          name    : 'What we have',
+          meta    : `${ATOMS.length} atoms`,
+          children: html`
+            <div class="atom-grid">
+              ${ATOMS.map(
+                ([name, cat, tags, specimen]) => html`
+                  <div class="atom">
+                    <div class="atom-head">
+                      <span class="atom-name">${name}</span>
+                      <span class="atom-tags">${cat}</span>
+                    </div>
+                    <div class="atom-body">${specimen}</div>
+                    <div class="atom-head" style="border-bottom: 0; border-top: var(--border-width-1) solid var(--color-neutral-100)">
+                      <span class="atom-tags" style="text-align: left">${tags.join(' · ')}</span>
+                    </div>
+                  </div>
+                `
+              )}
+            </div>
+          `
+        })}
+
+        ${refSection({
+          name    : 'Still missing',
+          meta    : `${GAPS.length} against common practice`,
+          children: html`
+            <div class="table-scroll">
+              <table class="gap-table">
+                <caption>Atoms absent from the main system</caption>
+                <thead>
+                  <tr>
+                    <th scope="col">Atom</th>
+                    <th scope="col">Category</th>
+                    <th scope="col">State</th>
+                    <th scope="col">Where it already half-exists</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  ${GAPS.map(
+                    ([name, cat, state, where]) => html`
+                      <tr>
+                        <td>${name}</td>
+                        <td class="muted">${cat}</td>
+                        <td><span class="where" data-state=${state}>${STATE_LABEL[state]}</span></td>
+                        <td class="where" data-state=${state}>${where || '—'}</td>
+                      </tr>
+                    `
+                  )}
+                </tbody>
+              </table>
+            </div>
+          `
+        })}
+
+        ${refSection({
+          name    : 'Tokens that finally have a component',
+          children: html`
+            <div class="docs-note">
+              <p style="margin: 0 0 var(--spacing-8)">
+                Six groups — caption, code, help text, footnote, citation and maths notation —
+                carried <b>${orphanTokenCount()}</b> tokens between them with <b>zero</b> component
+                references. They were designed and never built. Each now has an atom that consumes
+                nothing but those tokens: <code>bd-caption</code> takes its size from
+                <code>--typography-caption-default-fontSize</code>
+                (<code>${resolve('--typography-caption-default-fontSize')}</code>),
+                <code>bd-help-text</code> its tones from
+                <code>--form-help-text-error-color</code> and
+                <code>--form-help-text-success-color</code>, and so on.
+              </p>
+              <p style="margin: 0">
+                Auditing the token layer for orphaned groups turned out to be a reliable way to
+                find missing components — the design decisions were already made and written down.
+              </p>
+            </div>
+          `
+        })}
+
+        ${refSection({
+          name    : 'What stayed under Components',
+          children: html`
+            <div class="docs-note">
+              Everything composed of atoms: breadcrumb, card, accordion, tabs and the tab list it is
+              built from, carousel, features,
+              header, footer, modal, pricing cards, compare, awards, terms and the video player.
+              Introducing <b>Molecules</b> and <b>Organisms</b> tiers would split those further;
+              this section deliberately only draws the first line.
+            </div>
+          `
+        })}
+      `
+    })}
+  `;
+};

package/src/components/avatar/avatar.css.js

@@ -0,0 +1,67 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const avatarCSS = css`
+  :host { display: inline-flex; }
+
+  .avatar {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--dimension-40);
+    height: var(--dimension-40);
+    border-radius: var(--radius-full);
+    overflow: hidden;
+    /* The brand tint, chosen for what it means -- the disc carries brand
+       identity -- not for its value. It read blue-100 from the palette, which
+       no theme could reach: in dark its text-brand initials measured 2.68:1.
+       The only role holding blue-100 is info's surface-strong, and an avatar
+       is not info. On the brand tint the initials read 5.72:1 in light and
+       5.10 in dark. The disc is fainter on the page than it was (1.08:1 from
+       1.25); the initials identify the avatar, not its edge. Dark mode
+       decision 14. */
+    background: var(--status-brand-surface);
+    /* The brand ink. DECIDED, and it trades contrast for consistency rather than
+       gaining any: blue-700 measured 6.86:1 on the blue-100 disc and the role is
+       blue-600 at 4.95:1 -- still comfortably over the 3:1 bar for a mark, and over
+       4.5:1 if these initials are read as text. blue-700 was never required here
+       (blue-500 already cleared the disc at 3.64:1), so it was a local choice; the
+       role is what every other mark in the package asks for. Those ratios were
+       on the old blue-100 disc; on the brand tint it is 5.72:1. */
+    color: var(--color-text-brand);
+    font-family: var(--typography-fontFamily-sans);
+    /* no role: this renders the user's initials as a glyph -- sized and
+       weighted for legibility inside a fixed-diameter circle, not running text
+       that a role describes. The leading below is already sanctioned under
+       typography rule 7; these two axes are the same glyph-box decision, and
+       no role in the vocabulary means "two letters centred in a 40px disc". */
+    font-size: var(--typography-fontSize-sm);
+    /* no role: the weight is part of the glyph-box decision the comment above
+       describes. */
+    font-weight: var(--typography-fontWeight-semibold);
+    line-height: var(--typography-lineHeight-none);
+    flex: none;
+  }
+
+  :host([size='sm']) .avatar {
+    width: var(--dimension-24);
+    height: var(--dimension-24);
+    /* no role: the same glyph-box decision the base rule above argues, at a
+       24px diameter instead of 40. The size ladder is the disc's ladder --
+       each rung is picked so two letters still fit and stay legible inside
+       that circle -- so it is not a type-role ladder that a role family could
+       answer. */
+    font-size: var(--typography-fontSize-xxs);
+  }
+
+  :host([size='lg']) .avatar {
+    width: var(--dimension-64);
+    height: var(--dimension-64);
+    /* no role: as the sm rung above -- the same glyph box at a 64px diameter. */
+    font-size: var(--typography-fontSize-lg);
+  }
+
+  img { width: 100%; height: 100%; object-fit: cover; display: block; }
+`;
+
+export default avatarCSS;

package/src/components/avatar/avatar.js

@@ -0,0 +1,42 @@
+import { LitElement, html } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { avatarCSS } from './avatar.css.js';
+import { resolveSize } from '../shared/prop-vocabulary.js';
+
+export class BdAvatar extends LitElement {
+  static styles = [avatarCSS];
+
+  static properties = {
+    src : { type: String },
+    name: { type: String },
+    size: { type: String, reflect: true }
+  };
+
+  constructor() {
+    super();
+    this.src = '';
+    this.name = '';
+    this.size = 'md';
+  }
+
+  willUpdate(changed) {
+    // small / default / large still resolve; see shared/prop-vocabulary.js
+    if (changed.has('size')) this.size = resolveSize(this.size, 'md');
+  }
+
+  render() {
+    return html`
+      <span class="avatar" role="img" aria-label=${this.name || 'Avatar'}>
+        ${this.src
+          ? html`<img src=${this.src} alt="" />`
+          : html`${this.name.split(' ').map(w => w[0] || '')
+            .join('')
+            .slice(0, 2)
+            .toUpperCase()}`}
+      </span>
+    `;
+  }
+}
+
+customElements.define('bd-avatar', BdAvatar);

package/src/components/avatar/avatar.stories.js

@@ -0,0 +1,95 @@
+import { html } from 'lit';
+import './avatar.js';
+
+export default {
+  title     : 'Atoms/Avatar',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdAvatar** shows a person as an image, falling back to their initials when
+there is no image.
+
+### Usage
+\`\`\`html
+<bd-avatar src="/images/ada.jpg" name="Ada Lovelace"></bd-avatar>
+<bd-avatar name="Ada Lovelace"></bd-avatar>
+<bd-avatar name="Ada Lovelace" size="lg"></bd-avatar>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`src\` | image URL — omit to fall back to initials | \`''\` |
+| \`name\` | the person's name | \`''\` |
+| \`size\` | \`small\`, \`default\`, \`large\` | \`default\` |
+
+### Always pass a name
+\`name\` does two jobs. It is the source of the initials when there is no \`src\`,
+and it is the accessible name in both cases — the wrapper carries
+\`role="img"\` with \`aria-label\` from \`name\`, and the inner image is given an
+empty \`alt\` so it is not announced twice.
+
+Without a \`name\` the accessible name falls back to the literal string
+"Avatar", which tells a screen reader user nothing. Pass one even when you have
+an image.
+
+### How the initials are derived
+The first letter of each whitespace-separated word, capped at two characters
+and upper-cased. So "Ada Lovelace" gives AL, "Ada" gives A, and "Ada Byron
+Lovelace" gives **AB** rather than AL — it takes the first two words, not the
+first and last.
+        `
+      }
+    }
+  },
+  argTypes: {
+    src: {
+      control    : 'text',
+      description: 'Image URL. Omit and the initials from `name` are shown instead.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
+    },
+    name: {
+      control    : 'text',
+      description: 'The person. Source of the initials and of the accessible name — always pass it.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
+    },
+    size: {
+      control    : { type: 'select' },
+      options    : ['small', 'default', 'large'],
+      description: 'Diameter of the avatar.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+    }
+  }
+};
+
+export const Initials = () => html`
+    <bd-avatar name="Ada Lovelace"></bd-avatar>
+  `;
+
+export const Sizes = () => html`
+    <bd-avatar size="sm" name="Ada Lovelace"></bd-avatar>
+    <bd-avatar name="Ada Lovelace"></bd-avatar>
+    <bd-avatar size="lg" name="Ada Lovelace"></bd-avatar>
+  `;
+
+/**
+ * The image path, which until P6B nothing rendered: both stories used the
+ * initials fallback, so the img the component draws when `src` is set was never
+ * in the DOM and its rule never matched. The docs block showed an /images/ada.jpg
+ * that has never existed in src/assets.
+ */
+export const WithImage = () => html`
+    <bd-avatar src="/images/tabs-img1.png" name="Ada Lovelace"></bd-avatar>
+    <bd-avatar size="lg" src="/images/tabs-img2.png" name="Grace Hopper"></bd-avatar>
+  `;
+
+/**
+ * A src that cannot load. The alt is empty by design -- the accessible name is on
+ * the wrapper's aria-label -- so a broken image should leave the avatar silent
+ * rather than announcing a filename.
+ */
+export const BrokenImage = () => html`
+    <bd-avatar src="/nonexistent-image.png" name="Ada Lovelace"></bd-avatar>
+  `;