@repobit/dex-system-design 1.0.0 → 2.0.0

package/src/tokens/tokens.css

@@ -68,8 +68,11 @@
        t-comma, -0.275em in Bold, a third deeper than g -- and the tallest
        are grave and acute capitals at +0.977em. Measured per weight, ink
        spans 1.174 Light, 1.194 Regular, 1.219 Medium, 1.235 SemiBold,
-       1.252 Bold. Nothing may be set below the floor for its weight, which
-       is why the display roles stay at tight and are not tightened further.
+       1.252 Bold. Tight, 1.25, sits 0.002 under the Bold floor -- the
+       tallest accented capital and the deepest comma-below letter would
+       have to fall in consecutive lines, one above the other, to touch --
+       which is why the display roles stay at tight and are never tightened
+       further.
        Foundations/Typography/Vertical Rhythm reaches 1.231 for 48px Bold
        from canvas metrics; this is the same number from outline bounds. */
     --typography-lineHeight-130: 1.3;
@@ -230,13 +233,12 @@
     /* The CSS default curve. It was missing, and its absence was the single
        reason eleven component transitions could not be expressed in tokens:
        ease is not ease-in-out — it front-loads, and swapping one for the
-       other is a visible change. Named after the keyword, as linear,
-       ease-in and ease-out beside it are; smooth is the outlier that
-       aliases a keyword rather than naming it. */
+       other is a visible change. Named after the keyword, as linear and
+       ease-out beside it are; smooth is the outlier that aliases a keyword
+       rather than naming it. ease-in and a bounce curve stood here too and
+       went on 2026-10-15, because nothing read either. */
     --transition-easing-ease: ease;
-    --transition-easing-ease-in: ease-in;
     --transition-easing-ease-out: ease-out;
-    --transition-easing-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
 
     /* ================================
          CORE SHADOW TOKENS
@@ -248,37 +250,62 @@
         0 4px 6px -4px rgb(0 0 0 / 0.1);
     --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1),
         0 8px 10px -6px rgb(0 0 0 / 0.1);
-    --shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25);
-    --shadow-inner: inset 0 2px 4px 0 rgb(0 0 0 / 0.05);
+    /* The ladder stops at xl. --shadow-2xl and the inset --shadow-inner
+       stood beside it until 2026-10-15, and nothing read either. */
 
-    /* Focus Shadows - Box Shadow Version */
-    --shadow-focus-outline-blue: 0 0 0 3px rgba(6, 109, 255, 0.15);
-    --shadow-focus-outline-red: 0 0 0 3px rgba(239, 68, 68, 0.15);
-    --shadow-focus-outline-green: 0 0 0 3px rgba(34, 197, 94, 0.15);
+    /* The focus glow: --color-blue-500 at 15%, mixed from the palette. It
+       was rgba(6, 109, 255, 0.15) -- a blue one unit off blue-500 -- with a
+       red and a green beside it that were Tailwind's red-500 and green-500,
+       in no palette here. Nothing read the red or the green, so they went;
+       --form-input-focus-boxShadow reads this one. */
+    --shadow-focus-outline-blue: 0 0 0 3px color-mix(in srgb, var(--color-blue-500) 15%, transparent);
 
     /* Focus Outlines - Two-Color System for Universal Visibility */
     --focus-outline-primary: 0 0 0 2px var(--color-neutral-0),
         0 0 0 4px var(--color-blue-500);
-    --focus-outline-secondary: 0 0 0 2px var(--color-neutral-0),
-        0 0 0 4px var(--color-neutral-600);
-    --focus-outline-error: 0 0 0 2px var(--color-neutral-0),
-        0 0 0 4px var(--color-red-500);
-    --focus-outline-success: 0 0 0 2px var(--color-neutral-0),
-        0 0 0 4px var(--color-green-500);
-
-    /* The four above put the WHITE band against the control, which is what
-       keeps them visible on a coloured hero. That fails on a control which
+
+    /* Secondary, error and success rings stood here until 2026-10-15.
+       Nothing read them -- every component rings with primary -- and the
+       success ring was green-500, 2.39:1 against white, under the 3:1 a
+       focus indicator needs. */
+
+    /* The one above puts the WHITE band against the control, which is what
+       keeps it visible on a coloured hero. That fails on a control which
        is itself white: bd-button-link variant="white" measured 1.00:1 for
        the inner band against its own fill and 2.38:1 for the blue band
        against a blue hero, so neither band reached the 3:1 WCAG 2.4.11
        asks of a focus indicator. This one inverts the pair -- dark band
        against the control, white band against the ground -- so the inner
-       band carries the contrast whatever the control is sitting on. */
+       band carries the contrast whatever the control is sitting on.
+
+       This is also what the Figma library draws around a filled or
+       bordered button on a dark or brand ground (focus/ring-inverse).
+       Figma builds a ring from spread shadows, so every band in it is a
+       painted colour, and the band between control and ring has to be
+       chosen per surface. On a brand hero that painted neutral-900 band
+       reads as a black outline. bd-button does not use this one; it draws
+       the outline below, whose gap is not painted at all. */
     --focus-outline-inverse: 0 0 0 2px var(--color-neutral-900),
         0 0 0 4px var(--color-neutral-0);
 
-    /* Traditional Outline Values for Fallback */
+    /* The CTA ring in code: one band, held off the control by
+       --focus-outline-offset. The offset leaves the gap TRANSPARENT, so it
+       is always the surface the control sits on -- white on a light page,
+       neutral-900 on a dark hero, blue on a brand one -- and never merges
+       into a white fill or a white border, which is the job the painted
+       inner band of every two-band ring above does by hand. Figma has no
+       offset outline, which is why its rings paint that gap and need one
+       style per surface; code does not.
+
+       Only the band's colour follows the ground. Blue on light, 4.53:1
+       against white. White on dark and brand, the one colour that clears
+       3:1 on both: 4.53:1 on blue-500, 6.18 on blue-600, 8.56 on blue-700,
+       17.97 on neutral-900. A blue band on a brand hero is 1.00:1.
+
+       An outline also survives forced-colors mode, where a box-shadow ring
+       is not drawn at all. bd-button reads these; see its FOCUS block. */
     --focus-outline-traditional: 2px solid var(--color-blue-500);
+    --focus-outline-traditional-inverse: 2px solid var(--color-neutral-0);
     --focus-outline-offset: 2px;
 
     /* The ring is a box-shadow, so it already follows the radius of the
@@ -428,7 +455,7 @@
     /* Subordinate text on an inverse surface. --color-text-inverse is the
        high-emphasis step there; this is the one below it, and until now the
        system had no such step at all -- the light-side -secondary, -muted and
-       -subtle roles invert to 1.91, 2.73 and 3.85 against
+       -subtle roles invert to 1.91, 2.73 and 3.74 against
        --color-surface-inverse and cannot be used.
 
        Two components had already invented it independently and spelled it
@@ -469,6 +496,14 @@
        the link it borrowed falls to 2.27:1. */
     --color-text-brand-hover: var(--color-blue-700);
     --color-text-success: var(--color-green-800);
+    /* Warning text sits on the page, a card, surface-subtle (5.16) or its
+       own tint (--color-surface-warning, 5.59) -- not on surface-muted,
+       where it measures 4.49:1, a hair under 4.5. The same rule as
+       -subtle above: the role is right and the ground is wrong, so the
+       fix is the ground. Nothing in the package draws the pair today:
+       bd-tag and bd-badge draw this yellow through --status-warning-text,
+       on --status-warning-surface. The way a page reaches it is the
+       color="warning" value the text atoms take (token-scales.js). */
     --color-text-warning: var(--color-yellow-800);
     --color-text-error: var(--color-red-700);
 
@@ -528,7 +563,18 @@
        -subtle is a decorative hairline between things that already belong
        together, not the edge of anything actionable, and disabled controls
        are exempt under 1.4.3. Do not reach for -subtle to outline a
-       control. */
+       control.
+
+       -default's 3.23 holds on white and nowhere darker: on a band it is
+       2.88 (surface-subtle) and 2.51 (surface-muted), and on the brand
+       tint 2.99. So a control drawn in it carries a fill of its own --
+       surface-default, the ground it was measured on -- and its edge is
+       read against that fill wherever it is placed. A field already does
+       (--form-input-default-backgroundColor). A control with no fill, or
+       whose fill IS this colour (the switch's off track), belongs on the
+       page or a card, not on a band. The rule is where it goes; a darker
+       -default would move every field edge in the system to fix a case
+       nothing in the package draws. */
     --color-border-subtle: var(--color-neutral-200);
     --color-border-default: var(--color-neutral-400);
     --color-border-strong: var(--color-neutral-900);
@@ -592,7 +638,9 @@
        this theme, which is why the borrowing never showed -- and both must
        flip to near-black in a dark one, which would turn every label and
        mark dark on its blue or red fill. White clears every action fill:
-       4.53 to 10.51:1. Measured in the Figma Dark mode study. */
+       4.53 to 10.51:1 on the blue and red ones, 13.28 to 21:1 on the
+       near-black secondary ones. Measured in the Figma Dark mode study,
+       and re-measured on the live tokens 2026-10-15. */
     --color-action-on-fill: var(--color-neutral-0);
 
     /* ================================
@@ -721,10 +769,14 @@
        takes, it is whether the longest UNBREAKABLE WORD fits the column.
        The column is the viewport minus twice --grid-padding-*, so a 320px
        phone gives type 288px -- 10% of the screen is gutter. Against that
-       column the ceiling for the worst realistic compound (Finnish
-       "Henkilollisyyssuoja", 9.07px of width per px of size) is 31px.
-       heading-h1 is 48. It overflowed at 375 as well as at 320, in German
-       and Finnish both.
+       column, the widest real words in the nine shipping languages --
+       harvested from live localized copy, see type-ceiling-words.js and
+       plans/LATER.md entry 8 -- set two ceilings: 28px for any copy
+       (Swedish "kalenderinbjudningar", 10.16px of width per px of size)
+       and 31px for headline copy (German "Gründungsmitglied", 9.05).
+       heading-h1 is 48. It overflowed at 375 as well as at 320. (This
+       rested on a Finnish word once; Finnish is not a market, and three
+       real words beat it.)
 
        WHY NOT A BREAKPOINT STEP. Tried first and abandoned, measured:
        stepping h1 to 36 below sm still overflows at 320 (needs 327 of
@@ -766,20 +818,24 @@
        numbers: 30 27 24 21 18 16 for h1 through h6. Its ratios are 1.11,
        1.13, 1.14, 1.17, 1.13 -- near-even, against the desktop ladder's
        irregular 1.33, 1.13, 1.33, 1.20, 1.11. A phone has less range to
-       spend (16 to the 31px ceiling, a factor of 1.94, where desktop has
-       18 to 48, a factor of 2.67), so the ladder has to compress, and
-       compressing it evenly is what keeps six levels distinguishable.
-       Measured: h1 at 30 needs 272px of a 288px column, so there is 16px
-       of margin for a word longer than any tested.
+       spend (16 to the 31px headline ceiling, a factor of 1.94, where
+       desktop has 18 to 48, a factor of 2.67), so the ladder has to
+       compress, and compressing it evenly is what keeps six levels
+       distinguishable. Measured on the harvest: h1 at 30 sets the widest
+       headline word in 272px of a 288px column. The widest word of any
+       tier would need 305, so a headline word wider than 960px per 100px
+       of size is a stated copy constraint (LATER.md entry 8) rather than
+       a margin the ladder holds -- none of the five such words is a
+       headline today.
 
        WHAT IS DELIBERATELY NOT FLUID.
        - Every role at 24px and below except body-lead. Nothing that small
          overflows, and the small end's own failure is measure, not
          overflow -- see below.
        - display-lg, display-xl, display-2xl, display-3xl (60 to 128px).
-         Above display-md the family has NO mobile identity
-         to give it: five roles would all have to squeeze between 30 and
-         the 31px ceiling. They are desktop-only, and a component that
+         Above display-md the family has NO mobile identity to give it:
+         four roles would all have to squeeze between 30 and the 31px
+         headline ceiling. They are desktop-only, and a component that
          needs one of them on a phone should reach for a heading role
          instead. Recorded rather than papered over.
        - body-regular at 16px. It runs 40 characters per line on a 288px
@@ -1011,6 +1067,11 @@
     --typography-caption-default-fontFamily: var(--typography-fontFamily-sans);
     --typography-caption-default-color: var(--color-text-muted);
 
+    /* "small" is not smaller. It is caption-default with the tracking
+       opened to wide -- 0.025em, which is the design's caption/small at
+       2.5% -- and every other axis equal. The repeated axes are the role
+       being complete, as every role is, not a second copy to remove;
+       bd-caption size="sm" reads all five. */
     --typography-caption-small-fontSize: var(--typography-fontSize-xs);
     --typography-caption-small-fontWeight: var(--typography-fontWeight-normal);
     --typography-caption-small-lineHeight: var(--typography-lineHeight-normal);
@@ -1112,28 +1173,43 @@
          COMPONENT TOKENS - FORM
          ================================ */
 
-    /* Form Label Tokens */
-    --form-label-default-fontSize: var(--typography-fontSize-sm);
-    --form-label-default-fontWeight: var(--typography-fontWeight-medium);
-    --form-label-default-lineHeight: var(--typography-lineHeight-normal);
-    --form-label-default-letterSpacing: var(--typography-letterSpacing-normal);
-    --form-label-default-fontFamily: var(--typography-fontFamily-sans);
+    /* Form Label Tokens
+
+       The type of a field's label is the label role's, read through: the
+       default and small rungs were the same five values as
+       --typography-label-default-* and -small-*, written out a second time,
+       so a change to the role would have reached bd-text and missed every
+       form. Colour and margin stay here; they are the form's own and no
+       role carries them.
+
+       Large differs on one axis. Its size is 18px where label-large is
+       16px, set to the large field's own text (--form-input-large-fontSize)
+       so the label and the value read at the same step; a field's own
+       label at size lg, bd-label size=lg and the bd-fieldset legend all
+       render it. That size stays a
+       primitive -- no label role sits at 18px -- and the other four axes
+       are label-large's. */
+    --form-label-default-fontSize: var(--typography-label-default-fontSize);
+    --form-label-default-fontWeight: var(--typography-label-default-fontWeight);
+    --form-label-default-lineHeight: var(--typography-label-default-lineHeight);
+    --form-label-default-letterSpacing: var(--typography-label-default-letterSpacing);
+    --form-label-default-fontFamily: var(--typography-label-default-fontFamily);
     --form-label-default-color: var(--color-text-primary);
     --form-label-default-marginBottom: var(--spacing-4);
 
     --form-label-large-fontSize: var(--typography-fontSize-lg);
-    --form-label-large-fontWeight: var(--typography-fontWeight-medium);
-    --form-label-large-lineHeight: var(--typography-lineHeight-normal);
-    --form-label-large-letterSpacing: var(--typography-letterSpacing-normal);
-    --form-label-large-fontFamily: var(--typography-fontFamily-sans);
+    --form-label-large-fontWeight: var(--typography-label-large-fontWeight);
+    --form-label-large-lineHeight: var(--typography-label-large-lineHeight);
+    --form-label-large-letterSpacing: var(--typography-label-large-letterSpacing);
+    --form-label-large-fontFamily: var(--typography-label-large-fontFamily);
     --form-label-large-color: var(--color-text-primary);
     --form-label-large-marginBottom: var(--spacing-8);
 
-    --form-label-small-fontSize: var(--typography-fontSize-xs);
-    --form-label-small-fontWeight: var(--typography-fontWeight-medium);
-    --form-label-small-lineHeight: var(--typography-lineHeight-normal);
-    --form-label-small-letterSpacing: var(--typography-letterSpacing-wide);
-    --form-label-small-fontFamily: var(--typography-fontFamily-sans);
+    --form-label-small-fontSize: var(--typography-label-small-fontSize);
+    --form-label-small-fontWeight: var(--typography-label-small-fontWeight);
+    --form-label-small-lineHeight: var(--typography-label-small-lineHeight);
+    --form-label-small-letterSpacing: var(--typography-label-small-letterSpacing);
+    --form-label-small-fontFamily: var(--typography-label-small-fontFamily);
     --form-label-small-color: var(--color-text-primary);
     --form-label-small-marginBottom: var(--spacing-4);
 
@@ -1156,11 +1232,14 @@
        three times. Changing them changes no pixel; it changes what the
        package tells a consumer the height is.
 
-       The line box these leave is 2px taller than the content box, because
-       the derivation counts padding but not the 1px border on each edge.
-       Measured at every size: no glyph clips, because an input centres its
-       line and paints into the padding. Correcting it would move a field
-       off its button, so it stays a recorded fact rather than a fix. */
+       The derivation counts padding but not the 1px border on each edge,
+       and the box is border-box, so these heights leave the line box 2px
+       taller than the content box. An input hides that -- it centres its
+       line and paints into the padding -- but a select clips at the
+       content box, and at md its descenders lost their bottoms.
+       Correcting the height would move a field off its button, so the
+       border comes out of the block padding instead: see the note after
+       the size rules in shared/form-field.css.js. */
     --form-input-small-height: calc(
       var(--spacing-8) * 2 + var(--typography-fontSize-sm) * var(--typography-lineHeight-tight)
     );
@@ -1207,16 +1286,13 @@
 
     --form-input-error-backgroundColor: var(--status-error-surface);
     --form-input-error-borderColor: var(--status-error-accent);
-    --form-input-error-placeholderColor: var(--color-red-600);
 
     --form-input-success-backgroundColor: var(--status-success-surface);
     --form-input-success-borderColor: var(--color-green-600);
-    --form-input-success-placeholderColor: var(--color-green-700);
 
     --form-input-disabled-backgroundColor: var(--color-surface-disabled);
     --form-input-disabled-borderColor: var(--color-border-disabled);
     --form-input-disabled-color: var(--color-text-subtle);
-    --form-input-disabled-placeholderColor: var(--color-neutral-400);
 
     /* Form Help Text Tokens */
     --form-help-text-default-fontSize: var(--typography-fontSize-xs);
@@ -1254,9 +1330,6 @@
        32, which is what a form actually wants and what the value is set to
        here. */
     --form-fieldSpacing: var(--spacing-24);
-    --form-sectionSpacing: var(--spacing-32);
-    --form-labelSpacing: var(--spacing-4);
-    --form-helpTextSpacing: var(--spacing-4);
 
     /* ================================
          COMPONENT TOKENS - BUTTON
@@ -1286,15 +1359,14 @@
     --button-large-gap: var(--spacing-8);
     --button-large-borderRadius: var(--radius-lg);
 
-    /* Button Default State */
-    --button-default-backgroundColor: var(--color-neutral-0);
-    --button-default-borderColor: var(--color-neutral-400);
-    --button-default-borderWidth: var(--border-width-1);
-    --button-default-color: var(--color-neutral-900);
-    --button-default-fontFamily: var(--typography-fontFamily-sans);
-    --button-default-fontWeight: var(--typography-fontWeight-medium);
-    --button-default-lineHeight: var(--typography-lineHeight-normal);
-
+    /* Removed 2026-10-15, because nothing read them: the seven
+       --button-default-* (a state no variant draws), and
+       --button-shared-focus-boxShadow, -disabled-opacity and
+       -disabled-cursor (the button draws focus with the outline below and
+       disabled through its own rules). Likewise the three
+       --form-input-*-placeholderColor tokens, the --form-section-,
+       -label- and -helpTextSpacing trio, and two --layout-awards- widths.
+       None was mirrored in Figma, which carries no component tokens. */
     /* Button Shared Tokens */
     --button-shared-fontFamily: var(--typography-fontFamily-sans);
     --button-shared-fontWeight: var(--typography-fontWeight-medium);
@@ -1307,9 +1379,6 @@
     --button-shared-transition-easing: var(--transition-easing-smooth);
     --button-shared-focus-outline: var(--focus-outline-traditional);
     --button-shared-focus-outlineOffset: var(--focus-outline-offset);
-    --button-shared-focus-boxShadow: var(--focus-outline-primary);
-    --button-shared-disabled-opacity: 0.6;
-    --button-shared-disabled-cursor: not-allowed;
 
     /* ---- variant colours -------------------------------------------
        Named for the kind attribute they serve, because that is the public
@@ -1330,10 +1399,12 @@
        wiring them up unchanged would have moved pixels.
 
        The per-variant -focus and -disabled sets are gone. The component
-       draws one focus ring for every variant, from --focus-outline-primary,
-       and one shared disabled treatment; thirty tokens described per-variant
-       versions of both that nothing rendered. --button-empty-* went with
-       them: there is no empty kind. */
+       draws its focus ring as an offset outline -- the blue one through
+       --button-shared-focus-outline by default, the white one from
+       --focus-outline-traditional-inverse under surface="dark" and on
+       white and outline-white -- and one shared disabled treatment;
+       thirty tokens described per-variant versions of both that nothing
+       rendered. --button-empty-* went with them: there is no empty kind. */
 
     /* primary: blue fill */
     --button-primary-background-default: var(--color-action-primary);
@@ -1548,8 +1619,11 @@
     /* Accessibility Spacing Tokens
     -----------------------------------------------*/
     /* Touch Target Sizes - WCAG 2.1 Success Criterion 2.5.5 (AAA) and 2.5.8 (AA) */
-    --touch-target-size: 44px; /* Minimum touch target size (44px × 44px) */
-    --touch-target-spacing: 8px; /* Minimum space between touch targets */
+    /* The dimension steps that carry these values, rather than px
+       literals beside them: a target is matched to a finger, not to the
+       reader's text size, so it is px, which --dimension-* is. */
+    --touch-target-size: var(--dimension-44); /* Minimum touch target size (44px × 44px) */
+    --touch-target-spacing: var(--dimension-8); /* Minimum space between touch targets */
 
     /* Readable Line Lengths - For optimal readability */
     --content-width-readable: 70ch; /* Approximately 70 characters per line */
@@ -1557,18 +1631,21 @@
 
     /** GRID AND BREAKPOINT TOKENS
 
-       These have no consumer in this package and are kept deliberately.
-       A media condition cannot read a custom property — @media
+       The breakpoint tokens have no consumer in this package and are kept
+       deliberately. A media condition cannot read a custom property — @media
        (max-width: var(--breakpoint-sm)) is not valid CSS — so a breakpoint
        token can never be referenced the way a colour is. It exists so the
        six values have one place to be read from, by the lint that checks
        media queries against them and by anything generating CSS. The grid
-       tokens are the same case: a layout that wants them reads them, and
-       nothing in the atom layer does.
-
-       They are the exception. Everything else here that nothing references
-       is dead weight, and the OLD VALUES and FONT TOKENS blocks that used
-       to sit below were removed for exactly that reason.
+       tokens below are read: --grid-container-max-* and --grid-padding-*
+       are the page column, through shared/ensemble.css.js and layout.css,
+       and the header and compare read them too. --grid-gutter-* has no
+       reader outside the blog's own token copy, and carries the same
+       values as --grid-padding-*.
+
+       The breakpoints are the exception. Everything else here that nothing
+       references is dead weight, and the OLD VALUES and FONT TOKENS blocks
+       that used to sit below were removed for exactly that reason.
      */
     /* Grid container max widths */
     --grid-container-max-xs: 100%; /* mobile full width */
@@ -1617,18 +1694,18 @@
 
     /* Awards section — Orbit Frame 14 (node 1882:9342) */
     --layout-awards-section-background: var(--color-blue-50);
-    --layout-awards-banner-max-width: 37.5rem; /* legacy narrow cap; prefer cluster */
     --layout-awards-cluster-max-width: 49.5625rem; /* 793px — trust banner column */
     --layout-awards-intro-max-width: 39.4375rem; /* 631px — headline stack */
-    /* Legacy: narrow lower block from Orbit; prefer --layout-ensemble-content-max for compare-aligned grids */
-    --layout-awards-content-max-width: 53.0625rem; /* 849px */
-    /* There is no page-width token. The page column is an implementation --
+    /* The page column has no width token of its own. --content-width-max,
+       above, is a 1200px cap that no component reads; only the blog's own
+       token copy aliases it. The page column is an implementation --
        src/components/shared/ensemble.css.js -- on the grid container scale
        above (--grid-container-max-* with --grid-padding-*), which is what
        Foundations/Grid System documented and nothing had built. A width token
        here is how six ensembles came to hold one literal each and seven other
-       modules a different one. This padding step stays only because the blog
-       still reads it. */
+       modules a different one. This padding step stays because bd-features
+       reads it for its inline padding; the blog declares its own copy and
+       does not read this one. */
     --layout-ensemble-inline-padding: var(--spacing-24);