@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/stack.md

@@ -0,0 +1,334 @@
+<!-- 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.
+
+## 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>
+```

package/.llm/components/statusdot.md

@@ -0,0 +1,205 @@
+<!-- GENERATED from status-dot.contract.json. Do not edit. -->
+
+# StatusDot
+
+A small coloured circle that marks one thing in a list of otherwise equal things — either because it is worth noticing, or because it is in a state the others are not. The accent one draws attention and says nothing about a condition; the four beside it each name one. It never carries the meaning on its own: the words next to it do, because a colour is not readable to everyone who has to read it.
+
+## Use when
+
+- Marking something the page is pointing at — a plan that is new, a feature worth finding in a list of them. That is the accent one, and on a marketing page it is most of them
+- Showing presence or availability alongside a name
+- Indicating system health or severity in a compact space, where a word for each would cost more room than the difference is worth
+
+## Do not use
+
+- The status needs a text label inside a colored pill → `Badge`
+- Conveying status without an adjacent text label — color alone is not accessible
+- A bullet, or a mark that means nothing at all — use plain CSS or a list element. The accent variant is not the exception it looks like: it says the page is pointing at this one rather than the others, which is a meaning. A dot on every row in a list means nothing by saying it everywhere
+- Carrying the meaning in tooltip alone — a description that has to be pointed at is absent on touch and to anyone reading the page rather than exploring it. The adjacent text label is what says what the state is; the tooltip only says more about it
+
+## Anatomy
+
+StatusDot renders one element.
+
+- `root` — `<span>`, class `dds-statusdot`. The colored circle. Carries the variant and optional pulse animation, and the description when it has one.
+
+Apply these classes from the generated `statusDotParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+
+## Props
+
+### variant — `accent` | `success` | `warning` | `error` | `info` (default `accent`)
+
+- `accent` — A mark in the brand colour, for something worth noticing that is not a state — a feature that is new, an item the page is pointing at. It is the default because most dots on a marketing page are drawing attention rather than reporting a condition, which is the opposite of the balance an application view has.
+- `success` — Available, online, healthy, or passing
+- `warning` — Away, degraded, or approaching a limit
+- `error` — Busy, offline, failed, or critical
+- `info` — In progress, syncing, or informational
+Never for: And never as a neutral or unknown state. This variant says the brand is pointing at something; it does not say a condition is unknown, and there is no longer a dot that does — the four that remain each name a condition, and a mark that reports nothing at all is text or a Badge rather than a dot.
+
+### pulse — `boolean` (default `false`)
+
+Use when: The status is live or actively changing — draws attention to an ongoing state
+
+### label — `string` **Required when tooltip is set.**
+
+Use when: The rare dot that stands alone. Ordinarily leave this out: the contract asks for a visible text label beside every dot, and that text is what says what the state is — so a dot naming itself as well is heard twice, "Status, Online". Set it where the words beside the dot do not name the state, and the contract insists on it wherever tooltip is set
+Never for: Repeating the words already beside it, which is what makes a screen reader say the state twice. Nor for the explanation, which is tooltip. There is deliberately no default: a generic name would satisfy this without anybody choosing it, and it did — every unconfigured dot announced the word "Status" beside text that already said the state
+
+### tooltip — `string`
+
+Use when: The state has a meaning the colour and the adjacent label together still do not explain — why a service is degraded, what "away" counts as. A few words, revealed on hover and on keyboard focus
+Never for: A sentence the reader must have, or anything longer than a phrase. Setting this puts the dot in the tab order, because a description no keyboard can reach is one this system does not ship — so a tooltip on every dot in a list of twenty is twenty new tab stops, and worth spending only where the explanation is
+
+Also accepts everything from `HTMLAttributes<HTMLSpanElement>`.
+
+## 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.
+
+- `Tab` — Reaches the dot, but only while it carries a tooltip — a dot with nothing to describe is not a stop
+- `Escape` — Dismisses the tooltip, and does not reveal it again until focus leaves and returns
+- no role and no name of its own, unless label is set. The colour is the mark and the words beside it are the meaning, which the contract requires anyway — so the dot is hidden from a screen reader rather than repeating them. It carried role="status" and a name defaulting to "Status", which made every dot a live region announcing a word that says nothing.
+- an accessible name from label wherever label is set, since that is the case where the dot is carrying the state itself
+- aria-describedby pointing at the tooltip that explains the state, set whether the chip is revealed or not
+- focusable while it carries a tooltip, so the description is not one only a pointer can reach — and named, because a stop with no name is announced as nothing
+
+## 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.
+
+## Anti-examples
+
+❌ StatusDot for: The status needs a text label inside a colored pill
+   A badge carries its own label — a dot relies on surrounding text
+   → use `Badge` instead.
+
+❌ tooltip is set + label missing or empty
+   A tooltip puts the dot in the tab order, so that it can be reached by something other than a pointer. A focusable thing with no accessible name is announced as nothing at all — the reader arrives somewhere and is told only that they have arrived.
+
+## Example
+
+```tsx
+import { StatusDot } from '@deriv-com/dds-marketing'
+
+<StatusDot variant="success" />
+```
+
+## In use
+
+### What the colour says
+
+One mark for attention and four for a condition. The dot never carries the meaning alone — the words beside it do, which is why it is hidden from a screen reader unless nothing else says it.
+
+```tsx
+import { StatusDot } from '@deriv-com/dds-marketing'
+
+// Accent — the brand pointing at something
+<StatusDot />
+
+// Success — available, healthy, connected
+<StatusDot variant="success" />
+
+// Warning — degraded, and still working
+<StatusDot variant="warning" />
+
+// Error — down, or failing
+<StatusDot variant="error" />
+
+// Info — a state worth marking, not judging
+<StatusDot variant="info" />
+```
+
+### Beating, for something live
+
+A pulse says the state is being watched right now — a stream that is connected, a check that is running. On a dot that will not change it is motion for its own sake.
+
+```tsx
+import { StatusDot } from '@deriv-com/dds-marketing'
+
+// Still — the ordinary case
+<StatusDot variant="success" />
+
+// Pulsing — a live connection
+<StatusDot variant="success" pulse />
+```
+
+### When the dot has to name itself
+
+Ordinarily it does not: the text beside it is the meaning, and a dot repeating it is heard twice. Two cases need a name — one standing alone, and any dot with a tooltip.
+
+```tsx
+import { StatusDot } from '@deriv-com/dds-marketing'
+
+// Named, because a tooltip makes it a tab stop
+<StatusDot variant="warning" label="Degraded" tooltip="Order routing is slower than usual" />
+
+// Named, standing where no words say the state
+<StatusDot variant="error" label="Disconnected" />
+```