@deriv-com/dds-marketing 0.1.0 → 1.0.0

package/.llm/components/spinner.md

@@ -0,0 +1,230 @@
+<!-- GENERATED from spinner.contract.json. Do not edit. -->
+
+# Spinner
+
+A turning ring that says a wait is real and the page has not stalled. A marketing page has very little to wait for — it is copy and pictures, and they arrive with the page — so a spinner here is the exception rather than the furniture: a form that has just been submitted, an embed or a demo still loading, a band of live figures being fetched.
+
+That rarity is the brief. In an app a spinner is ordinary and a reader waits because they have an account and a reason to; on a landing page it is shown to someone with no stake in the outcome and nothing keeping them there. So it appears where a wait has already started — after the reader did something, or where a section has visibly held space for something that has not come — and nowhere else.
+
+## Use when
+
+- The reader has just submitted something — a signup, a contact request — and the page owes them a sign that it is working
+- A section is holding space for content that arrives separately: an embed, a demo, a band of live figures
+- Something the reader asked for is on its way and nobody can say how long it will take
+
+## Do not use
+
+- The wait is the page's own first load → nothing here does this
+- How much is done is known, or could be → nothing here does this
+- A wait short enough that the ring is a flash. A spinner that appears and goes inside a few hundred milliseconds reads as a glitch in the page rather than as work being done, and the reader is left with the flicker rather than the result
+- More than one in a view. Three rings turning in three cards is a page that looks broken rather than busy — one spinner for the thing being waited on, at the level the reader is looking
+- Decoration. A ring turning in a hero because the section looked static is motion with nothing behind it, and it teaches a reader that a spinner on this site does not mean a wait
+- Standing in for content whose shape is already known. A ring in the middle of a section says nothing about what is coming and holds no room for it, so the layout jumps when it arrives — space the content will fill is better held by the space itself
+
+## Anatomy
+
+Spinner renders 4 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-spinner`. The container, and the thing that carries the accessible name when there is one. `inline-flex` in a column with the items centred: the circle, and the label beneath it when there is a label to draw.
+  
+  A column rather than a row, and there is no orientation to choose. The label is off by default and the cases that show one are standalone — a section or a form waiting — where the words sit under the ring and the pair reads as one centred block. A spinner beside a line of text is the other case, and it is better served by omitting the label entirely and letting the sentence already on the page say what is loading.
+- `circle` — `<svg>`, class `dds-spinner__circle`. The turning ring. Its shapes carry `vector-effect: non-scaling-stroke`, which is what makes the stroke-width tokens mean rendered pixels rather than viewBox units — without it one token would draw a different thickness at every size, right at one of them and wrong at the rest.
+  
+  It takes the colour and the size — a fill role rather than an ink one, because the ring is a drawn shape and not text, and the fg roles are darkened to carry contrast as words; the rotation is in `spinner-impl.css`, because a keyframed loop is not something a contract can hold. It reads `--motion-duration-spinner` and `--motion-easing-spinner` straight from the built stylesheet: the token build emits every semantic role whether a contract binds it or not, so binding them here bought two `transition-*` declarations on an element that never transitions. That file also stops it under `prefers-reduced-motion`, where the ring stands still and the arc alone still marks the component as present.
+- `track` — `<circle>`, class `dds-spinner__track`. The faint full ring the arc travels over. Drawn in the same colour as the arc, so the only thing separating them is its alpha — which is why it is a part rather than an attribute: `stroke-opacity` inherits, so bound on the svg it would fade the arc along with it and leave a ring with nothing moving on it.
+- `label` — `<span>`, class `dds-spinner__label`. What is loading, in words. Rendered whenever a label is given, and hidden visually rather than dropped when `showLabel` is false — `role="status"` is a live region and a live region with no name is one that fires with nothing to say.
+  
+  Absent with no label, rather than present and empty: the span exists to carry the name, and with no name to carry it is a flex item holding a gap open under the ring.
+  
+  Its family is bound rather than inherited. A component that does not bind one takes whatever the page sets, and a marketing page sets a great many things — the ratified stack governs nothing it does not already happen to get. Rendered only when `label` is set.
+
+Apply these classes from the generated `spinnerParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+
+## Props
+
+### size — `sm` | `md` | `lg` (default `md`)
+
+- `sm` — In a line of body copy, or inside a control the reader has just pressed. Sixteen, the size of the words beside it, so it sits on the line rather than in front of it
+- `md` — The default. A form that has been submitted, a card waiting on the figure it is going to show
+- `lg` — A section holding space for something that arrives separately — an embed, a demo, a band of live figures. Sized to be found from where the reader is looking, which is the whole section rather than one control in it
+
+### variant — `accent` | `neutral` | `inherit` (default `accent`)
+
+- `accent` — The default, and what a page nearly always wants. The wait is the one thing happening, and the brand colour is what says the page is doing it rather than failing to
+- `neutral` — The wait is incidental to what the reader came for — a figure refreshing inside a card that is otherwise readable. Brand colour on a wait nobody is watching spends attention the page needs further down
+- `inherit` — Inside something that has already set a colour: a filled button, a dark band, a coloured panel. `currentColor` reaches the ring and the label together.
+
+This is also how a spinner on a dark section or a photograph gets its colour. There is no fixed-light or fixed-dark role in this package, and adding one would be asking a second time a question the section has already answered by setting its text colour
+Never for: Marking one wait as more important than another. Two spinners in a view is the thing to fix; recolouring one of them is not
+
+### label — `string` **Required when showLabel=true.**
+
+Use when: Naming what is loading, for a spinner that stands on its own — a section, a form, a button whose own words have been replaced by it. Without it the spinner is decorative and says so properly: no role, no name, hidden from a screen reader outright
+Never for: A second voice for something the page has already said. A ring beside a line reading “Sending your details” is not a separate thing loading, and naming it makes a screen reader announce the wait twice. Omitting it is what that case is for — an empty string is not, because an unnamed live region is still a live region and it still fires
+
+### showLabel — `boolean` (default `false`)
+
+Use when: The words should be drawn as well as announced — beneath the ring, for a section or a form where the reader can see the wait but not what it is for
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- Announced as: `status`
+- accessible name from label
+- A spinner with no label carries no role either. Decorative is a real mode here rather than an oversight — aria-hidden, no live region, nothing announced — and it is the right one wherever the copy beside the ring already names the wait.
+
+## Rules
+
+- **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.
+
+## Anti-examples
+
+❌ Spinner for: The wait is the page's own first load
+   Nothing here does this, and the useful thing is knowing why. A landing page that opens on a spinner has replaced its first impression with a placeholder — the reader has not asked for anything yet, so there is no wait they are party to, only a page that is not ready. That is a build and delivery problem, and a ring turning in the middle of it makes it look deliberate.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ Spinner for: How much is done is known, or could be
+   Nothing in this package shows progress yet, and a spinner is not a stand-in for it: a ring turning says only that something is happening, which is the right answer when it is the true one and a worse one than a bar whenever a share of the work can be named.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ showLabel=true + label missing or empty
+   A label shown on screen with no text in it is a gap held open under the ring, and a centred block that is no longer centred on anything
+
+## Example
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+<Spinner label="Sending your details" showLabel />
+```
+
+## In use
+
+### Three sizes, three places
+
+The size follows what the reader is looking at when the wait starts — a line of copy, a form, or a whole section holding space.
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+// sm — in a line of body copy, or in a control just pressed
+<Spinner size="sm" label="Checking that address" />
+
+// md — the default: a form that has just been submitted
+<Spinner size="md" label="Sending your details" />
+
+// lg — a section holding space for an embed or live figures
+<Spinner size="lg" label="Loading live spreads" />
+```
+
+### Three colours, and the one that borrows
+
+Brand says the page is working on what the reader asked for. Neutral is a wait nobody is watching. Inherit takes currentColor, which is how a ring gets its colour on a filled button or a dark band.
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+// accent — the default, and the wait the page owes the reader
+<Spinner variant="accent" label="Sending your details" />
+
+// neutral — a figure refreshing in a readable card
+<Spinner variant="neutral" label="Refreshing prices" />
+
+// inherit — inside something that has already set a colour
+<Spinner variant="inherit" label="Sending your details" />
+```
+
+### Named, drawn, or neither
+
+A standalone spinner has to name itself, and showLabel decides only whether the words are drawn. Omitting the label is the third mode: no role, nothing announced.
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+// Named and announced, not drawn — the default
+<Spinner label="Sending your details" />
+
+// Drawn as well — the wait is visible, its reason is not
+<Spinner label="Loading live spreads" showLabel size="lg" />
+
+// Neither — decorative, beside copy that names the wait
+<Spinner />
+```

package/.llm/components/stack.md

@@ -0,0 +1,342 @@
+<!-- GENERATED from stack.contract.json. Do not edit. -->
+
+# Stack
+
+A column, and one measure between its rows. It draws nothing — no ground, no edge, no padding — and owns one decision: how far apart the things stacked in it sit. Everything else about them stays theirs.
+
+It exists because the measure is what pages get wrong, and get wrong quietly. A gap typed as a number agreed with the system on the day it was written and never again. A gap written as a margin on the row belongs to the row, and travels with it into the next layout, where it is wrong and where nobody thinks to look — the last row of every group carrying a measure into whatever follows it. The column is the one thing that can see both sides of the space, so the column is what should own it.
+
+On a marketing page the rhythm is the argument. A hero, a proof, a price and an ask are read in order and at a pace the spacing sets, and a page whose steps are picked one at a time reads as a list of things that happened to be put on a page. The ramp is what makes that pace a decision rather than an accumulation.
+
+## Use when
+
+- Two or more things are read down the page in order and the space between them is the same the whole way down — an eyebrow, a headline and a line of copy; the points of a feature list; the rows of a plan
+- The spacing is a fact about the group rather than about any member of it. Set here, every row agrees; set on the rows, the group is only as consistent as the last person to add one
+- The measure should tighten on a phone without anyone writing a breakpoint. The top three steps of this ramp already do, so a column set at one of them is narrower below 768px and nothing about the page says so
+
+## Do not use
+
+- The things sit beside one another rather than one above the next → `Row`
+- The things must line up across as well as down → `Grid`
+- The set has to stay on one line and the reader moves along it → `Scroller`
+- Padding. It sets space between its children and none at all around them, so a stack reached for to inset a section leaves the band that should have carried the padding with none — and the inset now lives on an element that has no ground to sit on
+- A single child. A column of one has nothing to space: the gap is inert, and what is left is an element that renders, costs a node, and explains nothing to the next person to read it
+- Reaching a width. It is as wide as whatever holds it and declares no size of its own. A page's measure is a decision about the page, and a stack used to constrain one is a width hidden inside a spacing decision, in the one place nobody will search for it
+- Putting one thing in a particular place. The gap is a relationship between rows, not a distance from an edge — a measure picked because it lands something where it looks right is a position written in the wrong units, and it is wrong at the next width and on the next screen
+- Separating sections that a ground already separates. A band with a fill of its own has an edge, and an edge is the separation; a large gap on top of it is the page saying the same thing twice and the reader reading a hole
+
+## Anatomy
+
+Stack renders one element.
+
+- `root` — `<div>`, class `dds-stack`. The column, and the whole of what this component is. It paints nothing, holds no corner and takes no padding: an arrangement is not a surface, and one that brought a ground of its own would be a second surface inside whatever it was put in.
+  
+  A flex column rather than a block with margins, because the gap has to be a property of the container for the rows to be interchangeable. Written as margins, the measure lives on the rows, the first or the last carries one nobody wanted, and reordering the group changes the spacing — three faults with one cause. It also means adjacent margins cannot collapse into one another, which is the oldest way for a page's rhythm to come out smaller than the sum of its parts with nothing in the source to show for it.
+  
+  Its inline size is whatever contains it, and it declares none. What it does declare is `min-inline-size: 0`, which looks like nothing and is the difference between a stack that shrinks and one that does not: a flex item refuses to go below its content's intrinsic width, so a column holding a long unbroken string — a URL, an email address, a product name nobody hyphenated — placed inside a row would push its container wider rather than wrapping, and the overflow surfaces somewhere else entirely.
+  
+  The gap is the one token binding here, and the top three steps of this package's ramp are redefined below 768px. That is the whole of this component's responsiveness and it is inherited rather than declared: the column asks for a role, the role is narrower on a phone, and no breakpoint is written here. A page wanting a different pace on a phone changes the token, not the column.
+
+Apply these classes from the generated `stackParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: any content
+
+## Props
+
+### gap — `none` | `xs` | `sm` | `md` | `lg` | `xl` | `2xl` | `3xl` (default `md`)
+
+- `none` — No gap at all, for rows 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
+- `xs` — The tightest gap between related elements — an eyebrow and the headline under it, a figure and the caption beneath
+- `sm` — The default step for sibling controls, and what the token names for a form label and the input under it
+- `md` — The default, and what the token names for stacked items: form fields, feature list items, pricing features. Reach for this unless the column has a reason to be tighter or looser
+- `lg` — Between content groups — feature cards, footer columns, one pricing plan and the next
+- `xl` — Between the parts of a card, or between a heading and the block it introduces. Drops one step below 768px, a phone having a third of the width to spend
+- `2xl` — Between one section of a page and the next. Drops one step below 768px, a phone having a third of the width to spend
+- `3xl` — The largest gap, for separating whole movements of a long page. Drops one step below 768px, a phone having a third of the width to spend
+
+Use when: Always. The measure between rows is the component's one decision and the reason it exists, so there is no case for leaving it unstated
+Never for: Reaching a distance. The gap is a relationship between two rows rather than a measure from anything — a step picked because it puts something where it looks right is a position written in the wrong units, and it is wrong at the next width
+
+### align — `start` | `center` | `end` | `stretch` (default `stretch`)
+
+- `start` — Rows keep their own width and sit against the leading edge — a column of links, or a call to action as wide as its own label
+- `center` — Rows keep their own width and are centred — a hero's copy, a closing block, anything read as one object on a ground wider than it
+- `end` — Rows keep their own width and sit against the trailing edge, which on a page is rare and usually means the column is in a panel rather than in the flow
+- `stretch` — The default. Every row takes the column's full width, which is what stacked cards, fields and bands want, and what makes their edges agree down the page
+
+Use when: How wide the rows are, and where they sit across the column. The default is the common case and the one that keeps a stacked set looking like a set
+Never for: Centring the words inside a row. This moves the row and not its contents — a paragraph centred by setting the column to `center` is also a paragraph shrunk to the width of its longest line, which is a different thing and rarely the wanted one. Centred text is `text-align` on the text
+
+### justify — `start` | `center` | `end` | `between` (default `start`)
+
+- `start` — The default. Rows sit at the top, and a column with no height of its own is exactly as tall as they are
+- `center` — Rows sit together in the middle of a column that is taller than they are — a card in a row of cards whose copy is shorter than its neighbours'
+- `end` — Rows sit at the foot of a column taller than they are
+- `between` — The first row at the top, the last at the foot, and whatever room is spare shared between them — the shape a pricing card takes, where the price is at the top and the button has to sit on the same line as every other card's
+
+Use when: Where the rows sit down a column that has more height than they need. On a page that is usually a card in a row of cards, stretched to its tallest neighbour
+Never for: Making a column taller. This shares out height the column already has; where the column is sized by its own contents there is no room to share, and every value here draws exactly the same thing — which is the failure this prop has, silent and easy to spend an afternoon on
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Choosing a variant
+
+Placement in, props out. When one of these describes what you are building, take
+its props — do not re-derive them from the variant descriptions above.
+
+- **An eyebrow, a headline and a line of copy at the top of a section** — `gap="xs"`
+  Three lines that read as one block. The tightest step is what says the headline belongs to the eyebrow rather than following it
+- **The points of a feature list, one under the next** — `gap="md"`
+  The default step, and the one the token names for stacked items. Every point agrees without any point being asked
+- **The sections of a long page, stacked** — `gap="2xl"`
+  Between one section and the next, and it tightens a step below 768px on its own — a phone having a third of the width to spend, and the same air reading as a hole
+- **A closing block — one line and one call to action, centred on a wide ground** — `gap="lg"` `align="center"`
+  The rows keep their own width and sit in the middle, so the button is as wide as its label rather than as wide as the band. Stretched, one action reads as a bar
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- the column announces nothing of its own. It is an arrangement, and an arrangement is not something a reader needs told — what is inside carries the meaning, and each row keeps whatever name or role it would have had anywhere else
+- a run of things of a kind is marked as one somewhere other than here. Spacing is not structure: six cards in a column are announced as six unrelated things however tightly they sit, and the markup around them is what says otherwise
+- the order the rows are written in is the order they are read in. Nothing here reorders anything, and nothing here should be made to — a column whose visual order and DOM order disagree is read in one order and seen in another
+
+## Rules
+
+- **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.
+
+## Anti-examples
+
+❌ Stack for: The things sit beside one another rather than one above the next
+   A line and a column are different questions, and the props that answer them differ — a row wraps, and aligns to a baseline, neither of which means anything down a column
+   → use `Row` instead.
+
+❌ Stack for: The things must line up across as well as down
+   A column gives every row the full width and no row any relation to the one beside it, there being none. A set of cards that must agree in both directions is tracks, and a stack that looks like a grid at one width stops being one at the next
+   → use `Grid` instead.
+
+❌ Stack for: The set has to stay on one line and the reader moves along it
+   That is the third answer to a row that has run out of room, and it carries the snapping and the tab stop that make the rail reachable. A column never has the problem
+   → use `Scroller` instead.
+
+## Example
+
+```tsx
+import { Stack, Typography } from '@deriv-com/dds-marketing'
+
+<Stack gap="xs">
+  <Typography variant="eyebrow">Why Deriv</Typography>
+  <Typography variant="h2" as="h2">Trade the markets you already follow</Typography>
+  <Typography variant="body-lg">Over 200 instruments, one account, and no minimum to begin.</Typography>
+</Stack>
+```
+
+## In use
+
+### What it is for
+
+Things read down the page with one measure between them. On a page the rhythm is the argument, and the column is what sets its pace.
+
+```tsx
+import { Stack, Typography } from '@deriv-com/dds-marketing'
+
+// An eyebrow, a headline, a line
+<Stack gap="xs">
+  <Typography variant="eyebrow">Why Deriv</Typography>
+  <Typography variant="h2" as="h2">Trade the markets you already follow</Typography>
+  <Typography variant="body-lg">Over 200 instruments, one account, and no minimum to begin.</Typography>
+</Stack>
+```
+
+### Every step between rows
+
+The same two lines at each step. Nothing about the words changes — the measure decides whether the second reads as part of the first, beside it, or long after it.
+
+```tsx
+import { Stack, Typography } from '@deriv-com/dds-marketing'
+
+// none — rows carry their own
+<Stack gap="none">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+
+// xs — two lines that read as one
+<Stack gap="xs">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+
+// sm — a label and the field under it
+<Stack gap="sm">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+
+// md — the default — stacked peers
+<Stack gap="md">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+
+// lg — content groups
+<Stack gap="lg">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+
+// xl — parts of a card — tightens on a phone
+<Stack gap="xl">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+
+// 2xl — one section to the next — tightens
+<Stack gap="2xl">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+
+// 3xl — whole movements — tightens
+<Stack gap="3xl">
+  <Typography variant="h4" as="h3">Regulated in six jurisdictions</Typography>
+  <Typography variant="body-md">Client funds are held in segregated accounts.</Typography>
+</Stack>
+```
+
+### How wide the rows are
+
+The default stretches every row to the column's width. The other three let each row be as wide as its own contents — the shape a hero's copy or a closing block takes.
+
+```tsx
+import { Button, Stack, Typography } from '@deriv-com/dds-marketing'
+
+// stretch — the default — every row the full width
+<Stack gap="sm" align="stretch">
+  <Typography variant="body-md">Open an account in minutes.</Typography>
+  <Button variant="primary">Get started</Button>
+</Stack>
+
+// start — each row its own width, leading
+<Stack gap="sm" align="start">
+  <Typography variant="body-md">Open an account in minutes.</Typography>
+  <Button variant="primary">Get started</Button>
+</Stack>
+
+// center — each row its own width, centred
+<Stack gap="sm" align="center">
+  <Typography variant="body-md">Open an account in minutes.</Typography>
+  <Button variant="primary">Get started</Button>
+</Stack>
+
+// end — each row its own width, trailing
+<Stack gap="sm" align="end">
+  <Typography variant="body-md">Open an account in minutes.</Typography>
+  <Button variant="primary">Get started</Button>
+</Stack>
+```
+
+### Where the rows sit
+
+Only bites where something has given the column a height — a card stretched to its tallest neighbour. Nothing here has, so all four draw identically.
+
+```tsx
+import { Button, Stack, Typography } from '@deriv-com/dds-marketing'
+
+// start — rows at the top
+<Stack gap="sm" justify="start">
+  <Typography variant="h4" as="h3">Standard</Typography>
+  <Button variant="secondary">Choose plan</Button>
+</Stack>
+
+// center — rows in the middle
+<Stack gap="sm" justify="center">
+  <Typography variant="h4" as="h3">Standard</Typography>
+  <Button variant="secondary">Choose plan</Button>
+</Stack>
+
+// end — rows at the foot
+<Stack gap="sm" justify="end">
+  <Typography variant="h4" as="h3">Standard</Typography>
+  <Button variant="secondary">Choose plan</Button>
+</Stack>
+
+// between — first at top, last at foot
+<Stack gap="sm" justify="between">
+  <Typography variant="h4" as="h3">Standard</Typography>
+  <Button variant="secondary">Choose plan</Button>
+</Stack>
+```