@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/tokens/tokens.stories.js

@@ -1,11 +1,26 @@
 import { html } from 'lit';
-import '../components/heading/heading.js';
+import {
+  INK,
+  PAPER,
+  contrast,
+  copyToken,
+  discoverConsumers,
+  docsPage,
+  levelBadge,
+  readAllCssText,
+  refSection,
+  resolve,
+  toHex,
+  usageCell
+} from './story-chrome.js';
 
 export default {
-  title: 'Design Tokens/Colors'
+  title: 'Foundations/Colors',
+  tags : ['autodocs']
 };
 
-const colorGroups = {
+/** Only used if the stylesheets cannot be read (e.g. cross-origin). */
+const FALLBACK_FAMILIES = {
   blue   : ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'],
   red    : ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'],
   green  : ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'],
@@ -13,56 +28,131 @@ const colorGroups = {
   neutral: ['0', '25', '50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950', '1000']
 };
 
-export const Colors = () => html`
+function discoverFamilies(cssText) {
+  const families = new Map();
+  for (const [, family, shade] of cssText.matchAll(/--color-([a-z]+)-(\d+)\s*:/g)) {
+    if (!families.has(family)) families.set(family, new Set());
+    families.get(family).add(shade);
+  }
+  if (!families.size) {
+    for (const [family, shades] of Object.entries(FALLBACK_FAMILIES)) {
+      families.set(family, new Set(shades));
+    }
+  }
+  return [...families].map(([family, shades]) => ({
+    family,
+    shades: [...shades].sort((a, b) => Number(a) - Number(b))
+  }));
+}
+
+const swatchStyles = html`
   <style>
-    .color-group {
-      margin-bottom: 32px;
+    /* Full-bleed swatch column: no padding and no row border, so consecutive
+       rows read as one continuous ramp. */
+    .docs th.col-swatch {
+      padding-left: 0;
+      padding-right: 0;
     }
-    .color-group-title {
-      font-family: var(--font-family-sans);
-      font-weight: 600;
-      font-size: var(--heading-medium);
-      margin-bottom: 16px;
-      text-transform: capitalize;
+
+    .docs td.cell-swatch {
+      padding: 0;
+      width: 104px;
+      border-bottom: 0;
     }
-    .color-swatch {
-      display: inline-flex;
-      flex-direction: column;
+
+    .swatch {
+      min-height: var(--touch-target-size);
+      height: 100%;
+      display: flex;
       align-items: center;
       justify-content: center;
-      width: 80px;
-      height: 80px;
-      margin: 6px;
-      border-radius: 8px;
-      box-shadow: 0 0 4px rgba(0,0,0,0.1);
-      color: white;
-      font-family: var(--font-family-mono);
-      font-size: 12px;
-      text-align: center;
-      user-select: none;
+      gap: var(--spacing-10);
+      /* keeps --color-neutral-0 distinguishable from the page */
+      box-shadow: inset 0 0 0 1px rgb(0 0 0 / 0.1);
     }
-    .color-label {
-      margin-top: 6px;
-      color: var(--color-neutral-900);
-      font-weight: 600;
-      font-family: var(--font-family-sans);
-      font-size: 10px;
-      white-space: nowrap;
+
+    /* Both text colours drawn straight on the swatch, so an illegible
+       pairing genuinely looks illegible. */
+    .probe-aa {
+      font-weight: var(--typography-fontWeight-semibold);
+      font-size: var(--typography-fontSize-sm);
+      line-height: var(--typography-lineHeight-none);
     }
   </style>
+`;
+
+function renderRow(family, shade, consumers) {
+  const token = `--color-${family}-${shade}`;
+  const value = resolve(token);
+  if (!value) return html``;
 
-  ${Object.entries(colorGroups).map(([group, shades]) => html`
-    <section class="color-group">
-      <bd-h as="h4" class="color-group-title">${group}</bd-h>
-      ${shades.map(shade => {
-        const varName = `--color-${group}-${shade}`;
-        return html`
-          <div class="color-swatch" style="background-color: var(${varName})">
-            <div>${shade}</div>
-            <div class="color-label">${varName}</div>
-          </div>
-        `;
-      })}
-    </section>
-  `)}
-`;
+  const onPaper = contrast(value, PAPER);
+  const onInk = contrast(value, INK);
+
+  return html`
+    <tr>
+      <td class="cell-swatch">
+        <div class="swatch" style="background-color: var(${token})">
+          <span class="probe-aa" style="color: ${PAPER}">Aa</span>
+          <span class="probe-aa" style="color: ${INK}">Aa</span>
+        </div>
+      </td>
+      <td class="num">${shade}</td>
+      <td>${copyToken(token)}</td>
+      <td class="mono muted">${toHex(value).toUpperCase()}</td>
+      <td class="num">${onPaper.toFixed(2)}${levelBadge(onPaper)}</td>
+      <td class="num">${onInk.toFixed(2)}${levelBadge(onInk)}</td>
+      <td>${usageCell(consumers.get(token))}</td>
+    </tr>
+  `;
+}
+
+export const Colors = () => {
+  const cssText = readAllCssText();
+  const families = discoverFamilies(cssText);
+  const consumers = discoverConsumers(cssText);
+
+  return html`
+    ${swatchStyles}
+    ${docsPage({
+      title: 'Colour palette',
+      lede : html`Every ramp is read out of the loaded token CSS at render time, so this page
+        always matches <code>src/tokens/tokens.css</code>. Click a token name to copy its
+        <code>var()</code> reference.`,
+      note: html`The two <b>Aa</b> marks on each swatch are white and
+        <code>--color-neutral-900</code> text drawn straight onto that colour, so an illegible
+        pairing looks illegible. The contrast columns give the measured ratio and the WCAG level
+        it reaches for body text: <b>AAA</b> 7.0, <b>AA</b> 4.5, <b>18pt</b> 3.0 (large text and
+        UI edges only), <b>fail</b> below 3.0.`,
+      children: families.map(({ family, shades }) => {
+        const referenced = shades.filter(shade => consumers.has(`--color-${family}-${shade}`)).length;
+
+        return refSection({
+          name    : family,
+          meta    : `${shades.length} steps · ${referenced} referenced by other tokens`,
+          children: html`
+            <div class="table-scroll">
+              <table>
+                <caption>${family} colour ramp</caption>
+                <thead>
+                  <tr>
+                    <th class="col-swatch" scope="col">Swatch</th>
+                    <th scope="col">Step</th>
+                    <th scope="col">Token</th>
+                    <th scope="col">Hex</th>
+                    <th scope="col">On white</th>
+                    <th scope="col">On neutral-900</th>
+                    <th scope="col">Used by</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  ${shades.map(shade => renderRow(family, shade, consumers))}
+                </tbody>
+              </table>
+            </div>
+          `
+        });
+      })
+    })}
+  `;
+};

package/src/tokens/type-ceiling-words.js

@@ -0,0 +1,299 @@
+/**
+ * The word sample the type ceilings are measured against.
+ *
+ * WHY WORDS AND NOT STRINGS. For large type the binding constraint is the
+ * longest UNBREAKABLE WORD, not the length of the sentence -- a word wider
+ * than its column overflows or hyphenates, and neither is a size anyone chose.
+ * So this file holds words.
+ *
+ * NOTHING HERE CARRIES A MEASURED WIDTH. Foundations/Typography -> Why These
+ * Sizes measures every entry live in the browser, because a width measured
+ * once and written down is a width that goes stale -- and the browser and the
+ * Figma file already disagree by about 3.5% on the same word.
+ *
+ * WHERE THESE WORDS COME FROM, as of 2026-09-17: shipped copy. Every entry
+ * marked `production` was harvested from a live localized bitdefender.com
+ * page, and carries the page it came from and the size that page renders it
+ * at. The `representative` compounds this file started with are gone -- they
+ * indicated an order of magnitude and were the reason the ladder could only
+ * ever be provisional. See `harvest` below for the method.
+ *
+ * A JS module rather than the JSON registry it started as: the story needs it
+ * at build time, and a bare JSON import needs an import attribute under Node,
+ * which would break the per-file parse check without breaking the Vite build.
+ * One source, no attributes.
+ */
+export const ceilingWords = {
+  "about"           : "The word sample the type ceilings are measured against. For large type the binding constraint is the longest UNBREAKABLE WORD, not the length of the sentence, so this file holds words rather than strings. Foundations/Typography -> Why These Sizes reads it and measures every entry live in the browser; nothing here carries a measured width, because a width measured once and written down is a width that goes stale.",
+  "howToUpdate"     : "The ask that stood here -- one longest unbreakable token per language from the translation memory -- was answered another way, by harvesting the rendered copy instead of the TM that produced it. To re-run it, follow `harvest` below: it is one script against nine locale URLs and takes minutes. Re-run it when the marketing copy is rewritten, when a language is added to localeMap.js, or before changing any fontSizeMin token.",
+  "sourceVocabulary": {
+    "production"    : "Harvested from a live localized bitdefender.com page: a token that really renders at 24px or larger in that market's copy. Carries `page` and `observedAt`. Stronger evidence than a TM extract, because it is what actually renders rather than a string that might.",
+    "tm"            : "A string from the translation memory. None left -- `production` superseded the ask. Kept in the vocabulary because a TM entry would still be valid evidence for copy that has not shipped yet.",
+    "representative": "A plausible compound written for the study. NONE REMAIN: every one was replaced on 2026-09-17 by a production token in the same language. Kept in the vocabulary so a future gap can be filled honestly rather than silently.",
+    "outlier"       : "Deliberately extreme, kept to show the shape of the failure rather than to set a ceiling. Excluded from the worst case the ladder is calibrated against."
+  },
+  "tiers": {
+    "note"    : "Two tiers, because the question is not only how wide the longest token is but whether it can land in the role that would break. The size a token renders at on bitdefender.com is not our role -- their site, their scale -- but it does classify the COPY: a word set at 40px+ there is headline copy, a word set at 24-32px is feature or subhead copy.",
+    "headline": "observedAt >= 40. Copy that plays the part heading-h1 plays. This is the tier the h1 mobile size has to survive.",
+    "feature" : "observedAt 24-39. Subheads and feature lists. On a phone this copy lands in h3 and below, where the ladder has room -- but it is included in the all-tier worst case, because nothing stops a writer from promoting one of these words into a headline."
+  },
+  "shippingLanguages": {
+    "source"   : "Derived from src/components/footer/localeMap.js, the only locale list in this monorepo. It is the footer's country selector, so treat it as the best available evidence rather than a declared locale contract.",
+    "languages": [
+      "en",
+      "es",
+      "de",
+      "nl",
+      "fr",
+      "pt",
+      "zh",
+      "it",
+      "ro",
+      "sv",
+      "ja"
+    ],
+    "note": "46 locales, 11 languages. Two languages are deliberately absent. Finnish: there is no fi-FI locale at all -- see the `retired` note on the fi entries below. Hungarian: Hungary is served in ENGLISH, at /en-hu/, so the locale is en-HU and Hungarian is not a language this product sells in. That was established 2026-09-17 after the footer was found pointing at /hu-hu/, which 404s; the footer says en-HU now and all 46 roots resolve."
+  },
+  "wrappingCaveats": {
+    "zh": "Chinese wraps between characters, so the longest-word constraint barely applies. The relevant question there is characters per line at ~1em per glyph, which this study does not model.",
+    "ja": "Same as zh, with kinsoku line-breaking rules on top. Not modelled."
+  },
+  "harvest": {
+    "date"  : "2026-09-17",
+    "method": "In a browser on each locale URL below: walk every element, keep the ones whose computed font-size is >= 24px and are not hidden, take their direct text nodes, split on whitespace AND on hyphen, slash, en/em dash and punctuation -- all of them are line-break opportunities, so a hyphenated compound is not one unbreakable token -- strip anything that is not a letter or digit, and keep tokens of 9 characters or more with the largest size each was seen at. Then measure each candidate in IBM Plex Sans 700 at 100px in this package's own token scope and rank by width, not by character count.",
+    "pages" : [
+      "https://www.bitdefender.com/<locale>/consumer/total-security",
+      "https://www.bitdefender.com/<locale>/consumer/ultimate-security"
+    ],
+    "locales": [
+      "en-us",
+      "nl-nl",
+      "de-de",
+      "sv-se",
+      "ro-ro",
+      "fr-fr",
+      "it-it",
+      "es-es",
+      "pt-pt"
+    ],
+    "whyNotCharacterCount": "Character count is a prefilter, not the measurement. Plex is proportional: Romanian `Confidentialitate` and Dutch `Gepersonaliseerde` are both 17 characters and differ by 12% in width, and a 15-character Swedish compound outruns a 17-character Romanian one.",
+    "caveat"              : "These are marketing pages rendered by bitdefender.com's own design system, not by this package. The TOKEN TEXT is the evidence; the size it renders at there is used only to classify the copy into the two tiers above."
+  },
+  "words": [
+    {
+      "lang"      : "en",
+      "word"      : "Recommended",
+      "source"    : "production",
+      "page"      : "en-us/consumer/total-security",
+      "observedAt": 40
+    },
+    {
+      "lang"      : "en",
+      "word"      : "Personalized",
+      "source"    : "production",
+      "page"      : "en-us/consumer/total-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "en",
+      "word"      : "Performance",
+      "source"    : "production",
+      "page"      : "en-us/consumer/total-security",
+      "observedAt": 32
+    },
+    {
+      "lang"      : "sv",
+      "word"      : "kalenderinbjudningar",
+      "source"    : "production",
+      "page"      : "sv-se/consumer/ultimate-security",
+      "observedAt": 24,
+      "note"      : "The widest token in the whole sample. Swedish was in `alsoMissing` as a low-priority gap; it turned out to set the worst case."
+    },
+    {
+      "lang"      : "sv",
+      "word"      : "bedrägeriaviseringar",
+      "source"    : "production",
+      "page"      : "sv-se/consumer/ultimate-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "sv",
+      "word"      : "Rekommenderas",
+      "source"    : "production",
+      "page"      : "sv-se/consumer/total-security",
+      "observedAt": 40,
+      "note"      : "Swedish's widest HEADLINE-tier token, which is the one h1 has to survive."
+    },
+    {
+      "lang"      : "nl",
+      "word"      : "oplichtingsmeldingen",
+      "source"    : "production",
+      "page"      : "nl-nl/consumer/ultimate-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "nl",
+      "word"      : "oplichtingspatronen",
+      "source"    : "production",
+      "page"      : "nl-nl/consumer/ultimate-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "nl",
+      "word"      : "Gepersonaliseerde",
+      "source"    : "production",
+      "page"      : "nl-nl/consumer/total-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "nl",
+      "word"      : "Aanbevolen",
+      "source"    : "production",
+      "page"      : "nl-nl/consumer/total-security",
+      "observedAt": 40,
+      "note"      : "Dutch's widest headline-tier token -- and narrower than English `Recommended`, which is the same word doing the same job. Compounding does not reach the headline here."
+    },
+    {
+      "lang"      : "de",
+      "word"      : "Kalendereinladungen",
+      "source"    : "production",
+      "page"      : "de-de/consumer/ultimate-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "de",
+      "word"      : "Kalenderereignissen",
+      "source"    : "production",
+      "page"      : "de-de/consumer/ultimate-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "de",
+      "word"      : "Benachrichtigungen",
+      "source"    : "production",
+      "page"      : "de-de/consumer/ultimate-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "de",
+      "word"      : "Gründungsmitglied",
+      "source"    : "production",
+      "page"      : "de-de/consumer/ultimate-security",
+      "observedAt": 44,
+      "note"      : "The widest headline-tier token in the sample, in any language, and therefore the word the h1 mobile size is really calibrated against."
+    },
+    {
+      "lang"      : "ro",
+      "word"      : "Confidențialitate",
+      "source"    : "production",
+      "page"      : "ro-ro/consumer/total-security",
+      "observedAt": 32,
+      "note"      : "Was in this file as a `representative` compound and turned out to be real copy, at 32px."
+    },
+    {
+      "lang"      : "ro",
+      "word"      : "abonamentele",
+      "source"    : "production",
+      "page"      : "ro-ro/consumer/ultimate-security",
+      "observedAt": 40
+    },
+    {
+      "lang"      : "fr",
+      "word"      : "Confidentialité",
+      "source"    : "production",
+      "page"      : "fr-fr/consumer/total-security",
+      "observedAt": 32
+    },
+    {
+      "lang"      : "fr",
+      "word"      : "performances",
+      "source"    : "production",
+      "page"      : "fr-fr/consumer/total-security",
+      "observedAt": 40
+    },
+    {
+      "lang"      : "it",
+      "word"      : "personalizzata",
+      "source"    : "production",
+      "page"      : "it-it/consumer/total-security",
+      "observedAt": 32
+    },
+    {
+      "lang"      : "it",
+      "word"      : "disposizione",
+      "source"    : "production",
+      "page"      : "it-it/consumer/total-security",
+      "observedAt": 40
+    },
+    {
+      "lang"      : "es",
+      "word"      : "tranquilamente",
+      "source"    : "production",
+      "page"      : "es-es/consumer/total-security",
+      "observedAt": 32
+    },
+    {
+      "lang"      : "es",
+      "word"      : "Recomendado",
+      "source"    : "production",
+      "page"      : "es-es/consumer/total-security",
+      "observedAt": 40
+    },
+    {
+      "lang"      : "pt",
+      "word"      : "independência",
+      "source"    : "production",
+      "page"      : "pt-pt/consumer/total-security",
+      "observedAt": 24
+    },
+    {
+      "lang"      : "pt",
+      "word"      : "preocupação",
+      "source"    : "production",
+      "page"      : "pt-pt/consumer/total-security",
+      "observedAt": 40
+    },
+    {
+      "lang"   : "fi",
+      "word"   : "Tietoturvaratkaisu",
+      "source" : "representative",
+      "retired": "Finnish does not ship -- there is no fi-FI locale in localeMap.js. Kept only because the ladder committed in 723aa111 was calibrated against the widest of these, so removing them would erase the record of what it was calibrated against. Do not use them to set a new ceiling."
+    },
+    {
+      "lang"   : "fi",
+      "word"   : "Käyttäjätunnukset",
+      "source" : "representative",
+      "retired": "see the note on Tietoturvaratkaisu"
+    },
+    {
+      "lang"   : "fi",
+      "word"   : "Henkilöllisyyssuoja",
+      "source" : "representative",
+      "retired": "see the note on Tietoturvaratkaisu. THIS is the word the mobile ladder was sized against -- and the production harvest has since found three real tokens WIDER than it, in Swedish, Dutch and German."
+    }
+  ],
+  "missing": {
+    "note"         : "NOTHING, as of 2026-09-17. Every shipping language the longest-word model applies to now has a production sample. `unsampledLanguages` below derives to an empty array, and it should stay that way: if a language is added to localeMap.js, this file is one of the places that has to grow with it.",
+    "hungarian"    : "Was the one gap, and it turned out not to be a gap. The study could find no Hungarian copy because THERE IS NONE: Hungary is an English market, served at /en-hu/. The footer had it as hu-HU, which is why /hu-hu/ 404ed and why this file recorded Hungarian as an untested compounding language. Corrected in localeMap.js; Hungarian is no longer claimed as a shipping language.",
+    "notApplicable": [
+      "zh",
+      "ja"
+    ]
+  }
+};
+
+/** Live-sampled languages -- everything not marked `retired`. */
+export const sampledLanguages = [...new Set(
+  ceilingWords.words.filter(w => !w.retired).map(w => w.lang)
+)].sort();
+
+/** Shipping languages with no live sample, minus the two that wrap per character. */
+export const unsampledLanguages = ceilingWords.shippingLanguages.languages
+  .filter(l => !sampledLanguages.includes(l))
+  .filter(l => !Object.keys(ceilingWords.wrappingCaveats).includes(l))
+  .sort();
+
+/** The tier a word's copy belongs to; see `ceilingWords.tiers`. */
+export const tierOf = word => (word.observedAt >= 40 ? 'headline' : 'feature');
+
+export default ceilingWords;