/* @webcommerciale/os v0.113.0 */ /* ========================================================================== @webcommerciale/os One import for everything: @import '@webcommerciale/os'; Everything lives inside a single named layer with its own sub-layers. The previous system declares bare `tokens, base, components, utilities`, so a project holding both would land them in the same layers and interleave two cascades. Prefixes stop the class names colliding; only nesting stops the cascade colliding. Order inside the layer is the order of increasing specificity of intent: tokens hold values, base holds element defaults, roles name what things are, components are the assembled objects, utilities are the residue and therefore last. ========================================================================== */ @layer ds { @layer tokens, base, roles, components, utilities; @layer tokens { /* Tokens: the primitives, and nothing else. No token here is named after a component. If a value only makes sense inside one component, it belongs in that component's file, where it can be read next to the thing it serves. The type scale is deliberately absent, and step 4 brings it in with the roles rather than before them. Publishing a raw size ramp now would hand everyone a way to set type before there is a way to name it, and that is the exact order that produced 891 hand-built text elements in the system this one replaces. See ROADMAP.md. */ /* ========================================================================== Colour Two scales and seven groups of roles, counted on 20 August 2026 because the line said four and had said four since there were four. Nothing here is named after a component, and nothing is named after a CSS property: `surface` is a place a thing sits on, not `background-color`. A token called `bg-accent-blue` would imply a page background that is accent blue, which is not a thing this system has. Light is the default. Dark re-declares the same names on [data-theme="dark"], so a component never asks which theme it is in, and it repeats this file's order so the two read side by side. THE ORDER IS THE DEPENDENCY, as far as it can be. A group that reads another group's token sits below it, which is why Interactive comes before Border: `--ds-border-active` is `var(--ds-interactive)` and used to name a token declared further down the file. Two references still point forward, Brand and Status both reading `--ds-static-white`, and they stay: moving Utility above them would put the odds and ends in the middle of the colour groups AND invert the range `npm run check` uses to find the statuses, which is bounded by `--ds-success:` and `--ds-static-white:` and goes silently empty backwards. Named here rather than left to be rediscovered. THE NEUTRALS ARE A RAMP, and `scripts/ramp.mjs` is it: one hue, one chroma curve, and a lightness grid that every grey in this file stands on. Before 20 August 2026 they were Tailwind's zinc written out by hand, and the ramp had already been left eight times, every escape a line or a secondary ink and every one forced by a contrast measurement. Zinc's steps run 1.8 to 16.0 apart in OKLCH lightness and three of the eight landed inside the two sixteen-point gaps: the values the system kept needing were the ones the borrowed ramp did not have. The grid hangs from the light page at lightness 98.5 and steps down by 2, forty-three rungs to 14.5. Two is what the snippet's ground fixes rather than a preference: the syntax palette clears 4.5:1 on a ground of 96.4 and fails under it, so the well sits at 96.5, one rung down from the page, with one 8-bit step of margin and no more: that rung is #f3f3f4 at 4.52 and the next value darker, #f2f2f4, measures 4.49. A step of 3 puts the well at 95 and takes the green and the amber under AA. `npm run check` reads the ramp and fails on any neutral that is not one of its rungs, so a ninth hand-picked grey cannot be written here. What it does NOT cover is the seventeen chromatic values, which are Tailwind steps still: they were walked up their own ramps until the contrast check passed and they pass, and D4 left them where they are. ========================================================================== */ :root { /* --- Surfaces: a scale, numbered because position IS the meaning ------- Each level sits ON TOP OF the one before it. Pick by what your element is stacked on, never by how light or dark you want it: in dark the scale climbs and in light it inverts, because nothing goes lighter than a white card. Same numbers, opposite direction, one decision to make. */ --ds-surface-0: #fafafa; /* the page itself, behind everything */ --ds-surface-1: #ffffff; /* a card, a panel, a sheet sitting on the page */ --ds-surface-2: #f3f3f4; /* a field, a row, a well inside that card */ --ds-surface-3: #e6e6e8; /* a chip or a thumbnail inside that; the deepest the stack goes */ /* A disabled control loses its tone entirely and lands on one grey, so a row of them reads as one dead row instead of three tinted ones, which means the fill, the outline and the label all move together. They used to sit in a section of their own for that reason, and it put the answer to "what grey is a switched-off border" three ladders away from every other border in the system. */ --ds-surface-disabled: #f3f3f4; /* the fill of a control that is switched off */ /* A state is a different axis and does not get a level. An active row is not stacked higher than its neighbours, it is selected. */ /* A state is a wash and not a step of the ladder above. These were surface 2 and surface 3, which is a whole storey of the stack for a row that is only being pointed at: on a dark page the hovered row read as a raised panel and the selected one as two. A wash also lands correctly on whatever surface the row happens to sit on, which a fixed colour cannot. */ --ds-surface-hover: rgb(10 10 13 / 0.04); /* a row or a card under the pointer, before it is chosen */ --ds-surface-active: rgb(10 10 13 / 0.08); /* the row that is selected, and stays selected */ /* --- Text: three neutrals, named by the job they do -------------------- Primary is the default for anything with content in it. Secondary is the lesser half of a pair and needs a primary beside it. Tertiary is decorative only and does not reach 4.5:1 on every surface, so never content. `-neutral` is part of the name because the status colours below can also be text: primary-neutral against danger is the distinction that makes both readable at a glance. The three sit on a ramp of their own, and the ramp is what makes high contrast a shift rather than a second palette: `data-contrast="high"` points secondary at ink 1 and tertiary at ink 2, so every value it lands on is one the theme already chose. See tokens/access.css. The ink names are internal and a page never types one. A colour used directly is a colour nothing can move. */ --ds-ink-1: #0a0a0d; --ds-ink-2: #53535c; --ds-ink-3: #6f6f79; --ds-text-primary-neutral: var(--ds-ink-1); /* anything with content in it: a heading, a paragraph, a value */ --ds-text-secondary-neutral: var(--ds-ink-2); /* the lesser half of a pair, and only beside a primary */ --ds-text-tertiary-neutral: var(--ds-ink-3); /* 4.48:1 on the disabled fill. An inactive control is exempt from the contrast rules and that is not a reason to make it invisible: a reader still has to see WHICH control is unavailable. */ --ds-text-disabled: #6f6f79; /* the label of a control that is switched off */ /* --- Interactive: the neutral that reacts to a pointer ------------------ */ --ds-interactive: #3e3d46; /* a neutral that answers a pointer: an icon button, a sort arrow */ --ds-interactive-tint: rgb(62 61 70 / 0.1); /* the wash behind a quiet neutral control */ --ds-interactive-tint-hover: rgb(62 61 70 / 0.18); /* that wash, deeper, under the pointer */ --ds-interactive-edge: rgb(62 61 70 / 0.2); /* the line around a quiet neutral control */ /* --- Border ------------------------------------------------------------- The lines: between two things, around a card, around a control. Four, and the fourth is a state. The surfaces have had `-hover` and `-active` since the first commit and the borders had neither, which meant a selected card could change its fill and not its outline: half a state. `-active` is the interactive neutral rather than a fifth grey, so the border of a chosen thing and the control that reacts to a pointer are the same colour by construction and not by coincidence. `-strong` moved from #a1a1aa. Anything that identifies a component or its state owes 3:1 under WCAG 1.4.11, and #a1a1aa measured 2.46 on the page here and 2.57 in dark: an input outline nobody with low vision could find. Checked now, for every border except `-subtle`, which is a divider and is meant to be barely there. */ /* The owner brought this line and its dark twin from another system, because what they replaced equalled `--ds-surface-3` in light and was invisible on the surface it drew round. They came at a different hue from everything around them, 219 and 232 against the greys' 286, so a field's outline was a colder colour than the field. On the ramp now, at the hue the surfaces use, and holding the weight they were brought for: 1.51:1 on white against the 1.27 of the value they replaced. */ --ds-border: #d2d2d6; /* the line of a CONTROL at rest: a field, an outlined button */ /* The line that separates rather than bounds: a row from the next row, a head from a body, a strip from the list under it. Quieter than the control line and equal to no surface, which is what killed the last one: it was #f4f4f5, byte for byte `--ds-surface-2`, so every divider it drew measured 1.00:1 against the ground it was drawn on and a table went its whole life with no row lines. Measured now: 1.33:1 on a sheet, 1.27 on the page, 1.20 in a well, against the control line's 1.51. */ --ds-border-subtle: #dfdfe2; /* The rung that clears 3:1 on the deepest ground a control stands on, and the deepest ground is what decides how far this can go. Measured 3.10 on surface 3, 3.48 in a well, 3.86 on a sheet. One rung darker is ink round every control: zinc 500, which this used to sit half a step from, reads 4.63 against the page. */ /* A line that DRAWS A SHAPE rather than encloses a box, which is the job the owner named on 12 September 2026 after reading the eight rules that take it: the ring round a face, the box of a checkbox, the dashed target of a drop zone, the node on a roadmap's path, the zero line and the cursor on a chart, the alert's edge, the page-links border. A box that merely holds something takes `--ds-border` and the resting rule, 50 uses to 8. Read the shape, not the container. */ --ds-border-strong: #81818a; /* Half way between the resting line and the strong one, so being switched off is a colour and not only a fill. It was #e4e4e7, the same value as `--ds-border`, so a disabled field and a resting one had the identical outline and only the fill said anything: measured 1.55:1 on the fill it sits on against 1.15 before. */ --ds-border-disabled: #c5c5cb; /* the outline of a control that is switched off */ --ds-border-active: var(--ds-interactive); /* the outline of the control that is chosen or focused */ /* --- Inverse: a dark block in a light theme, and the text on it --------- */ --ds-inverse: #17171b; /* a block that quotes the page back at itself: a filled neutral button, a dark banner */ --ds-on-inverse: #fafafa; /* the label on that block, whichever way round the theme has it */ /* Lighter on the way down, because this one is already the darkest thing on a light page and there is nowhere below it to go. The label flips with the theme, which is what `inverse` means: this is the page quoted back at itself, so it is white on black here and black on white in dark. */ --ds-inverse-hover: #25252b; /* that block under the pointer */ --ds-inverse-active: #3e3d46; /* that block while it is held down */ /* Ink on the inverse block, beyond the one label: the block IS the other theme's page quoted, so these are the other theme's own vetted values, rung for rung. The lesser line is the dark theme's ink-2, and the four tone marks are the dark theme's tone inks, whose worst pairs are written beside them in the block below. Born 22 August 2026 for the toast, the first component to put a full sentence on the inverse ground. */ --ds-secondary-on-inverse: #b2b2b9; --ds-success-on-inverse: #4ade80; --ds-warning-on-inverse: #fbbf24; --ds-danger-on-inverse: #fca5a5; --ds-info-on-inverse: #7dd3fc; /* --- Brand: one hook, meant to be overridden per project ---------------- The tint and the edge are mixed FROM the brand rather than written as their own hex, so a project that re-points --ds-brand gets a matching wash for free. The status colours below are literal because they are the system's own and nobody overrides them; this one exists to be overridden, and a hardcoded tint would survive the override and clash with it. */ --ds-brand: #2563eb; /* the fill of the one action a page wants: the primary button, the checked box */ --ds-on-brand: var(--ds-static-white); /* the label on the brand fill, white in both themes on purpose (5.17:1) */ --ds-brand-hover: color-mix(in srgb, var(--ds-brand) 85%, black); /* that fill under the pointer */ --ds-brand-active: color-mix(in srgb, var(--ds-brand) 72%, black); /* that fill while it is held down */ --ds-brand-tint: color-mix(in srgb, var(--ds-brand) 10%, transparent); /* the wash behind a quiet brand thing: a selected tab, a soft badge */ --ds-brand-tint-hover: color-mix(in srgb, var(--ds-brand) 18%, transparent); /* that wash, deeper, under the pointer */ --ds-brand-edge: color-mix(in srgb, var(--ds-brand) 20%, transparent); /* the line around a brand-tinted block */ /* Darkened rather than picked, for the same reason the tint is mixed: the brand is the one colour a project replaces, and a hand-picked ink would survive the replacement. */ --ds-brand-ink: color-mix(in srgb, var(--ds-brand) 78%, black); /* the brand as TEXT on the page: a link, a brand label */ /* A TONE MAY BE A LINE where the line is the signal, ruled 12 September 2026. Eight rules paint a border with a fill: a field, a code field and the editor go `--ds-danger` when what they hold is broken, and the current tab, the chosen chip and today's square go `--ds-inverse` because being the one you are on is the whole of what the line says. The `-edge` values below are not that: they are the 20% line around a TINTED BLOCK, which is a container's outline and would be a whisper under a field that failed. A tone gains no third value; where the line carries the meaning, the fill is what draws it. */ /* --- Status -------------------------------------------------------------- What happened, in four colours built the same way each time. Status and not state. A state is what an element is doing under a pointer or a keyboard, hovered, held, chosen, and the four rules for those are above. These four report an outcome, and an element wearing one is not in a state at all: a badge is green because the thing it names succeeded, not because anybody is touching it. Called `States` here until 20 August 2026, which put two sections under one word on the colour page, since that page reads these markers for its headings. Five parts each, and every suffix means the same thing everywhere: the bare name is the fill, `-tint` is a wash behind it, `-edge` is the line around it, `-ink` is the colour as text, `-on-` is the label on the fill. `-on` is the fourth part, and it is not decoration: a status used as a BACKGROUND needs a text colour that survives on it, and white is the wrong answer more often than not. White on this green measures 3.3:1 and on this amber 3.2:1, both under AA, while black measures 6.4 and 6.6. `-ink` is the fifth, and it exists because the bare name cannot do two jobs. A status colour is chosen to be SEEN as a block, and a colour chosen to be seen as a block is too light to be read as text on a pale one: the green 600 this replaced measured 3.16:1 on the page and 2.95 on its own tint, the amber 600 3.05 and 2.86. Every coloured label and every soft badge in the system was under AA and looked fine, which is the whole problem with judging contrast by eye. Both are measurements. `npm run check` asserts every `-on` against the colour it names and every `-ink` against all four surfaces AND against its own tint over each of them, and the values below were picked by walking the ramp until it passed rather than by choosing a shade. */ /* Green 700 and not 600. A filled control carries white, and white on 600 measures 3.30, which is what made this label black while brand and danger carried white. Same green in both themes, same reason as those two: a filled thing is one decision. */ --ds-success: #15803d; /* the fill of a success block: a solid badge, a confirm button */ --ds-success-hover: #166534; /* that fill under the pointer */ --ds-success-active: #14532d; /* that fill while it is held down */ --ds-success-tint: rgb(21 128 61 / 0.1); /* the wash behind a quiet success block */ --ds-success-tint-hover: rgb(21 128 61 / 0.18); /* that wash, deeper, under the pointer */ --ds-success-edge: rgb(21 128 61 / 0.2); /* the line around it */ --ds-success-ink: #166534; /* success as TEXT: "Published", a passing count */ --ds-on-success: var(--ds-static-white); /* the label on the success fill (5.01:1) */ /* Amber 700. Six hundred measures 3.19 against white, and every filled thing in this system carries white, so the amber comes to the label rather than the label going to the amber. It is a browner amber than the one people picture, and that is what carrying white costs. */ --ds-warning: #b45309; /* the fill of a warning block */ --ds-warning-tint: rgb(180 83 9 / 0.1); /* the wash behind a quiet warning block */ --ds-warning-edge: rgb(180 83 9 / 0.2); /* the line around it */ --ds-warning-ink: #92400e; /* warning as TEXT: "Expires in 3 days" */ --ds-on-warning: var(--ds-static-white); /* the label on the warning fill (5.02:1) */ --ds-danger: #dc2626; /* the fill of a destructive control or a failure block */ --ds-danger-hover: #b91c1c; /* that fill under the pointer */ --ds-danger-active: #991b1b; /* that fill while it is held down */ --ds-danger-tint: rgb(220 38 38 / 0.1); /* the wash behind a quiet danger block: an error panel */ --ds-danger-tint-hover: rgb(220 38 38 / 0.18); /* that wash, deeper, under the pointer */ --ds-danger-edge: rgb(220 38 38 / 0.2); /* the line around it, and around a field that failed */ --ds-danger-ink: #991b1b; /* danger as TEXT: the message under a broken field (5.67:1) */ --ds-on-danger: var(--ds-static-white); /* the label on the danger fill (4.83:1) */ /* Cyan, and no longer the brand's blue. It was #2563eb, which IS the brand to the pixel, so an info block and a brand block were the same object wearing two names and neither said anything the other did not. It also carries white at 5.93, where the blue at its dark end did not. */ --ds-info: #0369a1; /* the fill of an informational block, which is a container and not a button */ --ds-info-tint: rgb(3 105 161 / 0.1); /* the wash behind a quiet info block */ --ds-info-edge: rgb(3 105 161 / 0.2); /* the line around it */ --ds-info-ink: #075985; /* info as TEXT, when a sentence is the whole notice */ --ds-on-info: var(--ds-static-white); /* the label on the info fill (5.93:1) */ /* --- Utility ------------------------------------------------------------- Four that belong to no ladder. The two static ones are for text over a photograph, where the theme is irrelevant because the backdrop is not a surface, so they hold the same value in both. Focus is its own token rather than the brand, because a brand can be a pale yellow and this ring has to hold contrast on every surface the system ships. It is the page's own opposite and not the blue every framework reaches for: blue is a colour this system spends on the brand, and a ring that is nearly black on a light screen and nearly white on a dark one is the highest contrast either theme has to offer. A project that wants a coloured ring changes this one token and every ring in the system moves, which is the point of it having a token at all. */ /* The wash over the page behind a panel that has to be closed. Its own token because two of them would disagree the day a modal lands beside the drawer. Light: enough to say the page is not yours, not enough to hide it. It was 40% and that turned the page into a photograph of itself, which is louder than the panel it is meant to sit behind. */ --ds-scrim: rgb(10 10 13 / 0.2); /* ── Hues ──────────────────────────────────────────────────────────────── Twelve colours that MEAN nothing: not a status, not the brand, but the colour a reader gave an option of their own, "High" red because they said so. A tone says what happened; a hue says which one this is. The same five parts a tone has, so a badge reads either with one rule, and each vetted the way a tone is: the ink over every surface and over its own tint in both themes. Tailwind's ramps like the tones, 700 for the fill under a white label, 800 for the ink on the light theme. */ --ds-hue-red: #b91c1c; --ds-hue-red-tint: rgb(185 28 28 / 0.12); --ds-hue-red-edge: rgb(185 28 28 / 0.25); --ds-hue-red-ink: #991b1b; --ds-on-hue-red: var(--ds-static-white); --ds-hue-orange: #c2410c; --ds-hue-orange-tint: rgb(194 65 12 / 0.12); --ds-hue-orange-edge: rgb(194 65 12 / 0.25); --ds-hue-orange-ink: #9a3412; --ds-on-hue-orange: var(--ds-static-white); --ds-hue-amber: #b45309; --ds-hue-amber-tint: rgb(180 83 9 / 0.12); --ds-hue-amber-edge: rgb(180 83 9 / 0.25); --ds-hue-amber-ink: #92400e; --ds-on-hue-amber: var(--ds-static-white); --ds-hue-yellow: #a16207; --ds-hue-yellow-tint: rgb(161 98 7 / 0.12); --ds-hue-yellow-edge: rgb(161 98 7 / 0.25); --ds-hue-yellow-ink: #854d0e; --ds-on-hue-yellow: var(--ds-static-white); --ds-hue-lime: #4d7c0f; --ds-hue-lime-tint: rgb(77 124 15 / 0.12); --ds-hue-lime-edge: rgb(77 124 15 / 0.25); --ds-hue-lime-ink: #3f6212; --ds-on-hue-lime: var(--ds-static-white); --ds-hue-green: #15803d; --ds-hue-green-tint: rgb(21 128 61 / 0.12); --ds-hue-green-edge: rgb(21 128 61 / 0.25); --ds-hue-green-ink: #166534; --ds-on-hue-green: var(--ds-static-white); --ds-hue-teal: #0f766e; --ds-hue-teal-tint: rgb(15 118 110 / 0.12); --ds-hue-teal-edge: rgb(15 118 110 / 0.25); --ds-hue-teal-ink: #115e59; --ds-on-hue-teal: var(--ds-static-white); --ds-hue-cyan: #0e7490; --ds-hue-cyan-tint: rgb(14 116 144 / 0.12); --ds-hue-cyan-edge: rgb(14 116 144 / 0.25); --ds-hue-cyan-ink: #155e75; --ds-on-hue-cyan: var(--ds-static-white); --ds-hue-blue: #1d4ed8; --ds-hue-blue-tint: rgb(29 78 216 / 0.12); --ds-hue-blue-edge: rgb(29 78 216 / 0.25); --ds-hue-blue-ink: #1e40af; --ds-on-hue-blue: var(--ds-static-white); --ds-hue-indigo: #4338ca; --ds-hue-indigo-tint: rgb(67 56 202 / 0.12); --ds-hue-indigo-edge: rgb(67 56 202 / 0.25); --ds-hue-indigo-ink: #3730a3; --ds-on-hue-indigo: var(--ds-static-white); --ds-hue-violet: #6d28d9; --ds-hue-violet-tint: rgb(109 40 217 / 0.12); --ds-hue-violet-edge: rgb(109 40 217 / 0.25); --ds-hue-violet-ink: #5b21b6; --ds-on-hue-violet: var(--ds-static-white); --ds-hue-pink: #be185d; --ds-hue-pink-tint: rgb(190 24 93 / 0.12); --ds-hue-pink-edge: rgb(190 24 93 / 0.25); --ds-hue-pink-ink: #9d174d; --ds-on-hue-pink: var(--ds-static-white); --ds-static-white: #ffffff; /* text over a photograph, where the theme is irrelevant */ --ds-static-black: #000000; /* the same, the other way up */ --ds-focus: #17171b; /* the ring a keyboard leaves behind, and nothing else */ /* --- Syntax --------------------------------------------------------------- Four for code, and the only place in the system where colour says what KIND of word something is rather than what state something is in. Inside a snippet that is what a reader wants, and nothing in there has a state to report. Measured against one background and not four. A snippet paints its own ground, surface 2, precisely so this palette has a single known thing to hold against: on surface 3 two of these fall under 4.5, and there is no reason to put code there. */ --ds-syntax-string: #15803d; /* anything in quotes */ --ds-syntax-keyword: #7c3aed; /* the words of the language: import, const, @media */ --ds-syntax-number: #b45309; /* numbers, and the custom properties that hold them */ --ds-syntax-name: #0369a1; /* what a thing is called: an element, a prop, a flag */ /* --- Charts --------------------------------------------------------------- Five for data, and the second place colour says WHICH rather than what state: a series is a series, and painting the second one `--ds-danger` would put an alarm on a line that only means "mobile". Categorical on purpose, and the values are shadcn's own CURRENT chart quintet, hue for hue, their oklch converted to hex because the check's parser reads hex and nothing else. Warm here, vivid in dark: each theme carries the pairing that was designed for it. A chart that MEANS a tone, a danger threshold, a success band, reaches for the tone by name instead. */ --ds-chart-1: #f54900; /* the first series: orange */ --ds-chart-2: #009689; /* teal */ --ds-chart-3: #104e64; /* deep petrol */ --ds-chart-4: #ffb900; /* gold */ --ds-chart-5: #fe9a00; /* amber */ /* ── The maker's mark ────────────────────────────────────────────────── WebCommerciale's logo, as the maker draws it, in the two versions the maker supplied: the dark one for a light ground, the light one for a dark ground. Four inks: the wordmark's first word and the main dots, the second word, and the two quieter dots. Not opacities of one ink: the light version is not the dark one faded, it is a different drawing. Read only by `site-credits.css`. */ --ds-maker-word-1: #141413; --ds-maker-word-2: #666666; --ds-maker-dot-2: #808080; --ds-maker-dot-3: #999999; /* The symbol alone, the dots without the words, has two inks in the maker's file: the main dots and one quieter grey. */ --ds-maker-symbol-dot: #999999; } [data-theme="dark"] { --ds-surface-0: #0a0a0d; --ds-surface-1: #17171b; --ds-surface-2: #25252b; --ds-surface-3: #3e3d46; --ds-surface-disabled: #25252b; --ds-surface-hover: rgb(250 250 250 / 0.05); --ds-surface-active: rgb(250 250 250 / 0.09); --ds-ink-1: #fafafa; /* Between two rungs that both fail it for different reasons, which is why zinc had nothing here: its 400 (#a1a1aa) measures 4.18:1 on surface 3 and its 300 (#d4d4d8) is close enough to primary to lose the pair. This holds 5.08:1, the nearest rung that clears AA on every dark surface. Found by the contrast check, not by looking. */ --ds-ink-2: #b2b2b9; --ds-ink-3: #6f6f79; --ds-text-primary-neutral: var(--ds-ink-1); --ds-text-secondary-neutral: var(--ds-ink-2); --ds-text-tertiary-neutral: var(--ds-ink-3); /* 4.29:1 on the disabled fill. An inactive control is exempt from the contrast rules and that is not a reason to make it invisible: a reader still has to see WHICH control is unavailable. */ --ds-text-disabled: #6f6f79; /* 3.07:1 on the disabled fill */ --ds-interactive: #d2d2d6; --ds-interactive-tint: rgb(210 210 214 / 0.1); --ds-interactive-tint-hover: rgb(210 210 214 / 0.2); --ds-interactive-edge: rgb(210 210 214 / 0.2); --ds-border: #43434b; --ds-border-subtle: #2e2e35; /* 1.33:1 on a sheet, 1.47 on the page */ /* The dark theme had the outline of a control at 7.8 against the page while the light theme had it at 4.8, so the same button was a line on one and a lit box on the other. This holds 6.01 on the page, 5.43 on surface 1 and 4.63 on surface 2, which is the light theme's relationship in the dark theme's colours, and 3.26 on surface 3, clear of the three to one a control's edge has to keep. */ --ds-border-strong: #8d8d96; --ds-border-disabled: #53535c; /* 2.00:1 on the disabled fill, was 1:1 */ --ds-border-active: var(--ds-interactive); --ds-inverse: #fafafa; --ds-on-inverse: #17171b; /* Darker on the way down, for the same reason and in the other direction. */ --ds-inverse-hover: #e6e6e8; --ds-inverse-active: #d2d2d6; /* Ink on the inverse block: the light theme's own values, because here the block is the light page quoted. Same reasoning as the light block's. */ --ds-secondary-on-inverse: #53535c; --ds-success-on-inverse: #166534; --ds-warning-on-inverse: #92400e; --ds-danger-on-inverse: #991b1b; --ds-info-on-inverse: #075985; /* The same blue as light, which is the whole idea: a filled button is one decision and not two. White measures 5.17 on it, and it measures 3.83 against the page, so it is a visible object carrying readable text. The lifted #3b82f6 it replaced measured 3.68 against white, which is why the label used to turn black here. */ --ds-brand: #2563eb; /* Every status is lifted in dark so it holds against a near-black page, and lifting it is exactly what makes white text fail on top of it: all four measure between 3.7 and 3.8 against white and between 5.6 and 9.7 against black. A bright chip with dark text is the shape a dark theme wants anyway. Asserted by `npm run check`. */ --ds-on-brand: var(--ds-static-white); /* 5.17:1 */ /* Lifted rather than darkened: on a near-black page the way to say "you are on it" is more light, not less. */ --ds-brand-hover: color-mix(in srgb, var(--ds-brand) 80%, white); --ds-brand-active: color-mix(in srgb, var(--ds-brand) 65%, white); --ds-brand-tint: color-mix(in srgb, var(--ds-brand) 15%, transparent); --ds-brand-tint-hover: color-mix(in srgb, var(--ds-brand) 25%, transparent); --ds-brand-edge: color-mix(in srgb, var(--ds-brand) 30%, transparent); /* Lightened here, for the same reason every status ink is. */ /* Half and half now that the brand itself is darker. At 62% it landed at 3.98 on surface 3; at 50% its worst pair is 4.58, measured by hand because color-mix is the one value `npm run check` cannot resolve and says so. */ --ds-brand-ink: color-mix(in srgb, var(--ds-brand) 50%, white); --ds-success: #15803d; --ds-success-hover: #166534; --ds-success-active: #14532d; --ds-success-tint: rgb(21 128 61 / 0.15); --ds-success-tint-hover: rgb(21 128 61 / 0.25); --ds-success-edge: rgb(21 128 61 / 0.3); --ds-success-ink: #4ade80; /* worst pair 5.59:1 */ --ds-on-success: var(--ds-static-white); --ds-warning: #b45309; --ds-warning-tint: rgb(180 83 9 / 0.15); --ds-warning-edge: rgb(180 83 9 / 0.3); --ds-warning-ink: #fbbf24; /* worst pair 5.87:1 */ --ds-on-warning: var(--ds-static-white); /* Same red as light, same reason as the brand. White measures 4.83 on it and it measures 4.09 against the page. */ --ds-danger: #dc2626; --ds-danger-hover: #b91c1c; --ds-danger-active: #991b1b; --ds-danger-tint: rgb(220 38 38 / 0.15); --ds-danger-tint-hover: rgb(220 38 38 / 0.25); --ds-danger-edge: rgb(220 38 38 / 0.3); --ds-danger-ink: #fca5a5; /* worst pair 5.33:1 */ --ds-on-danger: var(--ds-static-white); /* 4.83:1 */ --ds-info: #0369a1; --ds-info-tint: rgb(3 105 161 / 0.15); --ds-info-edge: rgb(3 105 161 / 0.3); --ds-info-ink: #7dd3fc; --ds-on-info: var(--ds-static-white); --ds-focus: #fafafa; /* A touch heavier, because the same wash over a near-black page barely registers. Still short of the 60% it was. */ --ds-scrim: rgb(10 10 13 / 0.35); --ds-syntax-string: #4ade80; --ds-syntax-keyword: #c4b5fd; --ds-syntax-number: #fbbf24; --ds-syntax-name: #7dd3fc; /* The chart palette, shadcn's dark quintet: the light one's warm five read as mud on near-black, so dark carries the vivid pairing that was designed for it. */ --ds-chart-1: #1447e6; /* electric blue */ --ds-chart-2: #00bc7d; /* green */ --ds-chart-3: #fe9a00; /* amber */ --ds-chart-4: #ad46ff; /* violet */ --ds-chart-5: #ff2056; /* raspberry */ /* The hues, on the dark ground: the fill stays, the ink is the 300 of the ramp so it reads on every surface and over its own wash, the wash a little thinner than the light theme's: 400 measured 3.07:1 over it. */ --ds-hue-red: #b91c1c; --ds-hue-red-tint: rgb(248 113 113 / 0.14); --ds-hue-red-edge: rgb(248 113 113 / 0.35); --ds-hue-red-ink: #fca5a5; --ds-on-hue-red: var(--ds-static-white); --ds-hue-orange: #c2410c; --ds-hue-orange-tint: rgb(251 146 60 / 0.14); --ds-hue-orange-edge: rgb(251 146 60 / 0.35); --ds-hue-orange-ink: #fdba74; --ds-on-hue-orange: var(--ds-static-white); --ds-hue-amber: #b45309; --ds-hue-amber-tint: rgb(251 191 36 / 0.14); --ds-hue-amber-edge: rgb(251 191 36 / 0.35); --ds-hue-amber-ink: #fcd34d; --ds-on-hue-amber: var(--ds-static-white); --ds-hue-yellow: #a16207; --ds-hue-yellow-tint: rgb(250 204 21 / 0.14); --ds-hue-yellow-edge: rgb(250 204 21 / 0.35); --ds-hue-yellow-ink: #fde047; --ds-on-hue-yellow: var(--ds-static-white); --ds-hue-lime: #4d7c0f; --ds-hue-lime-tint: rgb(163 230 53 / 0.14); --ds-hue-lime-edge: rgb(163 230 53 / 0.35); --ds-hue-lime-ink: #bef264; --ds-on-hue-lime: var(--ds-static-white); --ds-hue-green: #15803d; --ds-hue-green-tint: rgb(74 222 128 / 0.14); --ds-hue-green-edge: rgb(74 222 128 / 0.35); --ds-hue-green-ink: #86efac; --ds-on-hue-green: var(--ds-static-white); --ds-hue-teal: #0f766e; --ds-hue-teal-tint: rgb(45 212 191 / 0.14); --ds-hue-teal-edge: rgb(45 212 191 / 0.35); --ds-hue-teal-ink: #5eead4; --ds-on-hue-teal: var(--ds-static-white); --ds-hue-cyan: #0e7490; --ds-hue-cyan-tint: rgb(34 211 238 / 0.14); --ds-hue-cyan-edge: rgb(34 211 238 / 0.35); --ds-hue-cyan-ink: #67e8f9; --ds-on-hue-cyan: var(--ds-static-white); --ds-hue-blue: #1d4ed8; --ds-hue-blue-tint: rgb(96 165 250 / 0.14); --ds-hue-blue-edge: rgb(96 165 250 / 0.35); --ds-hue-blue-ink: #93c5fd; --ds-on-hue-blue: var(--ds-static-white); --ds-hue-indigo: #4338ca; --ds-hue-indigo-tint: rgb(129 140 248 / 0.14); --ds-hue-indigo-edge: rgb(129 140 248 / 0.35); --ds-hue-indigo-ink: #c7d2fe; --ds-on-hue-indigo: var(--ds-static-white); --ds-hue-violet: #6d28d9; --ds-hue-violet-tint: rgb(167 139 250 / 0.14); --ds-hue-violet-edge: rgb(167 139 250 / 0.35); --ds-hue-violet-ink: #c4b5fd; --ds-on-hue-violet: var(--ds-static-white); --ds-hue-pink: #be185d; --ds-hue-pink-tint: rgb(244 114 182 / 0.14); --ds-hue-pink-edge: rgb(244 114 182 / 0.35); --ds-hue-pink-ink: #f9a8d4; --ds-on-hue-pink: var(--ds-static-white); /* The maker's mark on a dark ground: the dark version mirrored, white where it was black, and the two quieter greys under it. The file the maker supplied as the light version had the first word in mid grey and read as faded on the site; the owner, 18 September 2026. */ --ds-maker-word-1: #ffffff; --ds-maker-word-2: #999999; --ds-maker-dot-2: #999999; --ds-maker-dot-3: #808080; /* The symbol on a dark ground is all white, as the maker's file has it. */ --ds-maker-symbol-dot: #ffffff; } /* --- The inverse ground, as a scope --------------------------------------- `data-ground="inverse"` on the element that paints `--ds-inverse` behind whole sentences: the toast wears it on its root and the site section's inverse band wears it now too. An axis like the surfaces and the radii, held in this file because these are colours and the literals live here. Two things happen inside, and the split matters: The NEUTRAL text names flip to what reads on the block, so a component that speaks in `--ds-text-*-neutral` keeps speaking without knowing where it stands. Only the neutrals: the `inverse` and `on-inverse` names stay the page's own, because the wearer paints its ground FROM them on the very element that carries the attribute, and because `button.css` answers this attribute by reading them as the ground's own pair since the toast was born. Flipping them broke both at once: the toast's field took the page's colour, and the banner button's label took the band's. The QUOTE family is the page's own pair, kept reachable on the block under names of its own: what a filled control on the ground becomes, because the block is the page quoted back at itself and a control standing on it is quoted back. Its hover and active are the other column's inverse pair, which is the vetted answer to "how does this fill move under the pointer" for a fill of exactly this colour. Cross-wired as literals, the way `--ds-secondary-on-inverse` already is: every value below is a rung the two columns already hold. An alias cannot say this on one element: a name reading the neutral while the neutral is being flipped on the same element is a cycle, and a cycle resolves both names to the guaranteed-invalid value. */ [data-ground="inverse"] { /* In light the block is dark: the dark column's inks read on it. */ --ds-text-primary-neutral: #fafafa; --ds-text-secondary-neutral: #b2b2b9; /* The light page, quoted onto its own dark block. */ --ds-quote: #fafafa; --ds-on-quote: #0a0a0d; --ds-quote-hover: #e6e6e8; --ds-quote-active: #d2d2d6; } [data-theme="dark"] [data-ground="inverse"] { /* In dark the block is light: the light column's inks read on it. */ --ds-text-primary-neutral: #0a0a0d; --ds-text-secondary-neutral: #53535c; /* The dark page, quoted onto its own light block. */ --ds-quote: #0a0a0d; --ds-on-quote: #fafafa; --ds-quote-hover: #25252b; --ds-quote-active: #3e3d46; } /* A panel opened from the inverse ground stands on the page, not on the ground: a popover, a dialog and a drawer are page surfaces in the top layer, and each is still a DOM child of the bar that opened it, so it inherited the flipped inks and drew the page's ink on the page's surface. The selection bar's Set menu came out empty and its dialog unreadable (owner, 11 September 2026). The page's own inks are read back by their theme names, which the ground never flips, so one rule serves both themes; `button.css` steps aside inside the same three. */ [data-ground="inverse"] :is(.ds-popover, .ds-dialog, .ds-drawer) { --ds-text-primary-neutral: var(--ds-ink-1); --ds-text-secondary-neutral: var(--ds-ink-2); } /* ========================================================================== Space A ramp, and three named distances built on it. The ramp is the raw material: numbers, in 4px steps, no opinions. The three named distances are the opinions, and they are the ones a page should reach for. A layout that spells out a ramp value at every level has taken the same decision many times; a layout that says "these are one element" has taken it once. The three named distances (element, block, section) are NOT here: they change with the surface, so they live in surface.css where both columns can be read side by side. On a marketing page an element gap of 16px reads as one group; on a dashboard the same 16px reads as loose. ========================================================================== */ :root { --ds-space-0: 0; --ds-space-px: 1px; --ds-space-0-5: 0.125rem; /* 2px */ --ds-space-1: 0.25rem; /* 4px */ --ds-space-2: 0.5rem; /* 8px */ --ds-space-3: 0.75rem; /* 12px */ --ds-space-4: 1rem; /* 16px */ --ds-space-5: 1.25rem; /* 20px */ --ds-space-6: 1.5rem; /* 24px */ --ds-space-8: 2rem; /* 32px */ --ds-space-10: 2.5rem; /* 40px */ --ds-space-12: 3rem; /* 48px */ --ds-space-16: 4rem; /* 64px */ --ds-space-20: 5rem; /* 80px */ --ds-space-24: 6rem; /* 96px */ --ds-space-32: 8rem; /* 128px */ } /* ========================================================================== Control heights Six, and they are the heights of things you can press or type into: a button, a field, a select, an icon button, a segmented control. Not a space ramp, which is the distance BETWEEN things; this is how tall a thing is. They live here rather than inside any one component because they are the same six everywhere. Two controls on one row have to be exactly as tall as each other or the row is visibly crooked, and two files writing `2.5rem` at each other is a match that holds until one of them is edited. There is one ladder, and a row lines up because both ends read the same tier. The floor is 24px, which is what WCAG 2.5.8 asks of a target. Nothing in this system is allowed below it, so the ramp starts there rather than offering a step that would have to be documented as unusable. In rem, so the whole ladder grows with `data-text`. ── What is written inside them ─────────────────────────────────────────── One map, for every control that stands on a tier, so two controls on one row read at one size as well as standing at one height: 24 small 12/16 48 body 16/24 32 label 14/20 56 body 16/24 40 body 16/24 64 body 16/24 It stops at body. The level above it is fluid on the web surface, 18px growing to 20 with the window, and its leading is a ratio rather than a multiple of the 4px step: a word that changes size inside a box whose height is fixed by this ramp. Tabs, accordion and the tallest field each reached for it and each has been brought back. Four levels for six tiers, so the top four share one. A 64px control with a 16px word in it is held together by the room at its sides, which every component here takes in em and therefore off the size. Each component writes the pair onto the element that wears it, never into a variable: a font token varies with the surface and an alias resolves where it is declared, not where it is read. This paragraph is the only place the map is stated; a component that disagrees with it is the one that is wrong. ========================================================================== */ :root { --ds-size-1: 1.5rem; /* 24px, the smallest target WCAG allows */ --ds-size-2: 2rem; /* 32px */ --ds-size-3: 2.5rem; /* 40px, the one a form uses by default */ --ds-size-4: 3rem; /* 48px */ --ds-size-5: 3.5rem; /* 56px */ --ds-size-6: 4rem; /* 64px */ } /* ── The width the fluid sizes measure against ──────────────────────────── The window, and something else where something else is the truth. Three sizes and one rhythm in this system grow with the room: a headline is 56 on a phone and 80 on a desk, and it gets there through `vw`. `vw` is the WINDOW, which is right on a page and wrong the moment a page is shown inside a frame narrower than the window: the docs draw a 430 canvas and the headline in it stayed at the desk's 80, one word to a line. Container units would read the nearest container, and this package already makes five things containers — a header, a toolbar, a pagination — so a heading inside any of them would have measured itself against a bar. A declared width has one owner and no ambiguity: the window says `100vw` and anything drawing a frame says its own width instead. Nothing else has to change for it: a page that never sets it behaves exactly as it did. */ :root { --ds-viewport: 100vw; } /* ── The widths a layout changes its mind at ────────────────────────────── Four, and each one is here because a component came to use it rather than because a device exists. They are declared as tokens so they have a name and a page, and they are ALSO written as literals in the queries that ask about them, because a container query cannot read a custom property in its condition. That is a limitation of CSS and not a choice. What keeps the two copies honest is the check: every length inside an `@container` in this package has to be one of these values, so a query asking about a width nobody named fails the build. */ :root { --ds-break-compact: 30rem; /* 480: a toolbar loses the room for labels */ --ds-break-phone: 40rem; /* 640: wider than every phone, narrower than every tablet */ --ds-break-wide: 60rem; /* 960: an auth shell can hold two columns */ --ds-break-tablet: 64rem; /* 1024: the widest tablet, so a sidebar stops being a column */ --ds-break-desktop: 80rem; /* 1280: where a WIDE column still leaves a page beside it */ } /* ========================================================================== Type: the parts that do not change with the surface Families and weights live here. Sizes, leadings and trackings do not: they are different on web and on product, so they sit in surface.css where both columns can be read together. There is no public size ramp, and that is the point. A ramp published beside the roles is a way to set type without naming it, and the roles lose every time. The sizes exist only as the values behind the levels. ========================================================================== */ :root { /* Two faces and a monospace. General Sans is drawn for large type and Satoshi for reading, and which one a level takes is decided by its size, so these two are the whole typographic choice. Space Mono carries code, and it is here for the reason a code face exists at all: it is obviously not the other two, so a snippet reads as a snippet before it is read as text. All three are free to serve, which SF Pro is not: Apple licenses it for interfaces, not for redistribution as a webfont. The value is the font, not a pointer to somewhere else the font might be named. A project that wants different faces re-declares these three, in its own stylesheet, and everything follows from there: :root { --ds-typeface-display: "Cabinet Grotesk", sans-serif; } This used to read a --font-* variable the project was expected to set, with these as the fallback. It cost every project a setup step, gave every project a way to get that step wrong, and the way it went wrong was invisible: a variable read one level too high resolves before the project has declared it and freezes the fallback, so the page renders in system-ui and nothing complains. An override is the same power without the ceremony, and it fails loudly when it fails at all. `typeface` and not `font`: `font-` belongs to the text classes, `.ds-font-body` being a size, and one prefix meaning two things is the thing this system is built to avoid. */ --ds-typeface-display: "General Sans", system-ui, sans-serif; --ds-typeface-body: Satoshi, system-ui, sans-serif; --ds-typeface-mono: "Space Mono", ui-monospace, SFMono-Regular, Menlo, monospace; } :root { /* Four weights, named for how the text should feel rather than for a number or a CSS keyword. `light`, `medium`, `semibold` and `bold` read like promises the typeface has to keep, and no two typefaces keep them the same way: one ships a Medium at 500 and another calls 500 Book, and a project that wants its robust weight to be 400 because its face has no middle cut then has a token called `medium` holding 400. The name stops describing anything. Named this way, a project re-points the value once in theme.css and every level that asked for robust gets what the brand means by robust. Four and not five: a fifth step needs a job, and the job the heaviest one does is emphasis inside running text, which `intense` already covers. */ --ds-weight-delicate: 300; --ds-weight-standard: 400; --ds-weight-robust: 500; --ds-weight-intense: 600; } /* ========================================================================== Surfaces A surface is a declaration on a subtree that says what kind of screen this is. Two of them: web a site, a landing page, an article. Generous. product an admin panel, a dashboard, a form. Dense. Density is a property of the surface, not a knob each page turns. The same card in a marketing page and in a dashboard is the same card; what differs is the room around it, and that is decided once on the shell: Everything that varies by surface is declared here, both columns side by side, so the difference can be read rather than reconstructed from two files. Today that is the rhythm. Step 4 adds the type scale to the same two blocks. ── The trap ───────────────────────────────────────────────────────────── A var() inside a custom property is substituted WHERE THE PROPERTY IS DECLARED, not where it is used. So this looks right and is not: :root { --ds-pad: var(--ds-rhythm-section); } [data-surface="product"] { --ds-rhythm-section: 2rem; } `--ds-pad` resolved at :root, froze the web value, and every descendant inherits it already resolved. The product block changes the rhythm and the alias never notices. The other system shipped this twice, once on font families and once on section padding, and both times the symptom was the same: half the values switch with the surface and half do not, which reads as a random bug rather than a systematic one. The rule that avoids it: **an alias of a surface-varying token must be re-declared inside every surface block.** If you cannot re-declare it, do not alias it. ========================================================================== */ /* Web is the default, and is also written out explicitly so a subtree can go back to it. Without the second selector, a web island inside a product shell is impossible: product would win by inheritance and there would be no way to say "this part is not a panel". `body` used to be in this list too, because the face tokens read a variable the project declared on body and an alias resolved at :root froze the fallback. The faces hold their own values now, so there is nothing left to resolve too early and `data-surface` goes anywhere, html included. */ :root, [data-surface="web"] { /* line between two lines of ONE thing: a name and its value, a label and the number under it element between the parts of one thing: a label and its field, an overline and the title under it block between two things in the same section section between sections `line` is the same on both surfaces and the other three are not, which is deliberate. The other three are density, and density is what a surface decides. This one is typography: two lines sit close because they are the same item, and that reason does not change between a landing page and a panel. It was added when the colour page put a token name, its two hex values and its note 16px apart and they read as three separate things. */ --ds-rhythm-line: var(--ds-space-1); /* 4px */ --ds-rhythm-element: var(--ds-space-4); /* 16px */ --ds-rhythm-block: var(--ds-space-12); /* 48px */ --ds-rhythm-section: clamp(5rem, calc(var(--ds-viewport) * 0.12), 10rem); /* ── Type on web ──────────────────────────────────────────────────────── Headings are fluid: a marquee title that does not grow with the viewport reads as a mistake on a wide screen. The face follows the SIZE, not the surface and not the role. The two faces are drawn for different ranges: display is the tighter one, made for large type, and body is opened up so small sizes stay readable. Apple sets that boundary at 20pt for its own pair and so does this: a heading at or above 20 takes display, below it takes body. Running text stays on the body face at every size, including the 20px lede. The boundary is a guide, and on a paragraph the openness is worth more than the tightening. ── The leading is a step, not a ratio ───────────────────────────────── Every fixed size carries its leading in rem, and every one of those is a multiple of 4, the same step the space ramp is built on. As ratios they were 1.55 and 1.5 and 1.6, which put a 14px label in a 21.7px box: two stacked lines then sat 10.9px apart, a number the ramp cannot produce and nobody can reason about. In rem and not in px, so the whole ladder scales with `data-text` and stays in step with the space ramp, which is also in rem. The three fluid sizes keep a ratio, because a leading that does not move with a clamped size is a leading that is wrong at one end of it. */ --ds-font-heading-1-face: var(--ds-typeface-display); --ds-font-heading-1-size: clamp(3.5rem, calc(var(--ds-viewport) * 0.05), 5rem); /* 56 -> 80 */ --ds-font-heading-1-weight: var(--ds-weight-standard); --ds-font-heading-1-leading: 1.05; --ds-font-heading-1-tracking: -0.03em; --ds-font-heading-2-face: var(--ds-typeface-display); --ds-font-heading-2-size: clamp(2.5rem, calc(var(--ds-viewport) * 0.035), 3.5rem); /* 40 -> 56 */ --ds-font-heading-2-weight: var(--ds-weight-standard); --ds-font-heading-2-leading: 1.1; --ds-font-heading-2-tracking: -0.025em; --ds-font-heading-3-face: var(--ds-typeface-display); --ds-font-heading-3-size: clamp(1.875rem, calc(var(--ds-viewport) * 0.02), 2.25rem); /* 30 -> 36 */ --ds-font-heading-3-weight: var(--ds-weight-standard); --ds-font-heading-3-leading: 1.15; --ds-font-heading-3-tracking: -0.02em; /* Levels 4 to 6 are the functional headings: a card title, a panel title, a field group, and the deep levels of an article. Fixed rather than fluid, because none of them is editorial. The face follows the SIZE and not the level: 20px and up takes the display face, below it the body face. So it lands on 6 here and on 4 in the product column, and the same class can be right in both places. Nobody flips it, which is the point: a functional heading arriving in editorial clothes is what put an editorial typeface on 75 admin panels in the other system. Six and not four. The first version of this file stopped at four, reasoning from zero uses of h4-h6 across twenty projects. That measured the markup DESIGNERS write and applied it to the markup AUTHORS write, and h4 to h6 only ever appear in the second: an article, a CMS body, markdown. Collapsing them onto one level flattens a hierarchy exactly where the person who wrote it had no say. The zero was also read wrong. It said the number was wrong, not that the level was unwanted: h4 over there was 28 to 40px, which is absurd for a fourth level, so of course nobody reached for it. */ --ds-font-heading-4-face: var(--ds-typeface-display); --ds-font-heading-4-size: 1.5rem; /* 24 */ --ds-font-heading-4-weight: var(--ds-weight-robust); --ds-font-heading-4-leading: 2rem; /* 32 on 24 */ --ds-font-heading-4-tracking: -0.01em; --ds-font-heading-5-face: var(--ds-typeface-display); --ds-font-heading-5-size: 1.25rem; /* 20 */ --ds-font-heading-5-weight: var(--ds-weight-robust); --ds-font-heading-5-leading: 1.75rem; /* 28 on 20 */ --ds-font-heading-5-tracking: 0; --ds-font-heading-6-face: var(--ds-typeface-body); --ds-font-heading-6-size: 1.125rem; /* 18 */ --ds-font-heading-6-weight: var(--ds-weight-robust); --ds-font-heading-6-leading: 1.5rem; /* 24 on 18 */ --ds-font-heading-6-tracking: 0; /* Running text. Level 3 is 14px because that is where the largest group of hand-built text sat, and the other scale had nothing there. */ --ds-font-copy-size: clamp(1.125rem, calc(var(--ds-viewport) * 0.003 + 1.05rem), 1.25rem); /* 18 -> 20 */ --ds-font-copy-leading: 1.5rem; /* 24, and a length rather than the ratio it was: a ratio on a clamped size gives a line that is off the 4px step everywhere between the two ends. */ --ds-font-body-size: 1rem; /* 16 */ --ds-font-body-leading: 1.25rem; /* 20 on 16 */ /* The same two sizes as PARAGRAPHS. The pairs above are UI lines, and their leading is what every mark in the package measures itself against: a body row keeps a 20px mark beside a 20px line. Running text wants air a row of controls cannot afford, so the prose pair holds the same size on a looser line, and marks never stand beside it. Owner's call, 22 August 2026. */ --ds-font-copy-prose-size: clamp(1.125rem, calc(var(--ds-viewport) * 0.003 + 1.05rem), 1.25rem); /* 18 -> 20 */ --ds-font-copy-prose-leading: 1.75rem; /* 28 */ --ds-font-body-prose-size: 1rem; /* 16 */ --ds-font-body-prose-leading: 1.5rem; /* 24 on 16 */ --ds-font-label-size: 0.875rem; /* 14 */ --ds-font-label-leading: 1rem; /* 16 on 14 */ --ds-font-small-size: 0.75rem; /* 12 */ --ds-font-small-leading: 1rem; /* 16 on 12 */ /* Code, in the code face, at small's measures: a shortcut at the end of a menu line, a snippet, a file's name. Named 4 September 2026 because five components wanted the monospace and, with no role to read, reached for the primitive, which is the one thing a component may not do. */ --ds-font-mono-size: 0.75rem; /* 12 */ --ds-font-mono-leading: 1rem; /* 16 on 12 */ /* A role is a complete set, not a size and a leading with the rest borrowed. Every one of these points at a primitive and every component reads the ROLE: that is what makes a role's face or weight movable without touching the scale, and what stops a reading of a paragraph naming the primitive where the source meant `copy`. The headings had all four from the start. These four had two. */ --ds-font-copy-face: var(--ds-typeface-body); --ds-font-copy-weight: var(--ds-weight-standard); --ds-font-body-face: var(--ds-typeface-body); --ds-font-body-weight: var(--ds-weight-standard); --ds-font-copy-prose-face: var(--ds-typeface-body); --ds-font-copy-prose-weight: var(--ds-weight-standard); --ds-font-body-prose-face: var(--ds-typeface-body); --ds-font-body-prose-weight: var(--ds-weight-standard); --ds-font-label-face: var(--ds-typeface-body); --ds-font-label-weight: var(--ds-weight-standard); --ds-font-small-face: var(--ds-typeface-body); --ds-font-small-weight: var(--ds-weight-standard); --ds-font-mono-face: var(--ds-typeface-mono); --ds-font-mono-weight: var(--ds-weight-standard); --ds-font-overline-face: var(--ds-typeface-body); /* The one that is not standard: an overline is a label in capitals with the tracking opened, and at that size and that spacing the standard weight reads as a whisper. */ --ds-font-overline-weight: var(--ds-weight-robust); --ds-font-overline-size: 0.875rem; /* 14 */ /* A role is a pair, and this one was half of one: everything that set an overline reached for `label`'s leading, which is the same 16 and is nobody's decision. Named, it is a decision. */ --ds-font-overline-leading: 1rem; /* 16 on 14 */ --ds-font-overline-tracking: 0.08em; /* ── Micro: the metadata voice, one step under everything ─────────────── The category and the date over a title, the key over a figure. The first consumer cut it by hand a rung under `small` and wrote down why: in capitals with the tracking this wide, a 10px line reads larger than its nominal size, and at 12 those lines compete with the title they are meant to introduce. The overline stays the sentence-level eyebrow; this is the one for rows of metadata, and it is the same on both surfaces because there is nothing under it to step down to. */ --ds-font-micro-face: var(--ds-typeface-body); --ds-font-micro-weight: var(--ds-weight-robust); --ds-font-micro-size: 0.625rem; /* 10 */ --ds-font-micro-leading: 0.75rem; /* 12 on 10 */ --ds-font-micro-tracking: 0.16em; /* ── Two weights that are not a role's, and are not a component's ──────── Nineteen rules in this package set a weight from the primitive, and they were saying two things between them. Eight said "this is the NAME of the thing": a card's title, a dialog's title, a field's label, a table's header cell, `strong` in prose, a button's words. Seven said "this is the one you are ON": every `[aria-current]` in the header, the sidebar, the tabs, the tab bar, the breadcrumb, the language switcher and the link. Written as `--ds-weight-robust` in nineteen places that is one decision copied nineteen times, and moving it means finding all nineteen. It also reports itself back as the primitive to anybody inspecting a card title, which says the component reached past the system rather than into it. Both are per-surface, like every other semantic here: a surface that wanted a heavier hand would move these and nothing else. */ /* The four text roles get a tracking too, and it is `0`. The headings have carried one from the start and these four never did, so anything taking `body`'s size on an element the tag types as a heading kept the HEADING's tracking: a card's title is 16px body with -0.32px on it, which is the spacing drawn for 32px type. A role is face, size, leading, weight and tracking, and four of them were missing the fifth. Zero is a decision here, not an absence: text at these sizes is set as drawn and the value says so. */ --ds-font-copy-tracking: 0; --ds-font-body-tracking: 0; --ds-font-copy-prose-tracking: 0; --ds-font-body-prose-tracking: 0; --ds-font-label-tracking: 0; --ds-font-small-tracking: 0; --ds-font-mono-tracking: 0; --ds-emphasis-weight: var(--ds-weight-robust); --ds-current-weight: var(--ds-weight-robust); /* The weight of a ``, which is a different job from the two above. Those are UI emphasis — the row you are on, the head of an accordion — and they sit alone, so 500 reads. This one is emphasis INSIDE running text, where 500 among 400 is a word slightly darker than the others. It exists as a name because a project can want a bolder bold without moving everything else `intense` dresses. The first one did: on a site that spends `intense` on its overlines and its buttons, taking the primitive to 700 would have taken those with it, and a 700 button is a different button. */ --ds-bold-weight: var(--ds-weight-intense); } [data-surface="product"] { --ds-rhythm-line: var(--ds-space-1); /* 4px, as on web */ --ds-rhythm-element: var(--ds-space-3); /* 12px */ --ds-rhythm-block: var(--ds-space-6); /* 24px */ --ds-rhythm-section: var(--ds-space-8); /* 32px */ /* ── Type on product ──────────────────────────────────────────────────── No clamp anywhere: density is a product decision, not the viewport's. The same rule applies, so the split lands in a different place because the sizes are different: heading 1 to 3 are 28, 24 and 20 and take the display face, and 4 to 6 are below the boundary and take the body face. This reads as a reversal of "the body face on a data screen" and is not. That rule guarded against a heading being dressed up because of what it is called. Here nothing is dressed up by name: a 28px title on a panel gets the face drawn for 28px, which is the same answer the web column gives at the same size. */ --ds-font-heading-1-face: var(--ds-typeface-display); --ds-font-heading-1-size: 1.75rem; /* 28 */ --ds-font-heading-1-weight: var(--ds-weight-intense); --ds-font-heading-1-leading: 2.25rem; /* 36 on 28 */ --ds-font-heading-1-tracking: -0.01em; --ds-font-heading-2-face: var(--ds-typeface-display); --ds-font-heading-2-size: 1.5rem; /* 24 */ --ds-font-heading-2-weight: var(--ds-weight-robust); --ds-font-heading-2-leading: 2rem; /* 32 on 24 */ --ds-font-heading-2-tracking: -0.01em; --ds-font-heading-3-face: var(--ds-typeface-display); --ds-font-heading-3-size: 1.25rem; /* 20 */ --ds-font-heading-3-weight: var(--ds-weight-robust); --ds-font-heading-3-leading: 1.75rem; /* 28 on 20 */ --ds-font-heading-3-tracking: -0.005em; --ds-font-heading-4-face: var(--ds-typeface-body); --ds-font-heading-4-size: 1.125rem; /* 18 */ --ds-font-heading-4-weight: var(--ds-weight-robust); --ds-font-heading-4-leading: 1.5rem; /* 24 on 18 */ --ds-font-heading-4-tracking: 0; --ds-font-heading-5-face: var(--ds-typeface-body); --ds-font-heading-5-size: 1rem; /* 16 */ --ds-font-heading-5-weight: var(--ds-weight-robust); --ds-font-heading-5-leading: 1.5rem; /* 24 on 16 */ --ds-font-heading-5-tracking: 0; --ds-font-heading-6-face: var(--ds-typeface-body); --ds-font-heading-6-size: 0.875rem; /* 14 */ --ds-font-heading-6-weight: var(--ds-weight-intense); --ds-font-heading-6-leading: 1.25rem; /* 20 on 14 */ --ds-font-heading-6-tracking: 0.01em; /* Reading sizes hold still: a timestamp is 12px on both surfaces. Only the lede loses its clamp, because a panel has no viewport to grow into. */ --ds-font-copy-size: 1.125rem; /* 18 */ --ds-font-copy-leading: 1.5rem; /* 24 on 18 */ --ds-font-body-size: 1rem; /* 16 */ --ds-font-body-leading: 1.25rem; /* 20 on 16 */ /* The prose pair, as on web: same sizes, looser line, for running text. */ --ds-font-copy-prose-size: 1.125rem; /* 18 */ --ds-font-copy-prose-leading: 1.75rem; /* 28 on 18 */ --ds-font-body-prose-size: 1rem; /* 16 */ --ds-font-body-prose-leading: 1.5rem; /* 24 on 16 */ --ds-font-label-size: 0.875rem; /* 14 */ --ds-font-label-leading: 1rem; /* 16 on 14 */ --ds-font-small-size: 0.75rem; /* 12 */ --ds-font-small-leading: 1rem; /* 16 on 12 */ /* Code, in the code face, at small's measures: a shortcut at the end of a menu line, a snippet, a file's name. Named 4 September 2026 because five components wanted the monospace and, with no role to read, reached for the primitive, which is the one thing a component may not do. */ --ds-font-mono-size: 0.75rem; /* 12 */ --ds-font-mono-leading: 1rem; /* 16 on 12 */ /* A role is a complete set, not a size and a leading with the rest borrowed. Every one of these points at a primitive and every component reads the ROLE: that is what makes a role's face or weight movable without touching the scale, and what stops a reading of a paragraph naming the primitive where the source meant `copy`. The headings had all four from the start. These four had two. */ --ds-font-copy-face: var(--ds-typeface-body); --ds-font-copy-weight: var(--ds-weight-standard); --ds-font-body-face: var(--ds-typeface-body); --ds-font-body-weight: var(--ds-weight-standard); --ds-font-copy-prose-face: var(--ds-typeface-body); --ds-font-copy-prose-weight: var(--ds-weight-standard); --ds-font-body-prose-face: var(--ds-typeface-body); --ds-font-body-prose-weight: var(--ds-weight-standard); --ds-font-label-face: var(--ds-typeface-body); --ds-font-label-weight: var(--ds-weight-standard); --ds-font-small-face: var(--ds-typeface-body); --ds-font-small-weight: var(--ds-weight-standard); --ds-font-mono-face: var(--ds-typeface-mono); --ds-font-mono-weight: var(--ds-weight-standard); --ds-font-overline-face: var(--ds-typeface-body); /* The one that is not standard: an overline is a label in capitals with the tracking opened, and at that size and that spacing the standard weight reads as a whisper. */ --ds-font-overline-weight: var(--ds-weight-robust); --ds-font-overline-size: 0.8125rem; /* 13 */ --ds-font-overline-leading: 1rem; /* 16 on 13 */ --ds-font-overline-tracking: 0.08em; /* Micro, as on web: there is nothing under it to step down to, so density has nothing to take away. */ --ds-font-micro-face: var(--ds-typeface-body); --ds-font-micro-weight: var(--ds-weight-robust); --ds-font-micro-size: 0.625rem; /* 10 */ --ds-font-micro-leading: 0.75rem; /* 12 on 10 */ --ds-font-micro-tracking: 0.16em; /* ── Two weights that are not a role's, and are not a component's ──────── Nineteen rules in this package set a weight from the primitive, and they were saying two things between them. Eight said "this is the NAME of the thing": a card's title, a dialog's title, a field's label, a table's header cell, `strong` in prose, a button's words. Seven said "this is the one you are ON": every `[aria-current]` in the header, the sidebar, the tabs, the tab bar, the breadcrumb, the language switcher and the link. Written as `--ds-weight-robust` in nineteen places that is one decision copied nineteen times, and moving it means finding all nineteen. It also reports itself back as the primitive to anybody inspecting a card title, which says the component reached past the system rather than into it. Both are per-surface, like every other semantic here: a surface that wanted a heavier hand would move these and nothing else. */ /* The four text roles get a tracking too, and it is `0`. The headings have carried one from the start and these four never did, so anything taking `body`'s size on an element the tag types as a heading kept the HEADING's tracking: a card's title is 16px body with -0.32px on it, which is the spacing drawn for 32px type. A role is face, size, leading, weight and tracking, and four of them were missing the fifth. Zero is a decision here, not an absence: text at these sizes is set as drawn and the value says so. */ --ds-font-copy-tracking: 0; --ds-font-body-tracking: 0; --ds-font-copy-prose-tracking: 0; --ds-font-body-prose-tracking: 0; --ds-font-label-tracking: 0; --ds-font-small-tracking: 0; --ds-font-mono-tracking: 0; --ds-emphasis-weight: var(--ds-weight-robust); --ds-current-weight: var(--ds-weight-robust); --ds-bold-weight: var(--ds-weight-intense); } /* ── A box that is not the window ───────────────────────────────────────── The five sizes above grow with `--ds-viewport`, and they are declared on `:root`, where a `var()` inside a custom property is substituted. So the window's width is baked into them before any element sees them, and a frame further down that says `--ds-viewport: 430px` changes nothing at all: the headline in a 430 canvas came out drawn for a desk, one word to a line. That is how custom properties work and not a bug to fix. What closes it is declaring the five again on the box itself, where the smaller width is the one in scope. One class, opt-in, and nothing changes for a page that never uses it. Written out rather than derived, because there is no way in CSS to say "the same formula, resolved here". The check `la scala fluida e' la stessa in entrambi i posti` compares the two lists character for character, so they cannot drift. Not for `product`: that surface has no clamp anywhere, because density there is a decision and not a width. */ .ds-viewport-scope { --ds-rhythm-section: clamp(5rem, calc(var(--ds-viewport) * 0.12), 10rem); --ds-font-heading-1-size: clamp(3.5rem, calc(var(--ds-viewport) * 0.05), 5rem); --ds-font-heading-2-size: clamp(2.5rem, calc(var(--ds-viewport) * 0.035), 3.5rem); --ds-font-heading-3-size: clamp(1.875rem, calc(var(--ds-viewport) * 0.02), 2.25rem); --ds-font-copy-size: clamp(1.125rem, calc(var(--ds-viewport) * 0.003 + 1.05rem), 1.25rem); --ds-font-copy-prose-size: clamp(1.125rem, calc(var(--ds-viewport) * 0.003 + 1.05rem), 1.25rem); } /* And the same box inside a product surface keeps the product's sizes, which are fixed. Without this the class would put the web scale on a panel. The admin vocabulary needs no line here: its roots carry `data-surface="product"` in the markup, so a head that calls itself admin is a product's wherever it stands. */ [data-surface="product"] .ds-viewport-scope, .ds-viewport-scope[data-surface="product"] { --ds-rhythm-section: var(--ds-space-8); --ds-font-heading-1-size: 1.75rem; --ds-font-heading-2-size: 1.5rem; --ds-font-heading-3-size: 1.25rem; --ds-font-copy-size: 1.125rem; --ds-font-copy-prose-size: 1.125rem; } /* ========================================================================== Shape A radius ramp, and four modes that re-scale it for a whole project. How round a product is reads as personality: the same dashboard feels engineered at 0 and friendly at 16. That is one decision, taken once on the shell, not a value argued over per component: Every component reads the ramp, so every component follows. `round` is the default and is written out as well, so a subtree can go back to it. Radius is its own axis, deliberately not folded into data-surface. How round a brand is does not change between its marketing page and its dashboard; how dense it is does. Tying them would make "soft and dense" unsayable. Two steps never move. `--ds-radius-0` is square by definition, and `--ds-radius-full` is the circle and the pill: an avatar, a radio dot, a toggle thumb are round because of what they are, not because of how the brand feels this year. Re-scaling those would turn a circle into a squircle under `square`, which nobody asks for. ========================================================================== */ :root { --ds-radius-0: 0; --ds-radius-full: 9999px; /* One lever a brand turns to move the whole system without touching a component. Every step below is a multiple of it, so scaling it scales everything in proportion. */ --ds-radius: 0.5rem; /* 8px */ } :root, [data-radius="round"] { --ds-radius-1: calc(var(--ds-radius) * 0.5); /* 4px */ --ds-radius-2: var(--ds-radius); /* 8px */ --ds-radius-3: calc(var(--ds-radius) * 1.5); /* 12px */ --ds-radius-4: calc(var(--ds-radius) * 2); /* 16px */ } /* Drawn, not softened. Everything square except the things that are circles. */ [data-radius="square"] { --ds-radius-1: 0; --ds-radius-2: 0; --ds-radius-3: 0; --ds-radius-4: 0; } /* Corners taken off, no more. Half the default at every step, so the steps stay distinguishable instead of collapsing onto the same 2px. */ [data-radius="soft"] { --ds-radius-1: calc(var(--ds-radius) * 0.25); /* 2px */ --ds-radius-2: calc(var(--ds-radius) * 0.5); /* 4px */ --ds-radius-3: calc(var(--ds-radius) * 0.75); /* 6px */ --ds-radius-4: var(--ds-radius); /* 8px */ } /* Generous. Three times the default, which is where a card stops being a rectangle with soft corners and starts reading as a lozenge. */ [data-radius="pill"] { --ds-radius-1: calc(var(--ds-radius) * 1.5); /* 12px */ --ds-radius-2: calc(var(--ds-radius) * 3); /* 24px */ --ds-radius-3: calc(var(--ds-radius) * 4.5); /* 36px */ --ds-radius-4: calc(var(--ds-radius) * 6); /* 48px */ } /* ========================================================================== Motion Durations and easings. Three durations for transitions, because a fourth invites a debate nobody wins, and one for a loop. A loop is not a transition and cannot borrow one of the three: 400ms is a long transition and a frantic spin. It sits here anyway rather than inside the spinner, so that reduced motion keeps being handled in one place. Reduced motion is handled here, once, by zeroing the durations. A component that reads these tokens gets it for free and never writes its own media query; a component that hardcodes 200ms opts every one of its users out of a preference they set on purpose. ========================================================================== */ :root { /* 100ms is the length of a small MOVEMENT: the eye follows the thing and the time is only there to stop it teleporting. It is too short for a colour, where there is nothing to follow and the whole of the change is the fade, which is why every hover in this system fades over the next one up. */ --ds-duration-fast: 100ms; --ds-duration: 200ms; --ds-duration-slow: 400ms; --ds-duration-loop: 700ms; /* one turn of something that repeats */ --ds-ease: cubic-bezier(0.4, 0, 0.2, 1); --ds-ease-out: cubic-bezier(0, 0, 0.2, 1); --ds-ease-in-out: cubic-bezier(0.65, 0, 0.35, 1); } @media (prefers-reduced-motion: reduce) { :root { --ds-duration-fast: 0s; --ds-duration: 0s; --ds-duration-slow: 0s; --ds-duration-loop: 0s; } } /* ========================================================================== Accessibility: two axes, both independent of everything else Reading needs and screen kind are different questions. A dashboard can need large text exactly as much as an article can, and folding either of these into `data-surface` would make "dense panel, large text" unsayable. Same reason radius is its own axis. They are also independent of EACH OTHER. Someone who needs 200% text usually has no trouble with a grey caption, and someone who needs contrast often reads at the normal size. One combined "accessible mode" would force both on anyone who needs one. Both belong on ``. `data-text` has to be there because that is the element `rem` is measured from; `data-contrast` has to be at or above every element it recolours, and html is the only place that is always true. ========================================================================== */ /* ── Text size ─────────────────────────────────────────────────────────── One declaration for the whole system, because every size in it is in `rem`. Type, spacing, radius and the gaps between them all scale together, which is the difference between large text and large text crammed into the layout it had before. A percentage and not a pixel value: the reader's own browser setting is the 100%, so this multiplies their choice instead of overwriting it. Someone who already reads at 20px gets 30px at `large`, not 24px. The fluid headings keep working. `clamp(3.5rem, 5vw, 5rem)` has its floor in rem, so at 115% the floor becomes 64px and wins over a viewport term that did not move: the heading grows even where the viewport did not. 115 and 130, which is smaller than it sounds and was arrived at by looking. Everything scales together here, headings included, so a step that reads as reasonable on a paragraph is already violent on an 80px title: at 200% the first heading passed 150px and left three words on the screen. The reader who needs more than 130% has the browser's own zoom, which this multiplies rather than replaces. */ [data-text="large"] { font-size: 115%; } [data-text="huge"] { font-size: 130%; } /* ── Contrast ──────────────────────────────────────────────────────────── The three text neutrals move up one step: secondary takes what primary had, tertiary takes what secondary had. Nothing new is invented, no palette is duplicated, and no value can be worse than the one it replaces because it is already the darker one on light and the lighter one on dark. What it costs is the distinction between primary and secondary, which becomes nothing. That is the correct trade rather than a shortcut: a reader who cannot separate #52525b from its background is not helped by keeping a hierarchy they cannot see, and hierarchy survives in size, weight and position, which do not depend on contrast at all. Tertiary is the one that mattered. It is documented as decorative and does not reach 4.5:1 on every surface, and here it does. Measured per theme and per surface by `npm run check`, which fails below the floor rather than trusting the reasoning above. Follows the operating system when the reader has not said otherwise: on macOS this is Increase Contrast, on Windows the contrast themes. An explicit `normal` wins over the query, which is what lets a preview switch it back off. */ @media (prefers-contrast: more) { :root:not([data-contrast="normal"]) { --ds-text-secondary-neutral: var(--ds-ink-1); --ds-text-tertiary-neutral: var(--ds-ink-2); } } [data-contrast="high"] { --ds-text-secondary-neutral: var(--ds-ink-1); --ds-text-tertiary-neutral: var(--ds-ink-2); } } @layer base { /* base. Empty until its step opens. See ROADMAP.md. */ /* ========================================================================== The three faces, fetched by the package. General Sans and Satoshi are on Fontshare, and these rules are its variable cut: one file per family covering the whole weight axis, so 600 is a real 600 and not the browser picking the nearest static weight it was handed. Space Mono is on Google and is not variable, so it arrives as the two weights and the one italic that code actually uses. Why the rules are copied here instead of an @import of Fontshare's own stylesheet: a bundler eats the @import. Measured, not assumed. The package shipped with `@import url("https://api.fontshare.com/...")` as the first line of dist/os.css, correct CSS by itself, and Next dropped it from the built chunk without a word. Every face resolved by name to a font nobody had loaded, which renders as system-ui and reports nothing. @font-face survives the same pipeline intact. Why not the files themselves: they would have to be redistributed, and pinned, and updated by hand. These URLs are Fontshare's own delivery, the same ones its stylesheet hands out. Those URLs are content-hashed, so they can rotate. `npm run check` requests each one and fails if it does not answer, which turns a silent fallback to system-ui into a build that stops. A project that wants other faces overrides --ds-typeface-* in tokens/type.css and pays one unused request for these. A project that wants to serve them itself declares its own @font-face for the same families and wins by order. ========================================================================== */ @font-face { font-family: "General Sans"; src: url("https://cdn.fontshare.com/wf/LHQJ5KSAL7VGAEIDSTEXCCOIUKFLT2I6/GW57XUEG4ZBVMLZZTQZTGYPROITRRQ5W/JA3IZUEMJ2J6WWT2OQVJOAWDXO3YL4YG.woff2") format("woff2"); font-weight: 200 700; font-style: normal; font-display: swap; } @font-face { font-family: "General Sans"; src: url("https://cdn.fontshare.com/wf/RRO6TYZXO7WQBHSH4BZYSTI7E7T2HKLF/55LXPUDQQQTSLB3M2T377FIN2EKQQWJY/3HUYMY6WP3BZQYPOVGG6IZQAM476CQDC.woff2") format("woff2"); font-weight: 200 700; font-style: italic; font-display: swap; } @font-face { font-family: "Satoshi"; src: url("https://cdn.fontshare.com/wf/NWBQYJIM7GCZ5XWD7D26ARB3VDY55ZRT/K63EV2KZIGKLE7RANQ2U42S6SVHU5RJ7/X6XYTKIVDUW7GZTZPZNN4EUM5KH54KHF.woff2") format("woff2"); font-weight: 300 900; font-style: normal; font-display: swap; } @font-face { font-family: "Satoshi"; src: url("https://cdn.fontshare.com/wf/3JZIFUW7KLFSPLVCIUI2DLGNIER6IFCX/MMP4RUF5LYGUAZS3DCJC3GJ6F6SAGKSN/E3NEPGEAHYCHR37DSBXHV33XCYYRE2CY.woff2") format("woff2"); font-weight: 300 900; font-style: italic; font-display: swap; } /* Space Mono, latin and latin-ext. The ranges are Google's own and they are what keeps this cheap: a page of English code downloads one file, and the accented file arrives only if an accent is on the page. */ @font-face { font-family: "Space Mono"; src: url("https://fonts.gstatic.com/s/spacemono/v17/i7dPIFZifjKcF5UAWdDRYEF8RXi4EwQ.woff2") format("woff2"); font-weight: 400; font-style: normal; font-display: swap; unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; } @font-face { font-family: "Space Mono"; src: url("https://fonts.gstatic.com/s/spacemono/v17/i7dPIFZifjKcF5UAWdDRYE98RXi4EwSsbg.woff2") format("woff2"); font-weight: 400; font-style: normal; font-display: swap; unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; } @font-face { font-family: "Space Mono"; src: url("https://fonts.gstatic.com/s/spacemono/v17/i7dMIFZifjKcF5UAWdDRaPpZUFWaHi6WZ3Q.woff2") format("woff2"); font-weight: 700; font-style: normal; font-display: swap; unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; } @font-face { font-family: "Space Mono"; src: url("https://fonts.gstatic.com/s/spacemono/v17/i7dMIFZifjKcF5UAWdDRaPpZUFuaHi6WZ3S_Yg.woff2") format("woff2"); font-weight: 700; font-style: normal; font-display: swap; unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; } @font-face { font-family: "Space Mono"; src: url("https://fonts.gstatic.com/s/spacemono/v17/i7dNIFZifjKcF5UAWdDRYERMR3K_MQacbw.woff2") format("woff2"); font-weight: 400; font-style: italic; font-display: swap; unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; } /* ========================================================================== Base: text elements Defaults for bare elements, so markup nobody wrote by hand still reads: CMS output, markdown, a pasted article. Everything here is overridable by a role, because the roles live in a later layer. Each element maps onto its own level, one to one. An earlier version pointed h4, h5 and h6 at the same level, which rendered three different levels identically. That is worst precisely here, in the base layer, because this layer exists for markup nobody wrote by hand: a CMS body or an article, where the author chose the level and cannot choose the style. ========================================================================== */ body { /* The browser's own eight pixels, cleared. Everything the system draws to an edge is drawn to the window's edge: a header, a bar at the foot, a sheet. With the default in place they all stopped short and left a band of the page showing round the outside, which reads as a page inside a page. Anything that should stay inside a measure holds its own width. */ margin: 0; font-family: var(--ds-typeface-body); font-size: var(--ds-font-body-size); line-height: var(--ds-font-body-leading); color: var(--ds-text-primary-neutral); background-color: var(--ds-surface-0); -webkit-font-smoothing: antialiased; } h1 { font: var(--ds-font-heading-1-weight) var(--ds-font-heading-1-size) / var(--ds-font-heading-1-leading) var(--ds-font-heading-1-face); letter-spacing: var(--ds-font-heading-1-tracking); } h2 { font: var(--ds-font-heading-2-weight) var(--ds-font-heading-2-size) / var(--ds-font-heading-2-leading) var(--ds-font-heading-2-face); letter-spacing: var(--ds-font-heading-2-tracking); } h3 { font: var(--ds-font-heading-3-weight) var(--ds-font-heading-3-size) / var(--ds-font-heading-3-leading) var(--ds-font-heading-3-face); letter-spacing: var(--ds-font-heading-3-tracking); } h4 { font: var(--ds-font-heading-4-weight) var(--ds-font-heading-4-size) / var(--ds-font-heading-4-leading) var(--ds-font-heading-4-face); letter-spacing: var(--ds-font-heading-4-tracking); } h5 { font: var(--ds-font-heading-5-weight) var(--ds-font-heading-5-size) / var(--ds-font-heading-5-leading) var(--ds-font-heading-5-face); letter-spacing: var(--ds-font-heading-5-tracking); } h6 { font: var(--ds-font-heading-6-weight) var(--ds-font-heading-6-size) / var(--ds-font-heading-6-leading) var(--ds-font-heading-6-face); letter-spacing: var(--ds-font-heading-6-tracking); } h1, h2, h3, h4, h5, h6 { margin: 0; color: inherit; } /* Bold is one weight in this system, and the browser's is not it. Left alone, `` renders at 700 everywhere except inside `.ds-prose`, which sets it from a token — so the same word was one weight in an article body and another in a summary beside it, and neither was the one the system chose. This layer exists for markup nobody wrote by hand, and a `` out of a CMS is exactly that. */ strong, b { font-weight: var(--ds-bold-weight); } p { margin: 0; /* The prose rung, not body's: a bare paragraph is running text, and the UI line belongs to rows with marks beside them. It read the body leading until 22 August 2026, which put 20px lines on every unstyled paragraph and overrode the Prose fence's own 28 from underneath. A component that renders a p declares its type anyway, so rows are untouched. */ line-height: var(--ds-font-body-prose-leading); } small { font-size: var(--ds-font-small-size); } code, pre, kbd, samp { font-family: var(--ds-typeface-mono); } /* ── Links ──────────────────────────────────────────────────────────────── A link is an element and its look is the system's to decide, not each project's and certainly not each page's. The docs site invented one for itself before this existed, which is the tell: whatever a documentation site has to invent, every consumer will invent too, differently. Underlined and not only coloured. A colour on its own is a link that is invisible to anyone who cannot see that colour, and it fails WCAG 1.4.1 for exactly that reason. `-ink` and not the bare brand, for the same reason the status colours have inks: the brand is chosen to be seen as a block, and text has to be read. Checked at 4.5:1 like every other ink. The offset and the thickness are the only raw numbers in this file, and they are numbers about drawing rather than decisions anyone tunes: the default underline sits on the baseline and cuts through every descender, and `from-font` takes the weight the typeface itself specifies instead of the browser's guess. */ /* The colour of the words around it, with a line under it that is a fraction of that colour. Blue and underlined is the link of 1996: it was right when a page had five of them and no other blue, and it reads as a museum piece on a page that has a palette. The line does the work the colour used to. WCAG 1.4.1 asks that a link in running text be told apart by something other than hue, and an underline is that something; it can then be quiet, because it is the only job it has. Full strength on hover, so the link answers. `color-mix` on `currentColor` rather than a token: the link takes the colour of whatever it is standing in, so its underline has to as well. */ a { color: inherit; text-decoration: underline; text-decoration-thickness: from-font; text-decoration-color: color-mix(in srgb, currentColor 35%, transparent); text-underline-offset: 0.15em; /* Both, and on the element rather than on the hover rule, so it eases in and back out again. A colour that snaps reads as a redraw; the same change over the fast token reads as an answer. Reduced motion takes the token to zero and the answer becomes instant, which is the point of it being a token. */ transition: color var(--ds-duration) var(--ds-ease-out), text-decoration-color var(--ds-duration) var(--ds-ease-out); } a:hover { text-decoration-color: currentColor; } /* ── Focus ──────────────────────────────────────────────────────────────── Every focusable thing, once, here. A keyboard is how a page is used without a pointer, and the browser default is a fixed blue that has no idea which theme it is on: readable on white, nearly invisible on the dark surfaces this system also ships. `:focus-visible` and not `:focus`, so a pointer click does not leave a ring behind. The offset keeps the ring off the glyphs, and the outline is drawn rather than a box-shadow so it survives inside anything that clips. */ :focus-visible { outline: 2px solid var(--ds-focus); outline-offset: 2px; border-radius: var(--ds-radius-1); } } @layer roles { /* roles. Empty until its step opens. See ROADMAP.md. */ /* ========================================================================== Text roles One class per element. The class says what the text IS; the surface says what number that comes out as. Two scales, largest first, and a word for the one treatment that is not a position on a scale. ds-font-heading-1 the page statement ds-font-heading-2 a section ds-font-heading-3 an article or a card, at editorial size ds-font-heading-4 a functional heading: a panel, a field group, a card in a dashboard ds-font-heading-5 a level below that ds-font-heading-6 the deepest level an article reaches ds-font-copy the lede, and large reading text, on the UI line ds-font-body reading text, on the UI line ds-font-copy-prose a paragraph at copy size, on the reading line ds-font-body-prose a paragraph at body size, on the reading line ds-font-label supporting text, a form label, a table header ds-font-small timestamps, counts, the genuinely supplementary ds-font-overline an eyebrow: uppercase, spaced, small ds-font-micro the metadata voice: uppercase, spaced wider, a step under everything, because in capitals at this tracking a 10px line reads larger than its number ds-text-colour--primary-neutral the default for content ds-text-colour--secondary-neutral the lesser half of a pair ds-text-colour--tertiary-neutral decorative only ds-text-colour--success | --warning | --danger what happened ── Three editorial, three functional ─────────────────────────────────── Levels 1 to 3 are fluid on web; 4 to 6 are fixed everywhere, because a functional heading is not editorial: 129 uses on the previous system meant exactly "a heading that is not in editorial clothes" and had no level to go to, so most of them bolted a size utility on instead. The face is not chosen per level, it follows the size: 20px and up gets the display face, below it the body face. The boundary lands between 5 and 6 on web and between 3 and 4 on product, which is why no level here names a face. This file stopped at four levels for one commit, on the grounds that h4 to h6 had zero uses across twenty projects. That counted the markup DESIGNERS write and applied it to the markup AUTHORS write, and the deep levels only ever appear in the second: an article, a CMS body, markdown. Four levels meant h4, h5 and h6 rendering identically, which flattens a hierarchy exactly where the person who wrote it had no say. ── No level carries a colour ──────────────────────────────────────────── A level sizes; a colour class colours. The previous system baked secondary into its caption and tertiary into its meta, and both went unused: the size someone wanted never arrived with the colour they wanted. Default is inherit, and anything else is one explicit class. ========================================================================== */ .ds-font-heading-1, .ds-font-heading-2, .ds-font-heading-3, .ds-font-heading-4, .ds-font-heading-5, .ds-font-heading-6 { margin: 0; color: inherit; text-wrap: balance; } .ds-font-heading-1 { font-family: var(--ds-font-heading-1-face); font-size: var(--ds-font-heading-1-size); font-weight: var(--ds-font-heading-1-weight); line-height: var(--ds-font-heading-1-leading); letter-spacing: var(--ds-font-heading-1-tracking); } .ds-font-heading-2 { font-family: var(--ds-font-heading-2-face); font-size: var(--ds-font-heading-2-size); font-weight: var(--ds-font-heading-2-weight); line-height: var(--ds-font-heading-2-leading); letter-spacing: var(--ds-font-heading-2-tracking); } .ds-font-heading-3 { font-family: var(--ds-font-heading-3-face); font-size: var(--ds-font-heading-3-size); font-weight: var(--ds-font-heading-3-weight); line-height: var(--ds-font-heading-3-leading); letter-spacing: var(--ds-font-heading-3-tracking); } .ds-font-heading-4 { font-family: var(--ds-font-heading-4-face); font-size: var(--ds-font-heading-4-size); font-weight: var(--ds-font-heading-4-weight); line-height: var(--ds-font-heading-4-leading); letter-spacing: var(--ds-font-heading-4-tracking); } .ds-font-heading-5 { font-family: var(--ds-font-heading-5-face); font-size: var(--ds-font-heading-5-size); font-weight: var(--ds-font-heading-5-weight); line-height: var(--ds-font-heading-5-leading); letter-spacing: var(--ds-font-heading-5-tracking); } .ds-font-heading-6 { font-family: var(--ds-font-heading-6-face); font-size: var(--ds-font-heading-6-size); font-weight: var(--ds-font-heading-6-weight); line-height: var(--ds-font-heading-6-leading); letter-spacing: var(--ds-font-heading-6-tracking); } /* Running text, named by the job rather than numbered. The headings are a hierarchy, so a number tells you where you are on it. These four are four different jobs at four sizes, and copy, body, label and small are what they are called out loud. `text-wrap: pretty` rather than `balance`: balance is for short blocks and the browser gives up past a handful of lines anyway. */ /* What the four share is everything EXCEPT the type, which is each one's own now that a role carries all four halves. Written as one rule with the primitive in it, the class for a role was the last place in the package still saying `--ds-weight-standard` where it meant `copy`. */ .ds-font-copy, .ds-font-body, .ds-font-label, .ds-font-small, .ds-font-mono { margin: 0; color: inherit; text-wrap: pretty; } .ds-font-copy { font-family: var(--ds-font-copy-face); font-size: var(--ds-font-copy-size); line-height: var(--ds-font-copy-leading); font-weight: var(--ds-font-copy-weight); } .ds-font-body { font-family: var(--ds-font-body-face); font-size: var(--ds-font-body-size); line-height: var(--ds-font-body-leading); font-weight: var(--ds-font-body-weight); } /* The same two sizes as paragraphs: the UI pairs above keep the line every mark measures itself against, and these hold the same size on the reading line, for running text with no marks beside it. */ .ds-font-copy-prose { font-family: var(--ds-font-copy-prose-face); font-size: var(--ds-font-copy-prose-size); line-height: var(--ds-font-copy-prose-leading); font-weight: var(--ds-font-copy-prose-weight); } .ds-font-body-prose { font-family: var(--ds-font-body-prose-face); font-size: var(--ds-font-body-prose-size); line-height: var(--ds-font-body-prose-leading); font-weight: var(--ds-font-body-prose-weight); } .ds-font-label { font-family: var(--ds-font-label-face); font-size: var(--ds-font-label-size); line-height: var(--ds-font-label-leading); font-weight: var(--ds-font-label-weight); } .ds-font-small { font-family: var(--ds-font-small-face); font-size: var(--ds-font-small-size); line-height: var(--ds-font-small-leading); font-weight: var(--ds-font-small-weight); } /* Code: small's measures in the code face. A key to press, a value as it is written, a file's name. The fifth role of the running text, and the only one whose face is not the body's. */ .ds-font-mono { font-family: var(--ds-font-mono-face); font-size: var(--ds-font-mono-size); line-height: var(--ds-font-mono-leading); font-weight: var(--ds-font-mono-weight); letter-spacing: var(--ds-font-mono-tracking); } /* A word rather than a number, because this is a treatment and not a step on a scale. It is also the only role of the previous system's five worded ones that people actually reached for: 223 uses against zero for three of the others. */ .ds-font-overline { margin: 0; font-family: var(--ds-font-overline-face); font-size: var(--ds-font-overline-size); font-weight: var(--ds-font-overline-weight); /* The role's own, and this is a fix: it was `1.4`, a number no token holds, which on 14px is 19.6 and lands the line off every 4px step in the package. `--ds-font-overline-leading` is 16. */ line-height: var(--ds-font-overline-leading); letter-spacing: var(--ds-font-overline-tracking); text-transform: uppercase; color: inherit; } /* The overline one step down, for rows of metadata: the category and the date over a title, the key over a figure. The first consumer cut it by hand and wrote down why 10 and not 12: at this tracking, in capitals, the line reads larger than its number, and at 12 it competes with the title it introduces. */ .ds-font-micro { margin: 0; font-family: var(--ds-font-micro-face); font-size: var(--ds-font-micro-size); font-weight: var(--ds-font-micro-weight); line-height: var(--ds-font-micro-leading); letter-spacing: var(--ds-font-micro-tracking); text-transform: uppercase; } /* ── Text colour: the modifier ─────────────────────────────────────────── Sits ON a role, never instead of one. Measured on the previous system: of 863 uses of its text-colour utilities, 859 were on an element with no role at all, which means the colour was not modifying anything, it was standing in for the name that should have been there. The name says the whole thing: `.ds-text-colour--secondary-neutral` is the secondary neutral used as a text colour. What it applies is the token for that colour AS TEXT, and there are two shapes of that. A neutral exists only as text, so its token is named for it and the two are spelled the same. A status is a family where text is one of five uses, so the one for text carries `-ink` and the class stays named for the colour rather than for the token. `npm run check` holds the rule that matters underneath both: one of these classes may only apply a colour meant for text. Handing a reader the FILL is what they did before the inks existed, and a status fill measures around 3:1 as text. `-neutral` earns its place: the three strengths and the three status colours are both text colours, and the suffix is what tells them apart at a glance in a className. A status colour has two jobs and cannot hold both in one value. As a block it has to be seen, as text it has to be read, and the value that gets seen is too light to be read: bare `--ds-success` measured 3.16:1 on the page. The `-ink` is the same colour taken to where it passes. Four statuses, four classes. Info used to be left out on the grounds that it belongs to a container like an alert, which is true of warning and danger too, so it separated nothing: three of the four had a class and one did not, and that gap was the whole argument. `npm run check` holds the symmetry now. Brand is the one that stays out, and its reason is different in kind: a brand-coloured word is a link, which the element earns by being a link. It arrives with the anchor, not as a colour an author picks. */ .ds-text-colour--primary-neutral { color: var(--ds-text-primary-neutral); } .ds-text-colour--secondary-neutral { color: var(--ds-text-secondary-neutral); } .ds-text-colour--tertiary-neutral { color: var(--ds-text-tertiary-neutral); } /* Numbers for strength, words for meaning, one prefix for both, because they answer the same question: what colour is this text. A number says where on the scale, a word says what happened. Three and not five. Measured across twenty projects on the other system: error 60 uses, success 41, warning 22, and then info 2, which is two uses saying the need is not there. Info is a container's job, an alert or a banner, and it has tokens for that. `interactive` had 58 and is missing on purpose too: that is the colour of a link, which the element earns by being a link, and not a colour an author picks per element. It arrives with prose. These stay classes rather than becoming a component's business, because that is where the uses are. Of the ones counted, not one sat inside anything that would become a component: 57 were loose error messages and 54 were loose status text, an overdue date in a table row, a count that is going badly. A Field will own its own error message and will use these underneath, and the rest of it never had a component to belong to. */ /* The `-ink` and not the bare name. The bare name is chosen to be seen as a block of colour and is too light to be read as text on a pale surface: it measured 3.16:1 on the page for success and 3.05 for warning, both under AA. Nothing looked broken, which is why it needed measuring. */ .ds-text-colour--success { color: var(--ds-success-ink); } .ds-text-colour--warning { color: var(--ds-warning-ink); } .ds-text-colour--danger { color: var(--ds-danger-ink); } .ds-text-colour--info { color: var(--ds-info-ink); } } @layer components { /* components. See ROADMAP.md step 6. */ /* ========================================================================== Layout The CSS behind Stack, Row and Grid. Not public: nothing outside this package should type these class names, and they are absent from the exports map for that reason. The component IS the API. That is the whole point of the split. The other system published `.ds-stack` AND a `` doing the same job, and 879 elements used neither: with `flex`, `flex-col` and `gap-6` also on the shelf, the column gets assembled by hand every time, because the utility is already in the file you are editing and the import is not. Here the utilities do not exist, so there is one way to make a column. Gap takes the four named distances and nothing else. `line` means the children are two lines of one thing, `element` means they are parts of one thing, `block` means they are separate things in a section, `section` means they are sections. The last three change with the surface, so a stack is automatically denser in a panel than on a page. There is deliberately no arbitrary gap: if a layout wants 27px, that is a sign it is not a stack of related things, and step 7 will say whether the need is real. ========================================================================== */ .ds-stack, .ds-row { display: flex; min-width: 0; } .ds-stack { flex-direction: column; } .ds-row { flex-direction: row; } /* A stack, a row or a grid written as a list is a list to the reader and an arrangement to the eye: the marks and the indent a list arrives with are the browser's, and the container is the only owner of the distance here. Two pages had reset them by hand before the rule was written. */ .ds-stack:is(ul, ol), .ds-row:is(ul, ol), .ds-grid:is(ul, ol) { list-style: none; margin: 0; padding: 0; } .ds-grid { /* The narrowest a column is allowed to be before the grid gives one up. One number, and it is the whole of how this grid is responsive: see the columns below. A caller wanting cards that hold more or less moves it on the one grid rather than reaching for a breakpoint. 384, and the number is chosen to produce the ramp people expect from a row of cards without anybody writing it: a three-column grid draws one column on a phone, two on a tablet and three on a desk, because a third of a tablet is 325 and that is under the floor while a half of it is 481 and that is over. Measured on the three canvases rather than reasoned about. At 16rem a tablet kept all three at 314 apiece, which fits and reads cramped: the floor is a judgement about how narrow a card may be, and 314 was on the wrong side of it. */ --ds-grid-floor: 24rem; /* Zero until a gap class says otherwise, so the arithmetic below never reads a name nobody declared. */ --ds-grid-gap: 0px; display: grid; min-width: 0; } /* One distance, one owner: the container holds it and the children carry no margins. Two owners is how a 16px gap becomes 48 and nobody can say which rule to edit. */ /* The gap is named as well as set, because the column arithmetic below has to subtract it and `calc()` cannot read the `gap` property. */ .ds-gap-line { --ds-grid-gap: var(--ds-rhythm-line); gap: var(--ds-grid-gap); } .ds-gap-element { --ds-grid-gap: var(--ds-rhythm-element); gap: var(--ds-grid-gap); } .ds-gap-block { --ds-grid-gap: var(--ds-rhythm-block); gap: var(--ds-grid-gap); } .ds-gap-section { --ds-grid-gap: var(--ds-rhythm-section); gap: var(--ds-grid-gap); } .ds-align-start { align-items: flex-start; } .ds-align-center { align-items: center; } .ds-align-end { align-items: flex-end; } .ds-align-stretch { align-items: stretch; } .ds-align-baseline { align-items: baseline; } .ds-justify-start { justify-content: flex-start; } .ds-justify-center { justify-content: center; } .ds-justify-end { justify-content: flex-end; } .ds-justify-between { justify-content: space-between; } .ds-wrap { flex-wrap: wrap; } /* ── Columns ────────────────────────────────────────────────────────────── The number is a CEILING, not a promise: at most this many, and fewer where a column would come out under the floor. One line each, and no breakpoint anywhere. Every track is at least a share of the grid's own width — a third of it on a three-column grid — so the grid can never draw more columns than it was asked for; and every track is also at least `--ds-grid-floor`, so when a third of the room is narrower than that, only two fit, then one. `auto-fill` counts how many fit and draws that many tracks, whether or not anything lands in them. The `100%` is the GRID's width, which is the point. This was a media query at 47.99rem, and a media query asks the WINDOW: three cards in a 380px canvas inside a 1280px window stayed three cards of 116px with the badge sitting on top of the title, because as far as the query was concerned the window was wide. The same is true of a panel, a split view, a drawer and an embed. A grid does not know the window and has no business asking about it; it knows how much room it was given. 1 / 2 / 3 / 4 by width falls out of this rather than being written: with the default floor a three-column grid draws one column on a phone, two on a tablet and three on a desk. Moving the floor moves all three, which is the one dial. And the whole thing is capped at `100%`, which is not a detail: without it the track stays the FLOOR when the grid is narrower than the floor, so a 384 card sat in a 380 column and every card in the row hung four pixels out of the canvas with its badge cut off. A column can never be wider than the grid it is in, and saying so is one `min()`. ── Why `auto-fill` and not `auto-fit` ──────────────────────────────────── `auto-fit` collapses the tracks nothing landed in and hands their room to the ones that filled, so a grid asked for three columns and given one card draws that card across the whole row. On a page of 306 wide cards the single one came out 1296 by 1818: not a wide card, a poster. Measured 27 August 2026 on a landing page whose calendar had emptied down to one date, and the same shape turns up whenever a list is filtered down to its last item or a client unpublishes all but one. `auto-fill` keeps the empty tracks, so the ceiling holds from both sides: at most this many, and each one no wider than its share. A grid that genuinely wants its only child to fill the row asks for one column, which is a thing it can say. */ .ds-cols-1 { grid-template-columns: 1fr; } .ds-cols-2 { grid-template-columns: repeat( auto-fill, minmax(min(max(var(--ds-grid-floor), (100% - var(--ds-grid-gap)) / 2), 100%), 1fr) ); } .ds-cols-3 { grid-template-columns: repeat( auto-fill, minmax(min(max(var(--ds-grid-floor), (100% - 2 * var(--ds-grid-gap)) / 3), 100%), 1fr) ); } .ds-cols-4 { grid-template-columns: repeat( auto-fill, minmax(min(max(var(--ds-grid-floor), (100% - 3 * var(--ds-grid-gap)) / 4), 100%), 1fr) ); } /* Posters: a picture with a line under it reads at less than half the room a card of words needs, so a grid of them lowers its floor and the ceiling above does the rest. 10rem is a poster on a phone with two abreast. */ .ds-grid--posters { --ds-grid-floor: 10rem; } /* No ceiling at all: as many as fit, and the floor is the only rule. Its own floor because a grid that is not counting columns is usually holding wider things than a grid that is. */ .ds-cols-auto { --ds-grid-floor: 18rem; grid-template-columns: repeat(auto-fill, minmax(min(var(--ds-grid-floor), 100%), 1fr)); } /* ========================================================================== Avatar The CSS behind and . Private, like every other component's: nothing outside this package types these names. An avatar is the small picture that stands for someone, in the one place a row has for it. It holds a photo when there is one and the initials of the name when there is not, and the two are the same disc at the same size, so a list where half the people have uploaded a photo still lines up. ── The size is the control ramp ────────────────────────────────────────── The same six tiers a button and a field read, and for the same reason: an avatar sits on a row beside them, and two things on one row have to be exactly as tall as each other. Its own ladder would line up until the day one of the two was edited. ── The disc is neutral, and opaque ─────────────────────────────────────── Initials sit on a plain grey surface. A palette keyed off the name is the usual thing here and it spends colour on identity, which leaves nothing to say status with two columns later. Opaque because the disc is a lid as much as a ground. It was the interactive tint first, which is a 10% wash, and a wash shows what is under it: in a stack that is the face of the person before, so "TB" came out as two dark letters lying on somebody's photograph. A surface, not a veil. ========================================================================== */ .ds-avatar { --ds-avatar-face: var(--ds-font-body-face); /* This component's own. The role says what the words are; this says that THIS component wants a heavier hand than the role has, which is a decision the component makes and nobody else. Pointed at the semantic rather than holding a number, so moving the system moves every component that has not been moved on purpose, and moving one moves one. */ --ds-avatar-weight: var(--ds-emphasis-weight); /* Its initials are sized off the avatar and not off the type scale, because a circle of 24 and one of 64 want a letter in proportion to the circle. There is no paired leading for a size that has no token, so the line box is the letter itself, said here so a tool reads the decision. The size is in this list too. It was left out while the leading was in it, so a tool reading the pair was told half the decision: the leading was answered "on purpose" and the 9.6px letter beside it, from the same sentence, was reported as a value nobody had named. */ --ds-avatar-intent: line-height font-size; /* Positioned because the stack orders the discs with z-index, which does nothing to a static box. */ position: relative; display: inline-flex; align-items: center; justify-content: center; /* Never squeezed by the text beside it: the name gives, the face does not. */ flex: none; inline-size: var(--ds-avatar-size); block-size: var(--ds-avatar-size); border-radius: var(--ds-radius-full); background-color: var(--ds-surface-3); --ds-avatar-ink: var(--ds-text-primary-neutral); color: var(--ds-avatar-ink); font-family: var(--ds-avatar-face); font-weight: var(--ds-avatar-weight); /* A share of the disc rather than a tier of the type scale, so the initials are the same weight of mark at 24px and at 64px. Fixed at 14 they fill the small disc and rattle around inside the large one. */ /* Named, because a value the panel cannot name is a value nobody can find: read back it was a bare 16px on a 40px disc and no token held it. */ --ds-avatar-initials-size: calc(var(--ds-avatar-size) * 0.4); font-size: var(--ds-avatar-initials-size); line-height: 1; /* The photo is cropped by the disc rather than by its own rounding, which is what lets `shape` change one number here and be done. */ overflow: hidden; /* A double click on a row should not select the initials. */ user-select: none; } .ds-avatar--xsmall { --ds-avatar-size: var(--ds-size-1); } /* 24 */ .ds-avatar--small { --ds-avatar-size: var(--ds-size-2); } /* 32 */ .ds-avatar--medium { --ds-avatar-size: var(--ds-size-3); } /* 40 */ .ds-avatar--large { --ds-avatar-size: var(--ds-size-4); } /* 48 */ .ds-avatar--xlarge { --ds-avatar-size: var(--ds-size-5); } /* 56 */ .ds-avatar--xxlarge { --ds-avatar-size: var(--ds-size-6); } /* 64 */ /* Square reads the roundness ramp rather than a number of its own, so it follows `data-radius` with everything else: rounded on the soft setting and a true square on the sharp one. */ .ds-avatar--square { border-radius: var(--ds-radius-2); } .ds-avatar__image { /* Over the initials rather than instead of them: both are rendered, because a server cannot hear an image fail and the behaviour bundle must not build the replacement. The picture covers the letters while it is there, and the rule below takes it away when it is not. */ position: absolute; inset: 0; display: block; inline-size: 100%; block-size: 100%; /* Cover and not contain: a portrait is cropped to the disc, and a letterboxed face with tint above and below it looks like a broken image. */ object-fit: cover; border-radius: inherit; } /* ── The stack ──────────────────────────────────────────────────────────── Several faces in the room one takes. Used where the count is the point and the faces are the texture: a bulk bar over a selection, the people on a project. The ring is what keeps them apart. It is drawn OUTSIDE the disc as a shadow, so it costs no layout and the discs stay exactly as far apart as the margin says. White, in both themes, for the reason the token itself gives: what it separates is photographs, and a photograph has no theme. It was the surface underneath at first, which is right while the stack sits on the page and gone the moment it does not: on a grey bar the ring came out grey and four faces ran together into one shape. `--ds-avatar-ring` is still there for wherever white is the wrong answer. */ .ds-avatar-stack { display: inline-flex; align-items: center; } .ds-avatar-stack > .ds-avatar { box-shadow: 0 0 0 2px var(--ds-avatar-ring, var(--ds-static-white)); } /* A share of the disc, so the overlap looks the same at every size. Read off the child, which is where the size variable is declared. */ .ds-avatar-stack > .ds-avatar + .ds-avatar { margin-inline-start: calc(var(--ds-avatar-size) * -0.3); } /* Every disc but the first has its left third under the one before it, and initials centred in the disc are therefore initials with a letter half hidden: a stack of six people read as a row of smudges. The letters move into the part that is still visible, by half of what is covered, which centres them there. Photographs need none of this, since a face is cropped by the disc already. */ .ds-avatar-stack > .ds-avatar:not(:first-child) > .ds-avatar__initials { transform: translateX(calc(var(--ds-avatar-size) * 0.15)); } /* ── The rest, as a number ──────────────────────────────────────────────── A number, written as a number. It was a disc for a revision, and a grey circle at the end of a row of photographs reads as a face that failed to load: the eye counts five people and finds four. Sized off the stack rather than off the type scale, so it stays in proportion at every tier: the ramp is declared on the stack for this one line, since a span outside the discs cannot read a variable one of them set. */ .ds-avatar-stack--xsmall { --ds-avatar-size: var(--ds-size-1); } .ds-avatar-stack--small { --ds-avatar-size: var(--ds-size-2); } .ds-avatar-stack--medium { --ds-avatar-size: var(--ds-size-3); } .ds-avatar-stack--large { --ds-avatar-size: var(--ds-size-4); } .ds-avatar-stack--xlarge { --ds-avatar-size: var(--ds-size-5); } .ds-avatar-stack--xxlarge { --ds-avatar-size: var(--ds-size-6); } .ds-avatar-stack__more { --ds-avatar-stack-more-face: var(--ds-font-body-face); margin-inline-start: var(--ds-space-2); font-family: var(--ds-avatar-stack-more-face); --ds-avatar-stack-more-size: calc(var(--ds-avatar-size) * 0.35); font-size: var(--ds-avatar-stack-more-size); font-weight: var(--ds-avatar-weight); --ds-avatar-stack-more-ink: var(--ds-text-secondary-neutral); color: var(--ds-avatar-stack-more-ink); font-variant-numeric: tabular-nums; white-space: nowrap; } /* ── The face that is a control ─────────────────────────────────────────── An account menu opens from the reader's own picture, and the way that was built here was an avatar inside a mark button: a circle inside a rounded square, with the focus ring drawing the square around the circle. Two shapes for one target. So the face IS the control. It keeps its own shape, which is the point, and takes the ring and the hover a control owes a reader. */ .ds-avatar--pressable { padding: 0; border: 0; cursor: pointer; /* A button inherits neither the face nor the leading, and the sizes below are read off the tier rather than the line, but the initials inside are type: without this they come out at the user agent's own size. */ font: inherit; /* The ring follows the picture, because `border-radius` is what an outline follows and the avatar's is already the circle. */ transition: box-shadow var(--ds-duration) var(--ds-ease); } .ds-avatar--pressable:hover { /* A ring the colour of the page's own line, in the gap the ring offset leaves, so the face is not dimmed or tinted: a photograph under a wash is a photograph nobody chose. */ box-shadow: 0 0 0 2px var(--ds-border-strong); } .ds-avatar--pressable:focus-visible { outline: 2px solid var(--ds-focus); outline-offset: 2px; } /* What the bundle writes when the picture fails, and the whole of what it writes: the letters were underneath the entire time. */ .ds-avatar[data-broken] .ds-avatar__image { display: none; } /* ── The face beside its name ───────────────────────────────────────────── Owner's call, 22 August 2026: the face-and-name pair was hand-built in two playground tables with a Row and a Stack, and the gap between the two was a decision taken twice. The pair is the avatar's own now: `label` draws the name at the type the size asks for, `description` the quiet line under it, and when anything presses it is the whole row that presses. */ .ds-avatar-identity { display: inline-flex; align-items: center; gap: var(--ds-rhythm-element); min-inline-size: 0; color: inherit; text-decoration: none; text-align: start; } /* A