@deriv-com/dds-marketing 0.1.0 → 1.0.0

package/.llm/rules.md

@@ -0,0 +1,146 @@
+<!-- GENERATED from rules/*.rule.json. Do not edit. -->
+
+# Rules
+
+Constraints that span more than one component. Rules about a single component
+also appear in that component's own document.
+
+## Always
+
+### On a phone a section's actions stack and each fills the width, including when there is only one
+
+On a phone a page's actions stack, and each one fills the width. Not most of it, and not the width its label happens to need — the whole column.
+
+Two side by side is what this replaces. On the narrowest screen each gets half a column minus the gap, which is rarely enough for a real label: the words wrap inside the pills, the two buttons come out different heights, and the pair reads as a broken row rather than as a choice. Stacked, each has the whole width and neither has to shorten its words to fit.
+
+A single action fills too, and that is the part worth saying, because it is the one that looks unnecessary. A lone button has the room to sit at its natural width and still should not: a full-width control is the phone's convention for the thing the screen is asking you to do, and a pill hugging its label reads as one option among others that are not there. It also makes the target predictable — the whole width, wherever the thumb lands — which a centred pill does not.
+
+Filling is the row's job rather than the button's. A button has no width of its own and is not given one; the row it sits in becomes a column and stretches its children, so nothing about the control changes and the same button is full width here and its own size on a desktop.
+
+This is the phone's breakpoint, size.breakpoint.md, and not the wider one that decides whether a heading is centred. Those are different questions and they break at different widths: a heading stops being centred when the measure is the screen, while a button stops being full width much sooner than that — stretched across a tablet it is a long way from its own label, and a label centred in a metre of pill is harder to hit than one in a pill the size of the words.
+
+What this is not about is every row of controls. A set of filter chips, a pagination strip, a toolbar, a link sitting after a sentence — none of these is the page asking for something, and stacking them to full width would turn a strip the eye skims into a list it has to read. The test is whether the row is the call to action the section was written for.
+
+Guidance only — cannot be checked automatically.
+
+### Never nest one interactive element inside another
+
+Nested interactive elements produce ambiguous hit targets and an unreachable inner control for keyboard and screen-reader users. This is why the rule cannot live on any single component — it constrains Button, Link, Input and Switch simultaneously.
+
+Guidance only — cannot be checked automatically.
+
+### A section that paints a ground sets the ink to go with it
+
+A page sits on color.bg.page, and a section that separates itself from it takes one of three grounds. color.bg.subtle is the light one and needs nothing further — the page's own ink still reads on it. The other two are dark and do not: color.bg.brand-strong takes color.fg.on-brand-strong, and color.bg.brand takes color.fg.on-solid. Both are white, and both are written as the role rather than the white they resolve to. Set one of those backgrounds without its ink and the text inherits whatever the page was already using, which is near-black on a dark band — legible to nobody, and invisible to every check here, because each pair passes contrast on its own and nothing can tell whether a section used both.
+
+color.bg.brand carries a second limit that is not about forgetting. Its ink measures 3.39:1, which clears the 3:1 a heading needs and misses the 4.5:1 running copy needs. A coral band may carry a headline and a call to action; a paragraph on one is text the reader has to work through at a ratio the waiver on that role does not cover — the waiver says so itself. A section with copy in it takes color.bg.brand-strong, which is near-black and carries white at full contrast.
+
+color.bg.strong is not a section ground. It is the inverted fill for an action that has to outrank what surrounds it, and the components that paint it — Button and ButtonIcon in their inverse form — already set both halves in one rule, which is the pattern a hand-painted section has to copy.
+
+Guidance only — cannot be checked automatically.
+
+### Every gap inside a section names the relationship it expresses, and the same relationship keeps its measure when it turns on its side
+
+A section's spacing is named by the relationship it expresses, not chosen by size. Every gap in a section has a role token, and reaching for a step off the generic scale because it happens to be the right number is how two sections written by two people stop lining up: the numbers agree today and drift the first time one of them is tuned.
+
+The heading group is three steps, not one gap. An eyebrow sits nearer its title than the title sits to its description, and the actions sit further from the description than either — space.heading.eyebrow-title, space.heading.title-description, space.heading.description-actions, in that order. A single `gap` on the group cannot say this; it sets all three the same and the block reads as evenly spaced lines rather than as a mark, a name and a paragraph. The eyebrow has to identify itself for this to work, because a group that opens with a title must not give its description the eyebrow's tighter step.
+
+The step between a title and its description follows the size of the title, which is why there are two of it. What a reader sees is not the gap but the gap plus the leading above it, and leading scales with the type: under a display title the leading is most of the space, under a card's title it is half as deep. One value for both makes a card look loose at the size that made a section look right. So space.heading.title-description is the display step and space.heading.title-description-compact is the step at a card's size, and the choice is made by how big the title is rather than by what kind of block it sits in.
+
+Every one of those steps is smaller than the gap below the group, and that ordering is what holds the group together as one thing. space.heading.content is the step between a heading group and the content it introduces, and it is the widest measure inside a section: the one gap the eye reads as a change of subject rather than as a continuation.
+
+That step is the same whether the content is under the heading or beside it. A split is the same relationship turned on its side — a heading group and the content it introduces — so the space between the two halves is space.heading.content, not a gutter. When the split collapses to one column on a phone the gap becomes vertical again, which is where it started, and nothing has to change for that to be right.
+
+space.grid.gutter is between two things of the same kind. Two cards in a row are the same kind; the two halves of a split are not, which is why the gutter is the wrong measure there even when the number would have looked acceptable. The gutter runs on both axes, so a grid reads as an even field rather than as rows with a seam down them.
+
+space.inset.card is the card's, not the page's. A row of cards padded differently is a row of different cards, and the fill is the only edge they have. A page composing a row does not get to choose it.
+
+Column count is not a breakpoint decision. A row holds as many columns as fit before a column would be narrower than size.grid.column-min, and drops one when they would not. Written as a fixed count that collapses at a breakpoint, a four-up row keeps four columns at every width above the phone and sets its copy two or three words to a line through the whole of the tablet range — and on a narrow desktop, which no breakpoint sits on at all. The threshold is a property of the row rather than of a card: a card fills whatever cell it is given.
+
+What this does not cover is the space above and below a section, which is space.section.default and space.section.compact, and the page's own side margin, which is space.inset.page. Those are the section's outside; everything here is its inside.
+
+Guidance only — cannot be checked automatically.
+
+### A section's title is centred over stacked content, starts beside content in columns, and starts on a phone
+
+Two arrangements, and the title's alignment is decided by which one it is introducing rather than chosen per section.
+
+Content stacked under the title — a row of cards, an accordion, a set of steps — takes a centred title. The heading group and the block below it share one axis, so a centred title is symmetric with the thing it names, and the eye drops from the middle of the words to the middle of the set. A title starting at the left over a centred or full-width block reads as belonging to the first column rather than to all of them.
+
+Content beside the title — a split, a picture in the other half, anything laid out in columns — takes a title that starts where its content starts. The two share a left edge, and that edge is what says they are one thing read across rather than two stacked. Centring the title there breaks the only alignment the reader has to hold the halves together, and it drifts further from its content the wider the page gets.
+
+The heading group is what carries this, not the heading alone. An eyebrow, a title and a description are read as one block and align together; aligning the title without them leaves a centred heading over start-aligned copy, which reads as a mistake rather than as a choice.
+
+Centred means all of it, not just the words. A badge, a row of actions, a picture — these are flex children, and a flex child is placed by align-items rather than by text-align, so a block that only sets the text leaves everything that is not text at the start. A hero is the case that shows it: its title and copy centred while its badge and its buttons did not.
+
+A capped block centres itself as well as its words. A heading group takes size.heading-group.max, and a cap that is not centred leaves the measure at the start of the column with the words centred inside it — composed, and a long way left of the middle it appears to be in.
+
+Both arrangements go to the start on a phone. A centred block reverts below the breakpoint, and the reason is the measure: on a phone the measure is the screen, so a centred title wraps to three or four ragged lines and the eye loses the left edge it was tracking — the same symmetry that reads as composure on a desktop is what makes it hard to scan on a phone. Centring there has to be asked for twice, and a section title is not one of the things that asks: it is centred because there is room for it, and on a phone there is not. Going back to the start means all of it too, and a capped block is the one that hides a leftover: its words go to the start while its measure stays in the middle of the column, which reads as a title still centred over a badge and buttons that are not — the box in the middle and the line inside it at the edge.
+
+A hero is a section like any other: its badge, title, copy and actions are one stacked block, so it is centred on a desktop and starts on a phone with everything else.
+
+What this is not about is a page whose body is a form or a document. A title over a sign-up form or a guide is not introducing a set of content — it is the first line of the thing itself, and it keeps the alignment the body has, which for running text is the start. The distinction is whether the block below is content the title names or content the title is part of.
+
+Guidance only — cannot be checked automatically.
+
+### Anything a pointer has to hit is at least 24px in both directions
+
+A control sized by its contents is as big as its contents, and a glyph is chosen for how it reads rather than for how easily it is hit. An icon-only button with no padding is a 16px target — smaller than the pad of a finger, and smaller than the tremor of a hand using a mouse.
+
+WCAG 2.2 asks for 24 by 24 CSS pixels at AA. The exceptions are narrower than they look: inline targets inside a sentence are exempt, and so is a small target with 24px of clear space around it — but a clear button sits against the field it empties, and a field is itself a target, so the spacing exemption does not apply to the case that keeps arising.
+
+The target and the mark are separate decisions, and conflating them is what produces both faults. Growing the glyph to 24px makes it shout; leaving the button at 16px makes it hard to hit. So the glyph keeps the size that reads correctly beside its text, and the box around it declares a minimum of its own — which is what size.target.min is for.
+
+Declared rather than emergent. Padding plus contents does clear 24px in several components today, and it is the weaker statement: it is a size nobody wrote down, so it moves when the type scale or the glyph does, and nothing says it was meant to be a target at all.
+
+Guidance only — cannot be checked automatically.
+
+### A component is written along the reading axis, not along the page's left and right
+
+Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+
+Guidance only — cannot be checked automatically.
+
+## Component rules
+
+### Destructive actions require a confirmation step (`Button`) *(applies to something not built yet)*
+
+An irreversible action taken by mis-click has no recovery path. The confirmation must name what will be lost, not merely ask whether the user is sure.
+
+Guidance only — cannot be checked automatically.
+
+### Solid weight means selected (`Icon`) *(applies to something not built yet)*
+
+Solid is not an alternative style, it is what a selected icon looks like. A tab or a navigation item renders regular at rest and swaps to solid when it becomes the current one, so the weight change is what carries the selection. The swap changes weight only — the same glyph at the same size, so the shape stays recognisable and just fills in. Marketing has fewer selected states than Product does, which is the reason to hold the meaning rather than to relax it: a solid glyph used decoratively here teaches a reader that solid means nothing, and they carry that into the product.
+
+Guidance only — cannot be checked automatically.
+
+### Match the glyph weight to the icon size (`Icon`) *(applies to something not built yet)*
+
+Quill ships every system glyph three times — light, regular and solid — as separate components chosen at the import site. Icon has no weight prop and cannot have one, so nothing in this system can observe the choice, let alone enforce it. Size is what should decide it: a glyph carries its stroke weight through any scale, so a regular-weight glyph drawn for 24px renders its strokes at over three times that width when placed at display size, and reads as heavy rather than confident. At rest, use regular from sm through lg, and light at xl, 2xl and display — selection is the one thing that overrides this, and it only ever moves regular to solid.
+
+Guidance only — cannot be checked automatically.
+
+### A navigation bar holds at most two buttons: one primary, and one secondary beside it (`Button`)
+
+The bar's actions are the conversion and the way back in for a reader who already has an account — sign up and log in. That is two things, and they rank: the one the site wants is primary and the other is secondary. A third button is a third thing the bar is asking for, and a row of three pills beside a mark and a set of destinations stops reading as a pair of actions and starts reading as a second navigation.
+
+A single button is the primary. Alone, there is nothing for a secondary to be quieter than, and a bar whose only action is the quiet one has hidden the thing it exists to offer. Two buttons are one primary and one secondary, never two of either: two primaries are two demands, and two secondaries leave the reader to guess which one the site meant.
+
+A switcher is not a button here — a DropdownMenu or a ButtonIcon for the language or the theme — and does not count against the two.
+
+Guidance rather than a count. The bar is drawn with a second copy of an action in compactAction for narrow widths, and a count of Buttons under Navbar cannot tell that slot from utilities or a ranked pair from two primaries. Navbar checks the pair itself, on what utilities is handed, and says so in the console.
+
+Guidance only — cannot be checked automatically.
+
+### At most one primary button per view (`Button`)
+
+Two primary actions compete for attention; the user cannot tell which one the system wants them to take.
+
+Machine-checkable — `dds lint` will enforce this once built.

package/.llm/tokens.md

@@ -0,0 +1,385 @@
+<!-- GENERATED from tokens/semantic/**. Do not edit. -->
+
+# Tokens
+
+Write the CSS variable, never the value it resolves to. Resolved values are
+deliberately not published here — copying one is the hardcoding this system rejects.
+
+Some roles below are marked **adapts**. Those already change at 768px on their own —
+write the variable once and do not add a media query for it. Every other role holds
+one value at every width.
+
+## color
+
+- `--color-bg-active` — Pressed state for interactive elements. Alpha-based like the hover and one step heavier, so it tints whatever surface it lands on — ink on light and paper on dark.
+- `--color-bg-active-inverse` — Pressed state for an interactive element on a surface that runs against the mode, one step heavier than color.bg.hover-inverse. The mirror of color.bg.active, and paired with it on the same reasoning.
+- `--color-bg-active-on-brand-strong` — Pressed state for an interactive element standing on color.bg.brand-strong, one step heavier than color.bg.hover-on-brand-strong. White at eight in both modes. For a surface that flips with the mode use color.bg.active-inverse.
+- `--color-bg-band-subtle` — A recessed band across the page, e.g. a section of steps or features set apart from the ones around it. gray.50 in light, white at six in dark. For a fill inside a control — a secondary button, a badge — use color.bg.subtle.
+- `--color-bg-brand` — Primary action surface, e.g. sign-up button, hero CTA, promotional banner. The same coral in light and dark; pair with color.fg.on-brand for text.
+- `--color-bg-brand-active` — Pressed state for color.bg.brand. One step further along the ramp than the hover, in the same direction, so a press reads as more of what the hover began.
+- `--color-bg-brand-hover` — Hover state for color.bg.brand.
+- `--color-bg-brand-strong` — A dark surface, for a band breaking a long page or a card carrying more weight than its neighbours, e.g. a feature band, the footer. gray.950 in light and dark alike, so the band is the same wherever it is drawn. Pair with color.fg.on-brand-strong for text.
+- `--color-bg-brand-subtle` — A brand ground quiet enough to read dark ink on. The solid coral takes white at 3.39:1 and is waived for a word; this pairs with color.fg.brand well past the bar, so a mark can be brand-coloured without spending the waiver.
+- `--color-bg-danger` — Destructive action surface, e.g. cancel subscription, delete account. Pair with color.fg.on-solid for text.
+- `--color-bg-danger-subtle` — Lightweight danger fill, e.g. error banners, danger badges. Pair with color.fg.danger for text.
+- `--color-bg-field` — The ground of a control a reader types into or picks from — a text field, a select, an upload zone. An alpha, so it can never come out the same colour as the container holding it, which a solid can. For the container itself use color.bg.surface.
+- `--color-bg-hover` — Hover state for interactive elements. Alpha-based, so it tints whatever surface it lands on rather than replacing it — ink on light and paper on dark, because a black alpha on a dark surface darkens what is already dark and reads as nothing at all.
+- `--color-bg-hover-inverse` — Hover for an interactive element on a surface that runs against the mode — a dark chip in light. The mirror of color.bg.hover, which tints with the mode and so shows nothing on a ground the mode did not paint. Use color.bg.hover where the mode paints the ground.
+- `--color-bg-hover-on-brand-strong` — Hover for an interactive element standing on color.bg.brand-strong, e.g. a navigation item or a plain icon button on a dark hero. White at four in both modes, because the band does not change. For a surface that flips with the mode use color.bg.hover-inverse.
+- `--color-bg-info` — Informational surface, e.g. info banners, tips. Pair with color.fg.on-solid for text.
+- `--color-bg-info-subtle` — Lightweight info fill, e.g. info badges, inline notices. Pair with color.fg.info for text.
+- `--color-bg-overlay` — Scrim behind modal dialogs and drawers. Blocks interaction with content beneath.
+- `--color-bg-overlay-subtle` — Light scrim for loading states and image overlays.
+- `--color-bg-page` — The website's ground. A section that needs separating from it takes color.bg.subtle, color.bg.brand-strong or color.bg.brand, rather than the page carrying a tint of its own.
+- `--color-bg-readonly` — A field whose value is fixed but still worth reading. Lighter than the disabled ground and at full contrast, which is the distinction: readonly is legible and settled, disabled recedes because it is not actionable.
+- `--color-bg-selected` — The active or current item in a set of choices, e.g. selected nav item, current tab, highlighted row. Not for recessive areas — use color.bg.subtle.
+- `--color-bg-strong` — Inverted neutral fill for an action that has to outrank everything around it — near-black in light and pure white in dark, the highest contrast the page can carry. Not a section ground: a band takes bg.subtle, bg.brand-strong or bg.brand. Pair with color.fg.on-strong.
+- `--color-bg-strong-on-brand` — The solid fill of a control on color.bg.brand, e.g. the primary action on the coral band. Near-black in both modes, because the band does not change — unlike color.bg.strong, which turns white in dark.
+- `--color-bg-subtle` — A recessive fill inside a control or a small area, e.g. a secondary button, a neutral badge. For a band across the page use color.bg.band-subtle; for selected items, color.bg.selected.
+- `--color-bg-subtle-on-brand-strong` — A recessive fill on a painted band — color.bg.brand-strong or the coral color.bg.brand — e.g. a secondary button there. White at six in both modes; hover and press layer color.bg.hover-on-brand-strong and color.bg.active-on-brand-strong over it.
+- `--color-bg-success` — Confirmation surface, e.g. sign-up complete, payment confirmed. Pair with color.fg.on-solid for text.
+- `--color-bg-success-subtle` — Lightweight success fill, e.g. success banners, success badges. Pair with color.fg.success for text.
+- `--color-bg-surface` — A card on the page: one step from the ground, so it reads as recessed against the page and raised on a subtle band. For a card that floats above the page, color.bg.surface-raised.
+- `--color-bg-surface-card-light` — A light card that stays light whatever the theme, e.g. a surface-light Card or CardButton set among dark ones. gray.50 in both modes. Pair with color.fg.on-surface-card-light; for a card that follows the theme use color.bg.surface.
+- `--color-bg-surface-card-light-raised` — The light card on a subtle band. White in light mode, where the band is the light card's own gray.50 and it would vanish; gray.50 in dark, where the band is a tint over near-black. Pair with color.fg.on-surface-card-light.
+- `--color-bg-surface-card-raised` — A card lifting off the ground behind it, e.g. a Card or CardButton on a color.bg.subtle band. White in light, white at six in dark, so a dark card tints the band instead of sitting on it as grey. Menus and popovers take color.bg.surface-raised.
+- `--color-bg-surface-card-strong` — The dark fill of a card weightier than its neighbours, e.g. an accent-strong Card or CardButton. gray.900 in both modes, a step lighter than color.bg.brand-strong so it reads as a card, not a band.
+- `--color-bg-surface-card-strong-raised` — The strong card on a subtle band. gray.900 in light mode, the strong card's own fill, which already stands off the gray.50 band; gray.800 in dark, where the band is a near-black tint the strong card would blend into. Pair with color.fg.on-brand-strong.
+- `--color-bg-surface-inverse` — The quieter of the two surfaces on a dark ground, for a panel rather than a pill. color.bg.surface-raised-inverse is the stronger lift and is right on a control the size of a navbar's; at that weight a card-sized box reads as a pale patch rather than a surface.
+- `--color-bg-surface-modal` — A surface that covers the page behind a scrim — dialogs, drawers, bottom sheets. The topmost plane there is, so it stays white in light where color.bg.surface is recessed. For one that floats without dimming what is under it use color.bg.surface-raised.
+- `--color-bg-surface-raised` — A surface that lifts off the one behind it, e.g. a dropdown, a popover, a card on a color.bg.subtle band. A card on the page itself takes color.bg.surface, which reads as recessed against it instead.
+- `--color-bg-surface-raised-inverse` — A raised surface on a ground that runs against the mode — a navigation bar's pill on a dark hero. An alpha rather than a grey step: a hero is often a photograph or a brand colour, which a solid surface would clash with.
+- `--color-bg-surface-raised-on-brand-strong` — A raised surface on color.bg.brand-strong, e.g. the navigation bar's pill on a dark hero. White at twenty-four in both modes, because the band does not change. For one that flips with the mode use color.bg.surface-raised-inverse.
+- `--color-bg-surface-translucent` — The base of a see-through surface with a blur behind it, e.g. the navigation bar's pill. Nearly opaque in its own ink — white in light, black in dark — so what scrolls behind cannot set its colour. color.bg.surface-translucent-tint goes over it.
+- `--color-bg-surface-translucent-on-brand-strong` — The base of a see-through surface on color.bg.brand-strong, e.g. the navigation bar's pill on a dark hero. Black at eighty-eight in both modes, so a light photograph behind cannot wash it out.
+- `--color-bg-surface-translucent-tint` — The lift laid over color.bg.surface-translucent, e.g. the navigation bar's pill. None in light, where the base is already the surface; white at sixteen in dark, which is what makes the pill read as a surface over the page.
+- `--color-bg-surface-translucent-tint-on-brand-strong` — The lift laid over color.bg.surface-translucent-on-brand-strong, e.g. the navigation bar's pill on a dark hero. White at twelve in both modes, because the band does not change.
+- `--color-bg-track` — The channel a thing travels or fills along — a grab handle on a sheet, a rail. An alpha rather than a ramp step, so it darkens whatever is behind it and stays a groove on a raised panel, where a fixed grey would stop matching the moment the surface changed.
+- `--color-bg-track-active` — Pressed state for the same mark. One step further than the hover, in the same direction, so a press always reads as more than a hover.
+- `--color-bg-track-hover` — Hover state for a mark drawn in color.bg.track, which is the only thing in this colour that hovers — a track itself never does. One step more ink, so a pointer over the mark reads as more, never less. An alpha like the track, so it keeps tinting what is behind it.
+- `--color-bg-transparent` — A fill that is declared and not seen, for an element whose own surface must show through rather than whatever a page happens to sit it on. Needed because omitting the background would leave that surface showing instead.
+- `--color-bg-warning` — Caution surface, e.g. limited offer, expiring promotion. Pair with color.fg.on-solid for text.
+- `--color-bg-warning-subtle` — Lightweight warning fill, e.g. warning banners, warning badges. Pair with color.fg.warning for text.
+- `--color-border-danger` — Error validation border, e.g. input with failed validation, error banner edge.
+- `--color-border-default` — Standard border for containers and controls, e.g. input outlines, grouped sections.
+- `--color-border-focus` — The keyboard focus indicator — a border on some controls, a ring on others. Never remove: required for accessibility. Neutral rather than blue, so it is never mistaken for the danger a control is also able to show. Inverts by mode.
+- `--color-border-focus-inverse` — The focus ring on a ground that runs against the mode. color.border.focus is near-black, which is invisible on a dark bar — and a focus ring that cannot be seen is the one affordance a keyboard reader has nothing to fall back on.
+- `--color-border-focus-on-brand-strong` — The focus ring on color.bg.brand-strong, e.g. a navigation bar's controls on a dark hero, a footer's links. White in both modes, because the band does not change. For a surface that flips with the mode use color.border.focus-inverse.
+- `--color-border-info` — Informational accent border, e.g. info banner edge, highlighted section.
+- `--color-border-strong` — Emphasised border for active or prominent elements, e.g. active input, selected card edge.
+- `--color-border-subtle` — A quiet separator, e.g. dividers, table rules. Alpha-based — works on any surface.
+- `--color-border-subtle-inverse` — A quiet rule on a dark ground. The counterpart to color.border.subtle, which is black at 5% and invisible on one.
+- `--color-border-success` — Success validation border, e.g. confirmed input, success banner edge.
+- `--color-border-warning` — Warning validation border, e.g. approaching-limit input, warning banner edge.
+- `--color-fg-brand` — Brand-coloured text, for a mark or a line on color.bg.brand-subtle. Not for text on the page: the brand is a colour a page uses to point at something, and copy set in it is a page pointing at all of itself.
+- `--color-fg-brand-accent` — The brand label at full saturation — the brand fill's own red, the same in both modes, so a label and a fill agree. For the one row a reader is already on. Only on the bare page, never a tint. 3.11:1 as text, under AA: never the only thing saying it.
+- `--color-fg-danger` — Error and destructive text on neutral surfaces, e.g. validation messages, negative values.
+- `--color-fg-default` — Headings and body copy — the default for any readable content.
+- `--color-fg-disabled` — Text on disabled controls. Intentionally low contrast — the control is not actionable.
+- `--color-fg-info` — Informational text on neutral surfaces, e.g. links, tips, contextual help.
+- `--color-fg-muted` — Supporting copy, e.g. subheadings, feature descriptions, form labels. Not for content the user must read to act.
+- `--color-fg-muted-inverse` — Supporting copy on a dark ground, e.g. a footer's group labels. White at sixty-four, so it takes the hue of whatever the band is painted rather than sitting cool against a warm one — and so it stays muted on any dark ground instead of on one.
+- `--color-fg-on-brand` — Text and marks on color.bg.brand, e.g. a primary button's label, a checked accent checkbox's tick. White in light and dark alike, because the brand fill does not change with the theme. For other solid fills — danger, success, info — use color.fg.on-solid.
+- `--color-fg-on-brand-strong` — Text and glyphs on color.bg.brand-strong. White in both modes, that surface being dark in both — unlike color.fg.on-solid, which follows the theme.
+- `--color-fg-on-solid` — Text on solid status fills, e.g. danger, success, info buttons and badges. For text on color.bg.brand use color.fg.on-brand; on neutral surfaces use color.fg.default.
+- `--color-fg-on-strong` — Text on color.bg.strong. The opposite extreme from the fill, so the pair is always near-black on white or white on near-black.
+- `--color-fg-on-strong-on-brand` — Text and glyphs on color.bg.strong-on-brand, the near-black fill on the coral band. White in both modes, because the fill does not change — unlike color.fg.on-strong, which follows the theme.
+- `--color-fg-on-surface-card-light` — Text on color.bg.surface-card-light, e.g. a surface-light card's title and copy. gray.950 in both modes, because the card does not change. On the page's own ground use color.fg.default.
+- `--color-fg-on-warning` — Text on a warning surface. Always dark because the warning background is bright in both modes.
+- `--color-fg-required` — The mark that says a field must be filled. The same red as fg.danger and a role of its own, because required is not a verdict — a field carrying an asterisk has not failed anything yet.
+- `--color-fg-success` — Positive text on neutral surfaces, e.g. profit values, confirmation messages.
+- `--color-fg-tertiary` — De-emphasised text, e.g. fine print, legal disclaimers, footnotes.
+- `--color-fg-warning` — Caution text on neutral surfaces, e.g. approaching limits, expiring sessions.
+
+## space
+
+- `--space-actions-gap` — The step between two calls to action standing side by side. Eight: they are one decision offered two ways, not two decisions, and the reference design sets them this close on every band. Sixteen read as two separate offers.
+- `--space-control-lg` — Side padding inside a large pill control. Half of size.control.lg, on the same reasoning as the default step. It coincides with space.inset.lg today and is still its own role: one follows a control's height, the other a section's rhythm, and they are free to move apart.
+- `--space-control-md` — Side padding inside a default-size pill control. Half of size.control.md, so the corner radius and the padding are one measure and a label starts where the curve stops. The inset scale has no step here — its steps answer to sections, not to a control's geometry.
+- `--space-control-sm` — Side padding inside a small pill control. Half of size.control.sm, on the same reasoning as the default step — the corner radius and the padding are one measure, so a label starts where the curve stops.
+- `--space-gap-2xl` **adapts** — Between one section of a page and the next.
+- `--space-gap-3xl` **adapts** — The largest gap, for separating whole movements of a long page.
+- `--space-gap-lg` — Gap between content groups, e.g. feature cards in a grid, footer columns, pricing plans.
+- `--space-gap-md` — Default gap between stacked items, e.g. form fields, feature list items, pricing features.
+- `--space-gap-none` — No gap at all, for a row whose marks are meant to read as one object rather than as a list of controls. The only step here that is a decision rather than a measure.
+- `--space-gap-sm` — Gap between sibling controls, e.g. buttons in a row, form label to input.
+- `--space-gap-xl` **adapts** — Between the parts of a card, or between a heading and the block it introduces.
+- `--space-gap-xs` — Tightest gap between related elements, e.g. icon and label, inline text pairs.
+- `--space-grid-gutter` **adapts** — The space between two cards, across and down. One value on both axes, so a grid reads as an even field rather than as rows with a seam between them.
+- `--space-heading-content` **adapts** — Between a heading group and the content it introduces, stacked or side by side. Measured from the last part the group actually shows, so a section opens the same way whether or not every part is present.
+- `--space-heading-description-actions` — The step from a description down to what a reader can do about it. Twenty-four, which is the reference design's step on every opening band, and what the mobile override already said.
+- `--space-heading-eyebrow-title` **adapts** — Between an eyebrow and the title under it. The tightest step in the group, because an eyebrow reads as the title's first line rather than as a line of its own.
+- `--space-heading-title-description` — Between a display title and the description under it. Smaller than it looks: a title's leading and descender depth sit inside the gap, and both scale with the type, so a smaller title takes the compact step instead.
+- `--space-heading-title-description-compact` — The same step under a title that is not a display size — a card's, a panel's. Half the measure because the leading above it is half as deep, and what the eye reads is this plus that leading.
+- `--space-inset-2xl` **adapts** — The page's horizontal gutter, and the inset of a band that runs its full width.
+- `--space-inset-2xs` — Tight padding inside compact elements, e.g. badges, pills, tags.
+- `--space-inset-3xl` **adapts** — The vertical air around a hero or a full-bleed breaker. For the air a full-width section keeps above and below its own content use space.inset.4xl.
+- `--space-inset-4xl` **adapts** — The vertical air a full-width section keeps above and below its content. Two sections on the same ground share one step between them rather than each taking its own; a section with a fill of its own keeps the full step, its edge being what needs the air.
+- `--space-inset-card` **adapts** — The space between a card's edge and its contents. The one inset a page does not choose — a row of cards padded differently is a row of different cards.
+- `--space-inset-lg` — Padding inside content containers, e.g. feature cards, pricing cards, form containers.
+- `--space-inset-md` — Padding inside a row of a list — an accordion's heading, a table's cell, anything read by running an eye down a column. Between a control's inset and a container's, because a row is neither. The step the gap ramp already had here, so the two now agree.
+- `--space-inset-page` **adapts** — What holds a page's content off the edge of the window. Thirty-two on a desktop, sixteen below 768px — a phone has a third of the width and cannot spend that much of it on air. The tablet step sits between them and is the layout primitive's to hold.
+- `--space-inset-sm` — Default padding inside controls, e.g. form inputs, dropdowns, sign-up fields.
+- `--space-inset-xl` **adapts** — Padding inside a card or a panel — the step most cards want, between the tight lg and the page's own gutter.
+- `--space-inset-xs` — Padding inside compact controls, e.g. buttons, nav items, form chips.
+- `--space-section-compact` **adapts** — The air above and below a section of supporting content, or one closely related to the section before it. Where the default step would read as a break rather than a step.
+- `--space-section-default` **adapts** — The air above and below a section, and the step most take. Adjacent sections each contribute their own; nothing adds a gap between them on top of it.
+
+## size
+
+- `--size-avatar` — A person's picture beside their words — the author of a testimonial. Forty-eight, round: large enough to recognise a face, small enough to stay a signature under the quote rather than a portrait above it.
+- `--size-backdrop-blur` — How far a see-through surface blurs what is behind it, e.g. the navigation bar over the page it scrolls across. Enough that the words behind it stop reading as words, so the bar's own stay legible.
+- `--size-band-compact` — The least height an opening band takes when it is not a screen tall — a company, legal or support page, where a full viewport would be a wall before the first sentence. Deep enough that the band reads as a band rather than a gap the title fell into.
+- `--size-bar-height` — The height of a collapsed navigation bar, which both bars here take. Declared rather than left to what a page hands the bar: an action beside the mark would otherwise set it.
+- `--size-breakpoint-lg` — Where a bar has room for its destinations. A value to read, not a condition to write: `var()` is not allowed in a query, so the seven stylesheets that bend here still carry 64rem themselves.
+- `--size-breakpoint-md` — Where the phone's type layer stops — the mobile overrides resolve below it, so 767 is the last width that reads as a phone. A value to read, not a condition to write: `var()` is not allowed in a media query.
+- `--size-checkbox-box` — The square a checkbox ticks. Twenty, which is the mark's own size rather than the line's: the line is twenty-four here and a square that filled it read as a panel. What puts it on the line is an offset, not the measure.
+- `--size-content-max` — The widest the page's content runs, whatever the window does. Beyond it a line of body copy is longer than an eye tracks comfortably, so the content stops and the ground either side of it keeps going.
+- `--size-control-lg` — Height of a large control, for a hero or a conversion band. Twice space.control.lg, on the same reasoning as the default step.
+- `--size-control-md` — Height of a default-size control, the same measure product gives its own default. Twice space.control.md, so on a pill the corner radius and the side padding are one measure and a label starts where the curve stops.
+- `--size-control-sm` — Height of a small control — a picker in a navigation bar, a field in a filter row. Half of it is space.control.sm and a quarter is radius.control.sm, the ratio every step of this ramp holds. Desktop only: below what a finger reliably hits.
+- `--size-dot-current` — How wide the current mark in a row of dots stretches, against size.dot.diameter for the rest — a pill three dots long, so where the reader is reads by shape.
+- `--size-dot-diameter` — The mark standing in for one page of a short sequence, or for a status beside a name. Eight: small enough that a row of ten reads as a row rather than as ten controls, and large enough to find at arm's length.
+- `--size-grid-track-lg` — For a cell holding a picture as well as words, or a pricing plan with a list under it. Three fit the page's measure and four do not, which is what makes this the floor for a grid meant to read as three across.
+- `--size-grid-track-md` — The default track floor, for a feature card: a heading and a line or two beneath it. Four of these fit the page's measure, so a grid asking for three has room to spare and drops to two on a tablet rather than at the first sign of pressure.
+- `--size-grid-track-sm` — The narrowest a grid track goes before the grid drops a column. For a cell holding a logo, an icon and a word, or one short claim — six of them clear the page's measure with the page gutter still on both sides.
+- `--size-heading-group-max` — How wide an eyebrow, a title and a description may run as a block. Independent or centred groups take this; one that has to sit on the grid takes eight columns instead, which is a span rather than a measure.
+- `--size-logo-columns-height` — How much of a LogoColumns wall shows at once, from the fold. Tall enough that a column reads as running on past both edges; half of it on a phone.
+- `--size-logo-rows-tile` — The width of a tile on a LogoRows, from the fold; three quarters of it on a phone. Wide enough for a wordmark, narrow enough that a row shows several at once.
+- `--size-measure-description` — How wide a supporting description runs. Wider than a title because it is read rather than taken in, and narrower than long-form because it sits under something.
+- `--size-measure-heading` — The width a centred heading block is held to. Narrower than the page measure, because a title centred across the full 1280 is read from a different edge on every line.
+- `--size-measure-hero-description` — How wide the description under an opening band's title runs, e.g. in LandingHero, ProductHero, PageHeader. Wider than size.measure.description because it is set larger and read once, at the top.
+- `--size-measure-hero-heading` — The width the text column of a band that opens a page is held to, e.g. PageHeader's title and actions. Wider than size.measure.heading because a page's name is set at h1 and 846 breaks it early.
+- `--size-measure-long-form` — How wide running text runs. Past this the eye loses the line it was on when it returns to the left edge, which is the whole reason a measure exists.
+- `--size-measure-title` — How wide a title runs before it wraps. A starting point — eighteen to twenty-four after a look. `ch` is the width of the font's zero, so it is a measure rather than a letter count, and typed string because a Figma variable carries a number.
+- `--size-menu-panel-max` — The widest a section's menu panel gets. Narrower than the page's own measure on purpose: a panel is scanned across with a pointer already on it, and one as wide as the page leaves its last column a long way from the name that opened it.
+- `--size-menu-panel-min` — The shortest a section's menu panel gets, whatever it holds. A bar's sections rarely have the same number of destinations, and panels that each took their own height would change size as the reader moved along the row.
+- `--size-menu-max` — The tallest a menu's surface gets before its commands scroll. Product's measure, and counted in rows: five whole and part of a sixth at either size. Neither lands on a row boundary — a ceiling cutting clean at the last full row looks like the whole set.
+- `--size-review-card-min` — The shortest a TestimonialRow card gets. A floor, not a height: a one-line review keeps a card's shape, and a longer one still grows it.
+- `--size-rule-grid-pitch` — How often the rule grid repeats on a band that paints one. A pitch rather than a gap: it is how far apart a decorative line recurs, not the space between two things a reader is comparing.
+- `--size-sheet-handle-height` — The thickness of that handle. At the smallest step the scale has, because a grab bar is a hint that the sheet moves rather than a part of what it holds.
+- `--size-sheet-handle-width` — The width of the grab handle at the top of a BottomSheet. Wide enough to take hold of, narrow enough to read as a grip rather than as a rule across the sheet.
+- `--size-sheet-max` — The widest a BottomSheet gets before it stops growing and centres. A sheet is a small-screen pattern, and one running the width of a desktop is a dialog that arrived from the wrong edge.
+- `--size-sheet-peek` — How much of the page a tall BottomSheet leaves showing above it — enough to read as a layer over something rather than as a screen of its own.
+- `--size-spinner-stroke-lg` — Ring thickness at size lg. Slightly finer than the eighth the smaller steps take — at forty pixels the proportion that reads as solid at sixteen reads as a band, and the ring is the shape rather than the weight.
+- `--size-spinner-stroke-md` — Ring thickness at size md. Holds the same eighth as sm: a ring that kept one thickness across the sizes would look heavy at sixteen and drawn in hairline at forty.
+- `--size-spinner-stroke-sm` — Ring thickness at size sm. An eighth of the diameter, which is what keeps the arc reading as a stroke travelling rather than as a wedge turning.
+- `--size-spinner-lg` — Spinner diameter at size lg. For a section holding space for content that has not arrived — an embed, a demo, a band of live figures. Its job there is to be visible from where the reader is looking, which is the whole section rather than one control in it.
+- `--size-spinner-md` — Spinner diameter at size md. The default: large enough to be the one thing happening in a form or a card, small enough that it does not become the card's subject.
+- `--size-spinner-sm` — Spinner diameter at size sm. Sixteen, which is the size of the body copy it sits beside — an indicator in a line of text reads as part of the line rather than as something dropped into it.
+- `--size-switcher-panel-width` — The width of a switcher's floating panel. Stated because the panel is out of flow and would otherwise shrink to the trigger it hangs from, wrapping every choice and running the set down the page.
+- `--size-target-min` — The smallest a thing a pointer has to hit may be. Bind it as a minimum on any control whose size would otherwise come from its contents — a pressable card is as big as its words, and one holding a single short line is smaller than a fingertip.
+- `--size-testimonial-art` — The decorative pictures in a TestimonialSlider's corners, as squares. Large enough to read as pictures, small enough to leave the card the quote's.
+- `--size-tooltip-max` — The widest a tooltip gets before its text wraps. Short enough that the eye finds the start of the next line without hunting for it, which is the whole job of a measure — and a tooltip that needs more than two lines is a tooltip carrying something that belongs on the page.
+
+## radius
+
+- `--radius-container` — Large rounding for promotional containers — hero cards, callout sections. For standard content sections, use radius.surface.
+- `--radius-container-item` — The corner of a row inside a radius.container surface — the container's radius less the inset the row sits in, so the two curves are concentric rather than merely matched. Thirty-two less sixteen is sixteen, as radius.menu-item is twelve one step down.
+- `--radius-control-lg` — The corner of a large control. Twelve on forty-eight, the same quarter as the steps below it, so the curve reads the same at every size.
+- `--radius-control-md` — The corner of a default control: ten on a forty-pixel height, a quarter of it — the same corner Product draws. Marketing rounded these harder for a while, at sixteen; the surfaces still carry that softer reading, the controls no longer do.
+- `--radius-control-sm` — The corner of a small control. A quarter of its height, which is the ratio every step of this ramp holds.
+- `--radius-expressive` — The most rounding before full — for high-impact visual sections such as feature showcases and banners.
+- `--radius-menu` — The corner of a floating menu's panel. Tighter than radius.surface, which answers to a card sitting in the page: a menu is a control surface that has to nest a row, and its corner less the panel's inset is exactly radius.menu-item.
+- `--radius-menu-item` — The corner of a row inside a menu — radius.menu less the inset the row sits in, so the two curves are concentric and the first and last rows land on the panel's inside edge. Sixteen less four is twelve, which is product's own measure for the same row.
+- `--radius-none` — No rounding — sharp corners for editorial and structured layouts such as grids and dividers.
+- `--radius-pill` — Fully rounded ends for pill shapes and circular elements — buttons, chips, badges, toggles, CTAs.
+- `--radius-subtle` — Subtle rounding for small elements — tags, tooltips, notifications. Twelve rather than Product's eight, the same step up the rest of this ramp already takes: control 16 against 10, surface 24 against 16. This was the one step still matching Product's.
+- `--radius-surface` — A generous radius for content sections — feature cards, testimonial blocks, pricing cards. For larger promotional containers, use radius.container.
+- `--radius-surface-compact` — The corner of a surface too small for radius.surface's twenty-four — a card in a footer's rail. Not radius.container-item, which is sixteen for another reason: a container's corner less its inset.
+
+## border
+
+- `--border-style-decorative` — A dashed border for drag targets, upload zones, and placeholder areas.
+- `--border-style-default` — The standard border style. Use for all component outlines unless a dashed treatment is explicitly required.
+- `--border-width-default` — The standard border width for inputs, cards, and secondary buttons.
+- `--border-width-emphasis` — A rule one step heavier than the resting default, for an edge holding its own beside a filled neighbour. Between default and strong because the jump between those is a doubling: 1px disappears, 2px draws a box.
+- `--border-width-focus` — The width of a focus ring. Kept separate from strong so accessibility requirements can adjust it independently.
+- `--border-width-hairline` — The thinnest rule the system draws, for an outline that has to register without reading as a box — the ring a field puts outside its own border on focus. For an ordinary outline use border.width.default; a rule this thin disappears on anything larger than a control.
+- `--border-width-none` — Removes a border entirely. Use to reset a border in a variant without adding a layout shift.
+- `--border-width-strong` — A heavier border for selected and active states. Never use for ordinary outlines.
+- `--border-width-thick` — A bold border for progress bars, active tab indicators, and high-emphasis decorative treatments.
+
+## font
+
+- `font.body.lg` — The largest body step: an introductory paragraph under a headline, a hero description, a section intro. The same regular weight and line height as the rest of the ramp — body text set larger, rather than a different kind of text.
+  - `--font-body-lg-family`
+  - `--font-body-lg-letter-spacing`
+  - `--font-body-lg-line-height`
+  - `--font-body-lg-size`
+  - `--font-body-lg-weight`
+- `font.body.md` — Marketing body text, and the default: feature descriptions, article content, footer links. Sixteen pixels because that is what a browser sets before anybody asks.
+  - `--font-body-md-family`
+  - `--font-body-md-letter-spacing`
+  - `--font-body-md-line-height`
+  - `--font-body-md-size`
+  - `--font-body-md-weight`
+- `font.body.sm` — De-emphasised text: legal disclaimers, copyright lines, help text. Fourteen rather than twelve, marketing copy being read on a phone as often as not.
+  - `--font-body-sm-family`
+  - `--font-body-sm-letter-spacing`
+  - `--font-body-sm-line-height`
+  - `--font-body-sm-size`
+  - `--font-body-sm-weight`
+- `font.eyebrow.lg` — The line that leads into a display claim on an opening band, sized against the heading under it rather than against body text. Sentence case, unlike the small step: capitals are what make a twelve-pixel label a label, and at this size they shout.
+  - `--font-eyebrow-lg-family`
+  - `--font-eyebrow-lg-letter-spacing`
+  - `--font-eyebrow-lg-line-height`
+  - `--font-eyebrow-lg-size` **adapts**
+  - `--font-eyebrow-lg-weight`
+- `font.eyebrow.sm` — Uppercase category labels above a headline — section tags, plan badges, feature categories. Carries the size, weight and wide tracking that setting needs; the capitals are the component's, through text-transform, which leaves the accessible name in the case it was written.
+  - `--font-eyebrow-sm-family`
+  - `--font-eyebrow-sm-letter-spacing`
+  - `--font-eyebrow-sm-line-height`
+  - `--font-eyebrow-sm-size`
+  - `--font-eyebrow-sm-weight`
+- `font.field-label.lg` — The words naming a field in a large form, the step that pairs with a large control. Sized with the field it sits above, weighted like every other step of this role.
+  - `--font-field-label-lg-family`
+  - `--font-field-label-lg-letter-spacing`
+  - `--font-field-label-lg-line-height`
+  - `--font-field-label-lg-size`
+  - `--font-field-label-lg-weight`
+- `font.field-label.md` — The words naming a form field, sat above it — 'Email', 'Work address'. Medium where font.label is semibold: that role is text inside a control, and a field's name set at a button's weight competes with the button that submits the form.
+  - `--font-field-label-md-family`
+  - `--font-field-label-md-letter-spacing`
+  - `--font-field-label-md-line-height`
+  - `--font-field-label-md-size`
+  - `--font-field-label-md-weight`
+- `font.figure` — A number read as a fact rather than as a heading. It takes a heading's size, because a figure has to hold a row on its own, and semibold rather than extrabold: the weight a title needs makes a number look like a claim.
+  - `--font-figure-family`
+  - `--font-figure-letter-spacing`
+  - `--font-figure-line-height` **adapts**
+  - `--font-figure-size` **adapts**
+  - `--font-figure-weight`
+- `font.h1` — The largest heading marketing draws, for the line a landing page is built around. A size, not an instruction: heading level is document structure and this is scale.
+  - `--font-h1-family`
+  - `--font-h1-letter-spacing` **adapts**
+  - `--font-h1-line-height`
+  - `--font-h1-size` **adapts**
+  - `--font-h1-weight`
+- `font.h2` — A headline opening a major section of a long page. A size, not an instruction: heading level is document structure and this is scale.
+  - `--font-h2-family`
+  - `--font-h2-letter-spacing`
+  - `--font-h2-line-height` **adapts**
+  - `--font-h2-size` **adapts**
+  - `--font-h2-weight`
+- `font.h3` — A section heading under an h1 and h2. A size, not an instruction: heading level is document structure and this is scale.
+  - `--font-h3-family`
+  - `--font-h3-letter-spacing` **adapts**
+  - `--font-h3-line-height` **adapts**
+  - `--font-h3-size` **adapts**
+  - `--font-h3-weight`
+- `font.h4` — A subsection heading, and the first step down from the extrabold the larger headings carry. A size, not an instruction: heading level is document structure and this is scale.
+  - `--font-h4-family`
+  - `--font-h4-letter-spacing` **adapts**
+  - `--font-h4-line-height`
+  - `--font-h4-size` **adapts**
+  - `--font-h4-weight`
+- `font.h5` — The smallest heading marketing draws, for a label over a group of cards, a list or a short block of copy. A size, not an instruction: heading level is document structure and this is scale.
+  - `--font-h5-family`
+  - `--font-h5-letter-spacing`
+  - `--font-h5-line-height` **adapts**
+  - `--font-h5-size` **adapts**
+  - `--font-h5-weight`
+- `font.label-medium.sm` — Interactive text at the small step, set a weight lighter than font.label.sm. For a mark rather than a control — a badge is read as a word beside something, and semibold at fourteen reads as a button that has lost its ground.
+  - `--font-label-medium-sm-family`
+  - `--font-label-medium-sm-letter-spacing`
+  - `--font-label-medium-sm-line-height`
+  - `--font-label-medium-sm-size`
+  - `--font-label-medium-sm-weight`
+- `font.label.lg` — Interactive text given prominence: the call to action in a hero, the primary button on a landing page. The step above the default, and the only one worth reaching for when a control is the point of the section.
+  - `--font-label-lg-family`
+  - `--font-label-lg-letter-spacing`
+  - `--font-label-lg-line-height`
+  - `--font-label-lg-size`
+  - `--font-label-lg-weight`
+- `font.label.md` — Interactive text, and the default: navigation links, form labels, the call to action in a hero. One size for every control, large or small.
+  - `--font-label-md-family`
+  - `--font-label-md-letter-spacing`
+  - `--font-label-md-line-height`
+  - `--font-label-md-size`
+  - `--font-label-md-weight`
+- `font.label.sm` — Interactive text in a supporting position: footer links, a secondary action beside a primary one, a form's helper link. Small enough to sit under the default without competing with it.
+  - `--font-label-sm-family`
+  - `--font-label-sm-letter-spacing`
+  - `--font-label-sm-line-height`
+  - `--font-label-sm-size`
+  - `--font-label-sm-weight`
+- `font.subtitle` — Sub-section headers and secondary titles, e.g. pricing plan names, sub-feature group headers.
+  - `--font-subtitle-family`
+  - `--font-subtitle-letter-spacing`
+  - `--font-subtitle-line-height`
+  - `--font-subtitle-size`
+  - `--font-subtitle-weight`
+- `font.title` — The name of a thing the reader is inside rather than a section of a page — a sheet, a panel, whatever arrives over what they were doing. Bold at the smallest heading step, so it holds its own against content without competing with the page behind it.
+  - `--font-title-family`
+  - `--font-title-letter-spacing`
+  - `--font-title-line-height`
+  - `--font-title-size`
+  - `--font-title-weight`
+
+## icon
+
+- `--icon-control-lg` — The mark inside a large control. Four above font.label.md, on the same reasoning as the default step.
+- `--icon-control-md` — The mark inside a default-size control. Four above font.label.sm, so it clears the label's line box and reads at the label's weight rather than under it.
+- `--icon-control-sm` — The mark inside a small control. Two above font.label.sm rather than four: the label ramp stops at fourteen, so at this step the mark answers to the box instead of the type. Held at eighteen it would fill a thirty-two control rather than sit in it.
+- `--icon-size-2xs` — A mark inside a box that states its own size rather than beside text — a checkbox's tick in its twenty-pixel square, four pixels clear either side. Too small to carry meaning alone; the control around it is what is read.
+- `--icon-size-lg` — A larger icon for cards and content sections.
+- `--icon-size-md` — The default icon size for body content and lists.
+- `--icon-size-sm` — A mark beside text that must not outweigh it — the chevron on a list row, an affordance next to a label. Between the inline step and the default because sixteen goes unnoticed against anything larger than body copy, and twenty-four reads as bigger than the words it belongs to.
+- `--icon-size-xl` — The largest a system glyph is drawn here, for a callout or a highlighted block where the mark does as much work as the copy. The ramp stops rather than continuing: past this a 24-grid glyph is a diagram of itself, and what a page wants at that scale is an illustration.
+- `--icon-size-xs` — The smallest icon size for inline and supporting content.
+
+## elevation
+
+- `--elevation-edge-bottom` — A thin shadow cast downward from a top-anchored surface — top navigation, app bars. Indicates the surface sits above scrolling content.
+- `--elevation-edge-top` — A thin shadow cast upward from a bottom-anchored surface — bottom navigation, bottom sheets. Indicates the surface sits above scrolling content.
+- `--elevation-ring-hover` — The tint a field carries while the pointer is over it, drawn as a ring just inside its border. Bound to box-shadow rather than border-color so a hover does not overwrite what focus and the error status both put on that border.
+- `--elevation-surface-floating` — A surface floating above page content — dropdowns, tooltips, autocomplete lists. For surfaces that block interaction beneath them, use elevation.surface.overlay.
+- `--elevation-surface-modal` — The highest surface — modals, dialogs, full-screen drawers. Typically paired with a backdrop that dims the page beneath.
+- `--elevation-surface-overlay` — A surface floating above the page and blocking interaction beneath it — popovers, action sheets, menus. For full-screen takeovers with a backdrop, use elevation.surface.modal.
+- `--elevation-surface-raised` — A surface lifted just off the page — cards, list items. For sticky elements that persist while content scrolls beneath, use elevation.surface.sticky.
+- `--elevation-surface-sticky` — A surface pinned in place while content scrolls beneath it — sticky headers, sticky footers. Visually stronger than raised because it persists and must stay distinct from scrolling content.
+
+## layer
+
+- `--layer-overlay` — Something that interrupts the reader and takes the page with it — a bottom sheet, and whatever else arrives over everything rather than beside something. Above the popup role rather than level with it, so a menu opened inside one belongs over it.
+- `--layer-popup` — What a thing lifts to when it leaves the flow and floats over the page — a tooltip, and whatever menu or panel this package grows next. Above everything the page lays out, below anything that interrupts the reader.
+
+## motion
+
+- `--motion-distance-drift` — How far decoration travels against the scroll while its section passes through the view, one way or the other. Far enough to be seen moving as the reader scrolls past, so it reads as depth.
+- `--motion-duration-dramatic` — Editorial hero entrances for visual impact, e.g. hero headline revealing, landing page title appearing. Not for scroll reveals — use motion.duration.reveal.
+- `--motion-duration-dwell` — How long a rotating message holds before the next one moves in, e.g. a CTA banner's slides. Long enough to read a headline and a line under it; the reference site's 2000 moved before a reader reached the button.
+- `--motion-duration-fast` — Direct user actions that should feel instant, e.g. hover, press, toggle.
+- `--motion-duration-instant` — A change the reader has already moved past — a tooltip leaving once the pointer is elsewhere. Not a short duration but no duration: animating a dismissal keeps a thing on screen after the reason for it has gone.
+- `--motion-duration-media-hover` — How long art takes to settle inside a frame that holds still. Longer than duration.normal, which suits a card that lifts and is over; a picture that zooms is still on screen when it stops and the eye follows it the whole way.
+- `--motion-duration-normal` — UI elements entering or leaving, e.g. dropdowns, tooltips, tab switches, card hover.
+- `--motion-duration-pulse` — One full pulse cycle for a status indicator. Slow enough to be subtle, fast enough to notice — and long enough that a row of them does not read as flicker.
+- `--motion-duration-reveal` — Content appearing on scroll, e.g. section reveals, feature items fading in, trust stats appearing. Not for hero text — use motion.duration.dramatic.
+- `--motion-duration-shift` — A surface rearranging itself between two resting states on the reader's scroll — a navigation bar gathering, and ungathering on the way back. Longer than a UI element entering, because nobody asked for it.
+- `--motion-duration-slow` — Large UI transitions, e.g. accordions expanding, page transitions, interactive demos.
+- `--motion-duration-spinner` — One full rotation of a spinner. Fast enough to read as working, slow enough that the stroke does not blur into a solid ring.
+- `--motion-duration-stagger` — The step between one part of a section arriving and the next. A gap rather than a length: five parts at this step trail the first by less than half a second, so a block still arrives as one thing rather than assembling itself while a reader waits.
+- `--motion-easing-enter` — UI elements arriving on screen — decelerates into place, e.g. dropdown opening, tooltip appearing.
+- `--motion-easing-exit` — UI elements leaving the screen — accelerates away, e.g. menu closing, notification dismissing.
+- `--motion-easing-media-hover` — Art moving inside a frame that holds still. Symmetric, unlike easing.standard: a hover runs forward on enter and backward on leave, so a one-way curve that settles hard reads as a snap going one way and a drift the other.
+- `--motion-easing-reveal` — Scroll reveals and hero entrances — arrives fast then settles slowly. Stronger deceleration than easing.enter for dramatic effect.
+- `--motion-easing-shift` — Symmetric, for a change that runs both ways: a bar gathering on scroll and ungathering on the way back should read the same in each direction, which easing.standard cannot do.
+- `--motion-easing-spinner` — Constant-speed rotation for a spinner. Linear because a loop is the one case with no arrival to ease into — any acceleration lands a seam at the point the animation restarts, and the eye finds it on the second turn.
+- `--motion-easing-standard` — Default easing for anything moving within the viewport. Use this unless the element is specifically entering, exiting, or revealing.
+- `--motion-scale-band-exit` — How far an opening band draws back as it scrolls out. Its own role rather than motion.scale.enter, which is named for something arriving.
+- `--motion-scale-enter` — What a component scales from when something reveals it — a tooltip appearing. Needs a transform origin on the edge nearest its anchor, or it grows out of its own middle. The counterpart to scale.hover, which is a response rather than an entrance.
+- `--motion-scale-hover` — How much a control grows under the cursor on hover. Deliberately small — a control that grows past the pointer fires its own mouse-out.
+- `--motion-scale-media-hover` — How much art grows inside a frame that holds still — an editorial card's picture under the cursor. Twice motion.scale.hover, which stays smaller because a control can outrun its own pointer and a framed picture cannot.
+- `--motion-translate-enter` — Where a surface waits before something reveals it: level on the inline axis, its own full height down the block one. A share of the element rather than of the page, so a sheet travels exactly its own height whatever that turns out to be.
+- `--motion-translate-hover` — How far a pressable surface rises under the cursor. A fixed distance rather than a share of the element, so a tall card and a short one lift by the same amount and a row of them stays level. Small enough that nothing it sits beside looks disturbed.
+- `--motion-translate-reveal` — How far a section waits below where it lands, before the scroll brings it up. A fixed distance rather than a share of the block, so a hero a screen tall and a split half that arrive by the same movement. Pairs with motion.easing.reveal.
+
+## opacity
+
+- `--opacity-disabled` — How far a control recedes when it is unavailable. Applied to the control as a whole rather than re-colouring its parts, so what is inside keeps its relationships and the whole thing reads as one unavailable object.
+- `--opacity-dot-current` — The position in a row of dots that the reader is on — the ground's own ink at full strength, stretched into a pill so the current one is told apart by shape as well as by weight.
+- `--opacity-dot-rest` — The positions in a row of dots that the reader is not on, e.g. a slider's other slides. Drawn in the ground's own ink at forty-eight, so the row reads on any band without a colour of its own.
+- `--opacity-hidden` — What a component fades from when something reveals it. Not a dimming treatment — something unavailable or quiet says so in its own colour role, where the contrast checker can see it. The first entry in a group this package had left empty.
+- `--opacity-muted` — A mark at rest, before a pointer reaches it. For artwork that carries its own colours and so cannot be quietened by an ink role — a brand logo, a partner mark — where every other quiet thing in this system says so in colour.
+- `--opacity-track` — How far a track recedes behind the thing travelling over it. Both are drawn in one colour, so this alpha is the only thing separating them — which is why it is a ratio and not a colour role.