@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/cardbutton.md

@@ -0,0 +1,259 @@
+<!-- GENERATED from card-button.contract.json. Do not edit. -->
+
+# CardButton
+
+A card that responds to a press. The whole surface is the target — a feature and where it leads, a market and its page, a plan and what it costs — so pressing anywhere on it does the thing, and what the thing is decides the element: an `<a>` when it is given an href, a `<button>` when it is not. One component rather than two, because a card that goes to a page and a card that opens something are the same gesture with different destinations, and the element is what tells a browser which.
+
+## Use when
+
+- The whole card is the target rather than a link buried in it — a grid of features each leading to its own page, a set of markets, a row of plans
+- Pressing it goes somewhere with a URL of its own. Pass href and the browser's own navigation works: cmd-click opens a tab, the status bar shows the destination, the link can be copied and it can be crawled
+- Pressing it opens something the page owns rather than leaving the page — a dialog, a video, a step in a sign-up
+
+## Do not use
+
+- The card holds a control of its own as well → `Card`
+- Nothing happens when it is pressed → `Card`
+- A card containing a button, a link or a field. Every one of them is unreachable inside a button or an anchor, and the rule about it is the one rule in this system that cannot live on any single component
+- An href to somewhere that does not exist. Given one this becomes a real anchor, so the destination has to be a place a reader could bookmark — an action dressed as a destination sends them nowhere and offers to open it in a tab
+- A whole section of the page. A card stands for something else and points at it; a surface wrapping an entire band with an href on it is a page linking to itself
+- Making a card feel lively. The lift under the pointer is what a control looks like, and putting it on something that does nothing teaches a reader that movement means nothing
+
+## Anatomy
+
+CardButton renders one element.
+
+- `root` — `<button>`, class `dds-cardbutton`. The surface, and the target. An `<a>` when given an href and a `<button>` when not, because a card that goes to a page and a card that opens a dialog are the same gesture and the element is what tells a browser which — one answers Space, the other answers cmd-click.
+  
+  Everything Card's surface does, it does: the four grounds, the corner, `overflow: hidden` so a picture meets that corner, and no inset of its own. What it adds is that the whole of it is one target, and what it gives up is holding a control of its own.
+  
+  It sets its own colour rather than letting it inherit, which the anchor makes necessary: a `<button>` takes the text colour around it and an `<a>` does not — it takes the browser's link blue, and every word in the card goes with it. So each ground names its ink here, exactly as Card does, and CardBody's regions inherit that.
+  
+  The response to a pointer is movement rather than colour, and that is not a stylistic preference — it is the only thing that works on all four grounds at once. There is one hover fill in this package and it is a five-percent black: it darkens a white card, does almost nothing to the coral, and is invisible on the near-black. A movement says the same thing on every ground.
+  
+  It rises rather than grows. A scale is what Product's card does and it was the first thing tried here, but it enlarges the type and the picture along with the surface, so the card is momentarily a different size from its neighbours in a row and the copy inside it is momentarily a different size from the copy beside it. A lift moves the whole card as one object and changes nothing about what is in it.
+  
+  `motion.translate.hover` is a fixed distance rather than a share of the element, which matters for a card more than for most things: cards in a row are rarely the same height, and a proportional lift would raise the tall one further than the short one and break the line they sit on. Nothing reflows either way — a translate is painted, not laid out — so the cards around it do not move.
+  
+  It takes `motion.duration.normal` to get there, which the scale reads oddly until you look at what each step is for: `fast` is the one named for hover, and it is named for the hover of a control that has somewhere to be — a toggle flipping, a button darkening. `normal` names card hover in as many words, because a card is a large object and a large object crossing a short distance in a hundred milliseconds does not read as rising, it reads as flicking. The distance is small enough that the extra hundred is still well inside the time a pointer rests.
+  
+  `easing.standard` rather than `enter`, which is a distinction the scale is explicit about: `enter` is for something arriving on screen and this is already here, moving in place.
+  
+  It lifts and does not give. There is no pressed state here on purpose: a return distance would be a second token, and a card that dipped under the press would be answering a question nobody has asked of this package yet.
+  
+  And a floor in both directions, which being a control rather than a box is what makes necessary. A card is as big as what is in it, and what is in it is usually plenty — but nothing guarantees it, and a card holding one short line is a target smaller than the pad of a finger. `size.target.min` costs nothing to a card that is already bigger and catches the one that is not.
+  
+  It holds one child. The wildcard beside `CardBody` in `allowedChildren` is older than that: it was there for a picture reaching the card's edges while the copy stayed inset, which was a second child until CardMedia folded into the body and became `src`. What the wildcard still buys is content that is not a body at all — a chart, a band of art — and there is still only ever one of it. Two bodies in one card is two padded stacks with a seam down the middle, which is a page composing a section rather than a card holding one. And a pressable card is one target: two of anything inside it asks which of them the press belonged to.
+  
+  `plain` gives up three things the other four keep, and they are one decision rather than three: the fill, the corner that shape needs, and the lift. A filled card rises on hover as one object because it is one object — a ground with a corner, sitting on the page. Take the ground away and what is left to rise is a picture and some loose text, which reads as the words sliding rather than as a card lifting. So the translate is bound per variant on the four that have a fill, and the editorial card answers the pointer through its picture instead, with CardBody's `zoomOnHover`. The focus ring is unconditional and stays: the lift was decoration, and that is not.
+  
+  There is a second rule beside that one, and the two are independent. This one is about the ground; the other is about the motion already present — a card whose body zooms does not lift either, whatever its fill, because two movements answering one hover read as a glitch rather than as emphasis. That rule cannot be bound: its condition is CardBody's prop, one level down, and neither a token binding nor a structural rule can name another component's axis. It is in the impl sheet as a `:has()` on this root, which reads the child without styling it — so an editorial card on `surface` keeps its fill and its corner and still holds still while its picture moves.
+
+Apply these classes from the generated `cardButtonParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: any content
+- Never contains: `Card`, `CardButton`, `Breadcrumb`, `BreadcrumbItem` — in children or in any prop that takes a node
+- Holds at least 1 and at most 1
+
+## Props
+
+### variant — `surface` | `surface-raised` | `accent` | `accent-strong` | `plain` (default `surface`)
+
+- `surface` — The default, and right for a pressable card on the page. The same recessed step off the white page that Card takes, so a row mixing pressable and plain cards reads as one row
+- `surface-raised` — The card sits on a color.bg.subtle band rather than on the page, where the recessed fill all but disappears and this one lifts off the band instead
+- `accent` — One card in a set is the promotional one and the page has already earned the colour
+- `accent-strong` — A card carrying more weight than its neighbours. The darkest of the four, and the one that takes white at 20.55:1 — the most legible ground a marketing card has
+- `plain` — An editorial card that goes somewhere — an article, a post, a release note. No fill, no corner and no lift: what marks it out is its picture and the gap to the next one, the way a column of articles is told apart on a page rather than the way a row of tiles is. The same ground Card's own plain variant takes, so a pressable article card and a static one sit in one column without a seam
+
+### href — `string`
+
+Use when: The press goes somewhere with a URL of its own. It makes this an anchor rather than a button, which is what gives a reader cmd-click, a visible destination and a copyable link — none of which mean anything for a press that opens a dialog. This is the ordinary case on a marketing page, where most cards point at a page
+Never for: A press the page handles itself. An anchor with an href nothing can navigate to is a promise the browser will try to keep
+
+Also accepts everything from `ButtonHTMLAttributes<HTMLButtonElement>`.
+
+## 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: `button`
+- `Tab` — move focus. One stop, on the card itself, because the card is the target — there is nothing inside it that takes focus, which is what forbidding controls in it buys
+- `Enter` — press it. A button and an anchor both answer Enter, so this reads the same either way
+- `Space` — press it, where it is a button. An anchor does not answer Space, and that difference belongs to the element rather than to this component — a reader who knows the difference is told which by how it was announced
+- What the card is for is readable from its own words. A card announced as a link or a button with nothing in it but a picture has no accessible name, so the title inside it is what names it — which is why the body's title is a heading rather than a styled line.
+- Nothing inside it takes focus. A button, a link or a field within this is unreachable to a keyboard and ambiguous to a pointer, and a card needing both a press and its own control is a Card with the control inside it.
+
+## 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
+
+❌ CardButton for: The card holds a control of its own as well
+   A button inside a button, or inside an anchor, is what no-nested-interactive refuses — and a card with its own 'Get started' in it is exactly that. Use a Card and put the control inside it: the card is then a box holding something pressable rather than being it
+   → use `Card` instead.
+
+❌ CardButton for: Nothing happens when it is pressed
+   This takes focus, sits in the tab order and announces itself as a control. A card that merely wants a hover flourish and does nothing is a trap for anybody moving through the page by keyboard, who arrives somewhere that will not answer them
+   → use `Card` instead.
+
+❌ variant=plain + state=hover
+   The editorial card does not move under the cursor, and this is the declaration of that rather than an omission. The other four variants lift, which works because each is one object — a ground with a corner, sitting on the page. plain has no ground, so what would rise is a picture and some loose text, and that reads as the words sliding rather than as a card lifting.
+
+What answers the pointer instead is the picture, through CardBody's zoomOnHover, and it has to live there because the picture is that component's part. Bound here as a no-op — scale at motion.scale.none — it would have been worse than nothing: a rule of the same specificity as the four lifts, later in the file, ranked by the cascade for no reason. Focus is untouched and stays unconditional: the lift was decoration and the ring is not.
+
+This covers plain alone. A filled variant whose body zooms also stops lifting, but that is not an unbound cell — the binding is there and a `:has()` rule in the impl sheet overrides it, which is why it needs no exemption here.
+
+## Example
+
+```tsx
+import { CardButton, CardBody } from '@deriv-com/dds-marketing'
+
+<CardButton href="/markets/forex">
+  <CardBody title="Forex" description="Trade the world's most liquid market, around the clock." />
+</CardButton>
+```
+
+## In use
+
+### The element follows the destination
+
+href decides what this is. An anchor gives cmd-click, a visible destination and a copyable link; a button answers Space and does what the page says. One gesture, two destinations.
+
+```tsx
+import { CardBody, CardButton } from '@deriv-com/dds-marketing'
+
+// With href — an anchor, and a real destination
+<CardButton href="/markets/forex">
+  <CardBody title="Forex" description="Trade the world's most liquid market." />
+</CardButton>
+
+// Without href — a button the page handles
+<CardButton>
+  <CardBody title="Watch the tour" description="Two minutes on how the platform works." />
+</CardButton>
+```
+
+### The four grounds, all pressable
+
+The same grounds Card offers, so a row mixing pressable and plain cards reads as one row. The response to a pointer is movement rather than colour, which is the only thing that works on all four.
+
+```tsx
+import { CardBody, CardButton } from '@deriv-com/dds-marketing'
+
+// surface — on the page
+<CardButton variant="surface" href="/markets">
+  <CardBody title="Tight spreads" description="Competitive pricing on every market." />
+</CardButton>
+
+// surface-raised — on a subtle band
+<CardButton variant="surface-raised" href="/markets/indices">
+  <CardBody title="Indices" description="Track the world’s major markets in one place." />
+</CardButton>
+
+// accent — the promotional one
+<CardButton variant="accent" href="/signup">
+  <CardBody title="Open an account" description="It takes about three minutes." />
+</CardButton>
+
+// accent-strong — carrying more weight
+<CardButton variant="accent-strong" href="/pro">
+  <CardBody title="Deriv Pro" description="Institutional pricing and dedicated support." />
+</CardButton>
+```
+
+### A picture that answers the pointer
+
+The card clips, so the picture grows inside its frame rather than spilling. The root lifts and the picture lifts with it, so the picture moves about twice as far — one token, compounded.
+
+```tsx
+import { CardBody, CardButton } from '@deriv-com/dds-marketing'
+
+// Hover it — the picture pushes into the crop
+<CardButton href="/markets/commodities">
+  <CardBody title="Commodities" description="Gold, oil and more, with tight spreads." src="/sample-card-image.svg" alt="" />
+</CardButton>
+```
+
+### It zooms instead of lifting
+
+An editorial card zooms its picture and does not lift, on any ground. CardButton drops its own lift whenever the body it holds zooms — one motion per gesture, whichever variant is under it.
+
+```tsx
+import { CardBody, CardButton } from '@deriv-com/dds-marketing'
+
+// plain — no ground to lift; the picture moves
+<CardButton variant="plain" href="/news/banking-hall">
+  <CardBody flush zoomOnHover src="/sample-card-image.svg" alt="The entrance to a bank, seen from street level." mediaPosition="above" aspect={1.7777777777777777} eyebrow="14 August 2026" title="A bank can bank your IPO and still refuse your account" />
+</CardButton>
+
+// surface — a fill, and still no lift while it zooms
+<CardButton variant="surface" href="/news/banking-hall">
+  <CardBody zoomOnHover src="/sample-card-image.svg" alt="The entrance to a bank, seen from street level." mediaPosition="above" aspect={1.7777777777777777} eyebrow="14 August 2026" title="A bank can bank your IPO and still refuse your account" />
+</CardButton>
+```

package/.llm/components/checkbox.md

@@ -0,0 +1,285 @@
+<!-- GENERATED from checkbox.contract.json. Do not edit. -->
+
+# Checkbox
+
+Records a single on-or-off choice that is submitted with the form around it rather than applied the moment it is ticked.
+
+## Use when
+
+- A choice the user makes now and confirms later — the form's Save or Continue is what applies it
+- Agreeing to something before proceeding — terms, a risk disclosure, a confirmation the user must actively give
+- One of several independent choices, each of which can be on or off without affecting the others
+
+## Do not use
+
+- Choosing exactly one option from a short set, where picking one unpicks the others → `SegmentedControl`
+- Performing an action rather than recording a choice → `Button`
+- A setting that takes effect the moment it is ticked. A checkbox is a value the form around it submits, and one that applied immediately would misreport itself — the reader looks for Save, finds nothing waiting, and cannot tell whether the change took. Marketing has no immediate-apply toggle to send them to
+- Destructive or irreversible changes — a checkbox is a value in a form, and a tick is not a confirmation step
+- A choice the user cannot see the label of. The label is required and always rendered: a bare box states nothing about what ticking it agrees to
+
+## Anatomy
+
+Checkbox renders 9 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-checkbox`. The whole control: the row a pointer aims at, and whatever the field has to report under it. A column rather than the row it used to be — the status message is about the field and not about its words, so it starts where the box starts instead of indenting to the label, which is where a set would put its own. Carries the tone, checked, status and disabled attributes, which is what lets every part below respond to them. Its structural keywords are the contract's own staticCss rather than a part-level one, which is where the root's always belong.
+- `control` — `<div>`, class `dds-checkbox__control`. The row a pointer aims at: the box and the words that name it. Named `control` for the same reason TextInput's box is — it is the part a reader operates, as against the message about it. Where the box sits against those words is the one thing about this part the contract does not decide: it is aligned to the start of the cross axis here, which is right when the label wrapped, and checkbox-impl.css centres it instead when there is a description, which is right when the second line belongs to the first. That rule needs to ask whether a part exists, which a token binding cannot, and it says so in its own header.
+- `box` — `<span>`, class `dds-checkbox__box`. The square the user sees, and the only part that reports the state — its fill, its border and what sits inside it. A span rather than the input itself because the tick has to live inside the box, and an <input> is void: it can hold no child. The positioning context for the field that covers it. Its corner is radius.control.sm where product's is radius.subtle, and the difference is the role rather than the decision: marketing's subtle step is twelve where product's is eight, deliberately, so the rest of its ramp sits a step above. Twelve on a twenty-pixel square is past half its width, which draws the box as a circle — a checkbox shaped like a radio button. Eight is the only step this ramp has below half, and the box is a control, which is what that role names. Retuning subtle instead would have moved breadcrumb, link and tooltip for one box. Its unticked fill is color.bg.surface-raised, where product's box paints color.bg.transparent and lets whatever contains it show through. Both answer the same question — a box has to be told apart from the surface under it — and this package answers it with the white raised ground, because its surface is the grey one a card is recessed into.
+- `field` — `<input>`, class `dds-checkbox__field`. The real control — a native checkbox, covering the box exactly and invisible over it. Invisible rather than absent: this is what submits with the form, what the keyboard reaches, what carries the native indeterminate property, and what :focus-visible and :disabled are answered from. Every state the box and the label draw is read off this element through :has().
+- `indicator` — `<span>`, class `dds-checkbox__indicator`. What the box says: a tick when checked, a dash when indeterminate, nothing when neither. Takes its colour from a binding here rather than from the glyph, so the shape and what colours it stay separate. Decorative to a screen reader — the input's own state already announces it, and hearing both says it twice.
+- `text` — `<div>`, class `dds-checkbox__text`. Stacks the label and whatever is said under it. An element of its own because the root lays the box beside the words in a row, and a description added without it would be a third item in that row rather than a second line under the label. Rendered even with nothing to stack, so the box meets the same box either way and a checkbox does not shift sideways the moment it gains a second line. No gap between the two lines, deliberately: body.md and body.sm both carry a line-height above one, so the half-leading either side of them already separates the label from the description, and a space.gap.xs on top of that read as more room than the space.gap.sm between one control and the next.
+- `label` — `<label>`, class `dds-checkbox__label`. States what ticking the box agrees to. Always rendered — a checkbox whose label is optional is a checkbox that ships bare. Tied to the field by htmlFor, which is what makes the text itself a target: the box on its own is a small square, and the words beside it are most of what a user actually aims at.
+  
+  It can be clipped rather than removed, and the difference is the whole of why the prop is not called `label: false`. A box that summarises a set is the case: the select-all in a table's header sits over a column of boxes and takes its meaning from the column, so drawing "Select all" beside it puts body-sized words in a row of column names — a control shouting where the names are eleven pixels. Clipped, the name is still there for anyone who cannot see the column, which is the half that matters.
+- `description-text` — `<span>`, class `dds-checkbox__description-text`. What ticking the box commits the user to, under the label it belongs to. Quieter than the label and smaller, so a column of checkboxes still scans as a list of choices rather than as a list of paragraphs. Named as the field's description rather than as part of its label, because a screen reader should reach it after the thing it qualifies rather than folded into its name. Rendered only when `description` is set.
+- `message` — `<span>`, class `dds-checkbox__message`. The glyph for the status and what the status means, in the colour of the status. The glyph takes that colour from the text beside it rather than binding one, and is decorative to a screen reader because the words say the same thing — its shape is what separates an error from a warning for a reader who cannot tell those two colours apart. Sits under the whole control rather than inside the words, so it lines up with the box rather than with the words — it reports on the field, and a message indented to the label read as a third line of the label. Stacks under the description rather than replacing it: a description says what ticking the box commits you to and a message says what is wrong with the answer, so they are not two ways of filling one slot. A success status may be silent — the contract requires a message only for an error or a warning. Rendered only when `status` is set.
+
+Apply these classes from the generated `checkboxParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `Button`, `TextInput` — in children or in any prop that takes a node
+
+## Props
+
+### tone — `standard` | `accent` (default `standard`)
+
+- `standard` — The default, and almost always right — the ticked box fills with the neutral that outranks everything around it, so the choice is legible before any colour is read and it is the fill every other chosen control in this package takes, which is what lets a form of them read as one set of answers
+- `accent` — The checkbox is the brand moment of the view — a single consent the design is deliberately drawing the eye to — and the surrounding design already carries brand red
+
+### checked — `unchecked` | `checked` | `indeterminate` (default `unchecked`)
+
+- `unchecked` — The default — the choice has not been made, or has been made against
+- `checked` — The user has made this choice, or it arrives pre-made and they may change it
+- `indeterminate` — A box that summarises others, where some but not all of them are ticked — a Select all above a partly selected list
+Never for: A pending or loading state. Indeterminate means partly chosen, not not-yet-known, and a user who ticks it expects the group to follow
+
+### status — `none` | `error` | `warning` | `success` (default `none`)
+
+- `none` — The default — the choice has not been judged, or it passed and there is nothing to say
+- `error` — The box had to be ticked and was not, or what ticking it asks for is not accepted
+- `warning` — The choice is accepted but has a consequence the user should see before submitting
+- `success` — The choice was checked against something and passed, and confirming that is worth the room
+Never for: A box in a set where something above it already asks the question and reports the error. The message answers for the whole set, and a box repeating it states the same failure twice. This prop is for the box that stands alone, which is the case a group cannot cover: a single consent has nothing above it to carry the error. Also never for guidance shown before the user has answered, which is what description is for
+
+### label — `string` **Required.**
+
+Use when: Always — it states what ticking the box agrees to, and the box shows nothing on its own. A phrase the user can read as a claim they are agreeing with: "Send me trade confirmations", not "Confirmations". Sentence case, and no full stop — a label is a phrase rather than a sentence, and a stop at the end of one reads as the start of prose. In a set, phrase every box the same way, so a reader compares the answers rather than the grammar
+Never for: The consequence or the rule, which belongs beside the form rather than inside the choice — a label that explains has stopped naming the thing being agreed to, and there is a description for what it was trying to say. Never phrased as an opt-out either: ticking a box means yes, so "Do not send me email" makes a ticked box a double negative and leaves the user working out which way round it is
+
+### showLabel — `boolean` (default `true`)
+
+Use when: Drawing the words, which is nearly always. A checkbox on its own is a question, and a question with no words is not one
+Never for: Deciding whether the box has a label. It always has one and it is always announced — this only says whether the label is drawn. Off is clipped, not removed, so a screen reader still reads it
+
+### description — `string`
+
+Use when: Ticking the box commits the user to something the label cannot carry without becoming a sentence — what it costs, how often it happens, what it applies to. On a box that summarises others it is where the summary belongs: "Four of six are on" says what an indeterminate tick cannot
+Never for: Guidance about the form as a whole, or the rule behind the choice, which belongs beside the form rather than under one of its controls. A note repeated under every box is describing the set, and putting it on one of them says it is true of that one only
+
+### statusMessage — `string` **Required when status=error, or when status=warning.**
+
+Use when: Whenever the status is an error or a warning — the words are what the user acts on, and the colour alone is not available to everyone
+Never for: Restating the label. The message says what happened and what to do, not what the choice was
+
+Also accepts everything from `InputHTMLAttributes<HTMLInputElement>`.
+
+## States
+
+States you set. Everything else is driven by the browser.
+
+- `disabled` — The choice cannot be made from here — a term the user's account has already accepted, or an option their plan does not offer
+  Avoid when: The choice is merely unticked, which is what the unchecked state is for
+
+## 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: `checkbox`
+- `Space` — toggle
+- `Tab` — move focus
+- a programmatically associated label
+- the mixed state carried on the input's native indeterminate property, never as aria-checked="mixed". A native checkbox already announces mixed from that property; a second declaration can desync from it and override it. Not verifiable in a DOM here — indeterminate is a property rather than an attribute, so nothing in the tree records it
+- aria-describedby pointing at the description, so what ticking the box commits the user to is heard after the choice rather than folded into its name
+- aria-invalid on the field while the status is an error, so a reader is told the box is the problem rather than only shown it in red
+
+## 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
+
+❌ Checkbox for: Choosing exactly one option from a short set, where picking one unpicks the others
+   Checkboxes are independent by construction — nothing about a row of them says only one may be on, and enforcing it in the consumer's handler leaves the control lying about what it allows. The row is for two to four alternatives shown at once; a longer set of exclusive choices has no control here yet
+   → use `SegmentedControl` instead.
+
+❌ Checkbox for: Performing an action rather than recording a choice
+   A checkbox describes a value the form will carry; an action that happens on press is a button
+   → use `Button` instead.
+
+❌ status=error + statusMessage missing or empty
+   An error with no explanation leaves the user stuck
+
+❌ status=warning + statusMessage missing or empty
+   A warning with no explanation is a choice the user cannot act on
+
+## Example
+
+```tsx
+import { Checkbox } from '@deriv-com/dds-marketing'
+
+<Checkbox label="Send me product updates and market insights" checked="unchecked" />
+```
+
+```tsx
+import { useState } from 'react'
+import { Checkbox } from '@deriv-com/dds-marketing'
+
+// Controlled: Checkbox reports the DOM event, so the value is read off it.
+// Unlike AmountInput and SearchInput, which declare an onChange that hands back the
+// value itself — the two shapes look the same at the call site and are not.
+const [value, setValue] = useState('')
+<Checkbox label="Send me product updates and market insights" checked="unchecked" value={value} onChange={(event) => setValue(event.target.value)} />
+```
+
+## In use
+
+### States
+
+The three values a checkbox can hold. Indeterminate is not a choice the reader picks — it is what a summary box shows when the boxes under it disagree.
+
+```tsx
+import { Checkbox } from '@deriv-com/dds-marketing'
+
+// Not chosen
+<Checkbox label="Send me product updates and market insights" checked="unchecked" />
+
+// Chosen
+<Checkbox label="Send me product updates and market insights" checked="checked" />
+
+// Summarising a partly chosen group
+<Checkbox label="All email preferences" checked="indeterminate" description="Three of the five below are on" />
+```
+
+### What ticking it commits you to
+
+A description carries what the label cannot without becoming a sentence — how often something arrives, or what it applies to.
+
+```tsx
+import { Checkbox } from '@deriv-com/dds-marketing'
+
+// The choice, and how often it acts
+<Checkbox label="Send me product updates" description="About one a month, unsubscribe any time" checked="checked" />
+
+// Described, and not on offer
+<Checkbox label="Send me updates by SMS" description="Not available in your region" checked="unchecked" disabled />
+```
+
+### A consent that has to be given
+
+The case a lone box owns and a group cannot: there is nothing above it to carry the error, so the box reports its own.
+
+```tsx
+import { Checkbox } from '@deriv-com/dds-marketing'
+
+// Submitted without the consent, and told so
+<Checkbox label="I accept the Terms of Use and the Privacy Policy" checked="unchecked" status="error" statusMessage="Accept the terms to create your account" />
+
+// Given, with a consequence worth seeing
+<Checkbox label="Share my activity with partner sites" checked="checked" status="warning" statusMessage="Partners may contact you about their own products" />
+
+// Checked against something, and it passed
+<Checkbox label="I accept the Terms of Use and the Privacy Policy" checked="checked" status="success" statusMessage="Consent recorded" />
+```
+
+### Tone
+
+Standard suits every form. Accent is for the one box a page is deliberately drawing the eye to, and is worth spending once rather than down a column.
+
+```tsx
+import { Checkbox } from '@deriv-com/dds-marketing'
+
+// Standard, the default
+<Checkbox label="Send me product updates and market insights" checked="checked" />
+
+// Accent, for a deliberate brand moment
+<Checkbox label="I accept the Terms of Use and the Privacy Policy" checked="checked" tone="accent" />
+```
+
+### Unavailable
+
+A choice that cannot be made from here. Disabled says the control is inert — not that the answer is no, which is what an unticked box says.
+
+```tsx
+import { Checkbox } from '@deriv-com/dds-marketing'
+
+// Already given, and not withdrawable here
+<Checkbox label="I accept the Terms of Use and the Privacy Policy" checked="checked" disabled />
+
+// Not offered in this region
+<Checkbox label="Send me updates by SMS" checked="unchecked" disabled />
+```