@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/selectchip.md

@@ -0,0 +1,334 @@
+<!-- GENERATED from select-chip.contract.json. Do not edit. -->
+
+# SelectChip
+
+A chip that opens a list of answers and keeps the one chosen, so a filter row shows the current narrowing rather than the name of a filter. On a marketing site that is the control above an index whose set is too long to spell out as a row of toggles — a language, a region, a sort order, a market.
+
+## Use when
+
+- A row narrows an index by one value out of a set, and has to keep showing which value that is
+- The set is short enough to scan rather than search — a region, a language, a sort order
+- The row has no space for a form field: nothing above the control, nothing beneath it, only the answer
+
+## Do not use
+
+- Pressing an item does something rather than answering something → `DropdownMenu`
+- The chip answers on its own, or the set is short enough for every answer to sit in the row as a chip of its own → `FilterChip`
+- Each answer is a page with its own address → `Link`
+- Running commands. Nothing here is performed — the list holds answers, and a reader who reopens it finds the one they gave still marked
+- A form field. There is no label row, no helper and no status, so a control that must be explained or validated has nowhere to say it
+- More than one answer at once. One chip carries one value; a set of narrowings that stack is a row of FilterChips
+
+## Anatomy
+
+SelectChip renders 6 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-selectchip`. Holds the chip and the list, and nothing else. `position: relative`, which is what the list is absolute against — so it is pinned to the chip that opened it and travels with it rather than with the page. Inline, because a chip sits in a row of other chips: a block root would take the width of whatever contains it and put the chip alone on a line.
+- `trigger` — `<button>`, class `dds-selectchip__trigger`. The chip itself, and the only thing pressed. A button inside the root rather than the root being one, because the list is a sibling that has to be positioned against something — and a button containing its own popup is a control inside a control. It says a list opens and whether it is open, which a chevron says to the eye and to nobody else. Whether anything has been chosen is this control's own to know rather than a prop it is handed, so it travels as a state on this element instead of an axis on the root: the answer comes from the value, and a prop beside it could disagree with it. At rest it wears the same white ground and hairline edge a FilterChip does, and once an answer is in it, the same dark ground a chosen FilterChip takes — the two say the same thing and should not say it two ways.
+- `trigger-icon` — `<span>`, class `dds-selectchip__trigger-icon`. A glyph before the words, naming the kind of narrowing. Its own part because a Quill glyph ships width and height attributes on the svg and only a rule on that element overrides them. Rendered only when `leadingIcon` is set.
+- `trigger-label` — `<span>`, class `dds-selectchip__trigger-label`. What is being narrowed by, and what is chosen where anything is. The value belongs here rather than in a second slot: a token reading "Sort: Newest" is one thing to read, and a name beside a separate value is two. It truncates rather than wrapping, because a chip is one line in a row of them. Its figures are tabular: a chip carrying a number — a year, a count — is one whose words change while the row around it stays put, and proportional digits are not the same width, so a 1 becoming a 2 would resize the chip and shift every chip after it.
+- `chevron` — `<svg>`, class `dds-selectchip__chevron`. The chevron that says a list is behind this. Always drawn, and that is the whole promise the component makes: a chip without one is a toggle, and one that showed a chevron and opened nothing would teach the reader not to trust the row. It turns while the list is open, which is the same fact aria-expanded carries for a reader who cannot see it. Drawn through Icon rather than sized here — a Quill glyph ships width and height attributes, and only a rule on that element beats them. The step it takes is the chip's own, the same one its leading glyph takes, so the two ends of a chip are one size.
+- `listbox` — `<ul>`, class `dds-selectchip__listbox`. The answers on offer. One element carrying the fill, the corner, the shadow, the inset and the ceiling before it scrolls. It takes the same surface a DropdownMenu takes in this package — same corner, same inset, same shadow — because two floating lists that differ by a few pixels read as a mistake rather than as a distinction. Announced as a listbox, which is what tells a reader these are things to choose between rather than things to do, and what makes the arrow keys mean what they mean. Absent when shut rather than hidden, so nothing beneath it is covered by something nobody can see and no answer is reachable by a reader running past a shut chip. As wide as its longest answer with the chip's width as a floor: this list is a different object from the chip that opened it, and an answer reading "Most recent first" cannot be cut to fit a chip reading "Sort". One edge is pinned and the other let go, and which one is the alignment axis. It always opens downwards — a chip near the foot of the screen should open upwards instead, and nothing here does that yet, the same gap DropdownMenu has. It is not a prop: which side a list opens on is a fact about the room left below the chip at that moment, which a page cannot assert and cannot keep true through a scroll. Rendered only when `open` is set.
+
+Apply these classes from the generated `selectChipParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `Option`
+- Never contains: `Button`, `Link`, `TextInput`, `MenuItem`, `FilterChip`, `SelectChip` — in children or in any prop that takes a node
+
+## Props
+
+### disabled — `boolean` (default `false`)
+
+Use when: The narrowing cannot be made just now — the set is empty, or the index it governs has not loaded. It dims and leaves the tab order
+Never for: The reader could act on it if they knew what to change. This says the choice is closed and nothing about why, so a reason belongs in the prose around the row
+
+### size — `sm` | `md` (default `sm`)
+
+- `sm` — The default, and the same measure a FilterChip takes at its own default, so a row holding both sits level
+- `md` — A touch-first layout, or a filter row in a hero band where the chips carry more weight
+
+Use when: How dense the row is, matched to whatever it sits beside. The chip takes the size and the list it opens follows, so a reader never meets rows from one size under a chip from another
+Never for: Marking one chip in a row as more important. They are a set of equals and a row of mismatched heights reads as a mistake before it reads as emphasis
+
+### alignment — `start` | `end` (default `start`)
+
+- `start` — The list's leading edge lines up with the chip's. The default, because a reader reads from that edge and the answers begin where the chip's own words began
+- `end` — Its trailing edge lines up instead, for a chip near the end of a row where a list opening the other way would run off the screen
+
+Use when: Which edge the list is pinned to. The other edge is let go, so the list is as wide as its longest answer with the chip's width as a floor.
+Never for: Nudging the list into place a few pixels. It names an edge to line up, not an offset
+
+### label — `string` **Required.**
+
+Use when: Always, and required on that account — it names what is being chosen, and it is what the chip shows until something has been. Short enough to read at a glance in a row of other chips
+Never for: Describing what pressing it does. The chip names the narrowing, and what happens is that a list opens
+
+### value — `string`
+
+Use when: The page owns the answer — it arrives from a URL, is shared with something else on screen, or has to survive the chip unmounting. Passed, this is the answer, and onChange is the only way it moves
+Never for: Seeding a first answer and then leaving it alone. That is defaultValue, and passing this instead gives a chip that cannot be changed
+
+### defaultValue — `string`
+
+Use when: An answer the chip arrives carrying, which the reader is then free to change. The uncontrolled half of the pair, and what almost every use wants
+Never for: Keeping the answer in step with something else on the page. Once set it is the chip's own; a page that has to steer it wants value
+
+### onChange — `callback` **Required.**
+
+Use when: Always, and it is required for that reason. It hands back the value of the answer taken, each time one is taken. It is also the only way the answer reaches the page: this renders a div, a button and a list, so there is no form field carrying the choice and no name to submit it under — and a narrowing the page never learns about narrows nothing. The chip goes on showing it either way, which is what makes the omission quiet
+Never for: Nothing — there is no case for leaving it out
+
+### open — `boolean`
+
+Use when: The page owns whether the list is showing — closing it when something else opens, or holding it open across a re-render. Left out, the chip opens and shuts itself, which is what almost every use wants
+Never for: Opening the list once on arrival. That is defaultOpen; passing this pins it open until the page says otherwise
+
+### defaultOpen — `boolean`
+
+Use when: The list is showing when the chip arrives, and the chip owns it from there
+Never for: A list that should stay open. Anything the reader can shut and the page must reopen wants open
+
+### onOpenChange — `callback`
+
+Use when: Something outside the chip has to know the list opened or shut — closing another one beside it, or reporting the interaction
+Never for: Reading the answer. That is onChange, and shutting is not answering
+
+### leadingIcon — `node`
+
+Accepts: QuillSystemIcon
+Use when: A glyph makes the kind of narrowing faster to recognise than its name alone. It sits before the words and never replaces them. Pass the glyph itself rather than one already wrapped in an Icon: the chip wraps it at icon.size.xs at sm and icon.size.sm at md, the same step its chevron takes
+Never for: Decoration, or a second copy of what the word says. A row where every chip carries a mark that adds nothing reads more slowly than plain words would
+
+## 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.
+
+- **A sort order above an article index** — `label="Sort"`
+  The set is four or five answers and the row has space for one control rather than five. The chip shows the answer in place of its own name once something is chosen, so the row reports the query rather than naming the filter
+- **A region or language picker in a filter row** — `alignment="end"`
+  Near the end of a row, a list pinned to its leading edge runs off the screen. The trailing edge is pinned instead and the other let go
+
+## 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: `listbox`
+- `Tab` — move focus. One stop, on the chip — the list never takes focus, so a reader passes an open chip in a single press just as they pass a shut one
+- `Enter` — open the list, or take the answer the arrow keys are resting on
+- `Space` — the same as Enter. A chip that opens on one and not the other is broken
+- `ArrowDown` — open the list, or move down it
+- `ArrowUp` — open the list at its end, or move up it
+- `Home` — the first answer that can be taken
+- `End` — the last answer that can be taken
+- `Escape` — shut the list, leaving the answer as it was
+- an accessible name drawn from label, which names what is being chosen rather than what pressing does
+- the chip says a list opens and whether it is open, which a chevron says to the eye and to nobody else. Both come from the chip itself, which is why this renders one rather than taking any trigger
+- focus stays on the chip while the list is open, and the answer the arrow keys are resting on is named from there. A list of answers is not a set of tab stops — the chip holds the answer, so the chip holds the focus, which is what separates this from a DropdownMenu
+- the answer already given is marked in the list rather than only shown on the chip, so a reader who reopens it hears which one is theirs without leaving the list
+- Escape returns nothing but the list. The answer stays as it was, because shutting is not answering — a reader who opens a list and changes their mind has changed 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
+
+❌ SelectChip for: Pressing an item does something rather than answering something
+   A menu performs and a list of answers answers. This holds a value, shows it when shut and marks it when reopened; a menu keeps its own name whatever was pressed, and the difference reaches a screen reader as two different roles
+   → use `DropdownMenu` instead.
+
+❌ SelectChip for: The chip answers on its own, or the set is short enough for every answer to sit in the row as a chip of its own
+   A chevron promises a list, and a chip that only turns on and off and shows one anyway is promising something it does not have. The same holds from the other end: a chip each shows every narrowing at once and answers in one press, where this costs a press to open before anything can be read. Folding is worth it only when the row cannot hold the set
+   → use `FilterChip` instead.
+
+❌ SelectChip for: Each answer is a page with its own address
+   A narrowing that has a URL is a place, and a place should be an anchor: crawlable, openable in a new tab, returned to by the back button. A list of answers is none of those
+   → use `Link` instead.
+
+❌ disabled=true + open=true
+   A chip that cannot be used has no list to show. Opening one asks for a set of answers on a control that can take none of them, and the component declines it — this is the same refusal a compiler can make first.
+
+## Example
+
+```tsx
+import { SelectChip, Option } from '@deriv-com/dds-marketing'
+
+<SelectChip onChange={(value) => { /* your handler */ }} label="Sort" defaultValue="newest">
+  <Option value="newest">Newest first</Option>
+  <Option value="oldest">Oldest first</Option>
+  <Option value="popular">Most read</Option>
+</SelectChip>
+```
+
+```tsx
+import { useState } from 'react'
+import { SelectChip, Option } from '@deriv-com/dds-marketing'
+
+// Controlled: SelectChip reports the value, not the event.
+const [value, setValue] = useState('')
+<SelectChip label="Sort" value={value} onChange={setValue} onOpenChange={(open) => { /* your handler */ }}>
+  <Option value="newest">Newest first</Option>
+  <Option value="oldest">Oldest first</Option>
+  <Option value="popular">Most read</Option>
+</SelectChip>
+```
+
+## In use
+
+### Before and after an answer
+
+The chip names the narrowing until one is chosen, and carries the answer afterwards. A row of these reads as decisions made rather than filters available.
+
+```tsx
+import { Option, SelectChip } from '@deriv-com/dds-marketing'
+
+// Nothing chosen — the chip is the name of the filter
+<SelectChip onChange={(value) => { /* your handler */ }} label="Sort">
+  <Option value="newest">Newest first</Option>
+  <Option value="oldest">Oldest first</Option>
+  <Option value="popular">Most read</Option>
+</SelectChip>
+
+// Answered — the chip carries the answer
+<SelectChip onChange={(value) => { /* your handler */ }} label="Sort" defaultValue="popular">
+  <Option value="newest">Newest first</Option>
+  <Option value="oldest">Oldest first</Option>
+  <Option value="popular">Most read</Option>
+</SelectChip>
+```
+
+### Which edge the list is pinned to
+
+The other edge is let go, so the list is as wide as its longest answer with the chip's width as a floor. End is for a chip near the end of a row.
+
+```tsx
+import { Option, SelectChip } from '@deriv-com/dds-marketing'
+
+// start — the default, answers begin at that edge
+<SelectChip onChange={(value) => { /* your handler */ }} label="Region" alignment="start" defaultOpen>
+  <Option value="eu">Europe</Option>
+  <Option value="apac">Asia Pacific</Option>
+  <Option value="latam">Latin America</Option>
+</SelectChip>
+
+// end — for a chip that would otherwise open off the screen
+<SelectChip onChange={(value) => { /* your handler */ }} label="Region" alignment="end" defaultOpen>
+  <Option value="eu">Europe</Option>
+  <Option value="apac">Asia Pacific</Option>
+  <Option value="latam">Latin America</Option>
+</SelectChip>
+```
+
+### An answer that cannot be taken
+
+It stays in the list and stays readable: a set that hides what it will not accept leaves the reader hunting for something that was there last week. The arrow keys step over it.
+
+```tsx
+import { Option, SelectChip } from '@deriv-com/dds-marketing'
+
+// One market not open to this account
+<SelectChip onChange={(value) => { /* your handler */ }} label="Market" defaultOpen>
+  <Option value="forex">Forex</Option>
+  <Option value="stocks">Stocks</Option>
+  <Option value="crypto" disabled>Crypto</Option>
+</SelectChip>
+```
+
+### Sizes
+
+The chip takes the size and the list it opens follows, so a reader never meets rows from one size under a chip from another.
+
+```tsx
+import { Option, SelectChip } from '@deriv-com/dds-marketing'
+
+// sm — the default, level with a FilterChip
+<SelectChip onChange={(value) => { /* your handler */ }} label="Sort" size="sm">
+  <Option value="newest">Newest first</Option>
+  <Option value="oldest">Oldest first</Option>
+</SelectChip>
+
+// md — a touch-first layout
+<SelectChip onChange={(value) => { /* your handler */ }} label="Sort" size="md">
+  <Option value="newest">Newest first</Option>
+  <Option value="oldest">Oldest first</Option>
+</SelectChip>
+```
+
+### Unavailable
+
+The narrowing cannot be made just now — the set is empty, or the index it governs has not loaded. It dims and leaves the tab order.
+
+```tsx
+import { Option, SelectChip } from '@deriv-com/dds-marketing'
+
+// Nothing to choose between yet
+<SelectChip onChange={(value) => { /* your handler */ }} label="Market" disabled>
+  <Option value="forex">Forex</Option>
+</SelectChip>
+```

package/.llm/components/spinner.md

@@ -0,0 +1,222 @@
+<!-- GENERATED from spinner.contract.json. Do not edit. -->
+
+# Spinner
+
+A turning ring that says a wait is real and the page has not stalled. A marketing page has very little to wait for — it is copy and pictures, and they arrive with the page — so a spinner here is the exception rather than the furniture: a form that has just been submitted, an embed or a demo still loading, a band of live figures being fetched.
+
+That rarity is the brief. In an app a spinner is ordinary and a reader waits because they have an account and a reason to; on a landing page it is shown to someone with no stake in the outcome and nothing keeping them there. So it appears where a wait has already started — after the reader did something, or where a section has visibly held space for something that has not come — and nowhere else.
+
+## Use when
+
+- The reader has just submitted something — a signup, a contact request — and the page owes them a sign that it is working
+- A section is holding space for content that arrives separately: an embed, a demo, a band of live figures
+- Something the reader asked for is on its way and nobody can say how long it will take
+
+## Do not use
+
+- The wait is the page's own first load → nothing here does this
+- How much is done is known, or could be → nothing here does this
+- A wait short enough that the ring is a flash. A spinner that appears and goes inside a few hundred milliseconds reads as a glitch in the page rather than as work being done, and the reader is left with the flicker rather than the result
+- More than one in a view. Three rings turning in three cards is a page that looks broken rather than busy — one spinner for the thing being waited on, at the level the reader is looking
+- Decoration. A ring turning in a hero because the section looked static is motion with nothing behind it, and it teaches a reader that a spinner on this site does not mean a wait
+- Standing in for content whose shape is already known. A ring in the middle of a section says nothing about what is coming and holds no room for it, so the layout jumps when it arrives — space the content will fill is better held by the space itself
+
+## Anatomy
+
+Spinner renders 4 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-spinner`. The container, and the thing that carries the accessible name when there is one. `inline-flex` in a column with the items centred: the circle, and the label beneath it when there is a label to draw.
+  
+  A column rather than a row, and there is no orientation to choose. The label is off by default and the cases that show one are standalone — a section or a form waiting — where the words sit under the ring and the pair reads as one centred block. A spinner beside a line of text is the other case, and it is better served by omitting the label entirely and letting the sentence already on the page say what is loading.
+- `circle` — `<svg>`, class `dds-spinner__circle`. The turning ring. Its shapes carry `vector-effect: non-scaling-stroke`, which is what makes the stroke-width tokens mean rendered pixels rather than viewBox units — without it one token would draw a different thickness at every size, right at one of them and wrong at the rest.
+  
+  It takes the colour and the size — a fill role rather than an ink one, because the ring is a drawn shape and not text, and the fg roles are darkened to carry contrast as words; the rotation is in `spinner-impl.css`, because a keyframed loop is not something a contract can hold. It reads `--motion-duration-spinner` and `--motion-easing-spinner` straight from the built stylesheet: the token build emits every semantic role whether a contract binds it or not, so binding them here bought two `transition-*` declarations on an element that never transitions. That file also stops it under `prefers-reduced-motion`, where the ring stands still and the arc alone still marks the component as present.
+- `track` — `<circle>`, class `dds-spinner__track`. The faint full ring the arc travels over. Drawn in the same colour as the arc, so the only thing separating them is its alpha — which is why it is a part rather than an attribute: `stroke-opacity` inherits, so bound on the svg it would fade the arc along with it and leave a ring with nothing moving on it.
+- `label` — `<span>`, class `dds-spinner__label`. What is loading, in words. Rendered whenever a label is given, and hidden visually rather than dropped when `showLabel` is false — `role="status"` is a live region and a live region with no name is one that fires with nothing to say.
+  
+  Absent with no label, rather than present and empty: the span exists to carry the name, and with no name to carry it is a flex item holding a gap open under the ring.
+  
+  Its family is bound rather than inherited. A component that does not bind one takes whatever the page sets, and a marketing page sets a great many things — the ratified stack governs nothing it does not already happen to get. Rendered only when `label` is set.
+
+Apply these classes from the generated `spinnerParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+
+## Props
+
+### size — `sm` | `md` | `lg` (default `md`)
+
+- `sm` — In a line of body copy, or inside a control the reader has just pressed. Sixteen, the size of the words beside it, so it sits on the line rather than in front of it
+- `md` — The default. A form that has been submitted, a card waiting on the figure it is going to show
+- `lg` — A section holding space for something that arrives separately — an embed, a demo, a band of live figures. Sized to be found from where the reader is looking, which is the whole section rather than one control in it
+
+### variant — `accent` | `neutral` | `inherit` (default `accent`)
+
+- `accent` — The default, and what a page nearly always wants. The wait is the one thing happening, and the brand colour is what says the page is doing it rather than failing to
+- `neutral` — The wait is incidental to what the reader came for — a figure refreshing inside a card that is otherwise readable. Brand colour on a wait nobody is watching spends attention the page needs further down
+- `inherit` — Inside something that has already set a colour: a filled button, a dark band, a coloured panel. `currentColor` reaches the ring and the label together.
+
+This is also how a spinner on a dark section or a photograph gets its colour. There is no fixed-light or fixed-dark role in this package, and adding one would be asking a second time a question the section has already answered by setting its text colour
+Never for: Marking one wait as more important than another. Two spinners in a view is the thing to fix; recolouring one of them is not
+
+### label — `string` **Required when showLabel=true.**
+
+Use when: Naming what is loading, for a spinner that stands on its own — a section, a form, a button whose own words have been replaced by it. Without it the spinner is decorative and says so properly: no role, no name, hidden from a screen reader outright
+Never for: A second voice for something the page has already said. A ring beside a line reading “Sending your details” is not a separate thing loading, and naming it makes a screen reader announce the wait twice. Omitting it is what that case is for — an empty string is not, because an unnamed live region is still a live region and it still fires
+
+### showLabel — `boolean` (default `false`)
+
+Use when: The words should be drawn as well as announced — beneath the ring, for a section or a form where the reader can see the wait but not what it is for
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- Announced as: `status`
+- accessible name from label
+- A spinner with no label carries no role either. Decorative is a real mode here rather than an oversight — aria-hidden, no live region, nothing announced — and it is the right one wherever the copy beside the ring already names the wait.
+
+## Rules
+
+- **On a phone a section's actions stack and each fills the width, including when there is only one** — On a phone a page's actions stack, and each one fills the width. Not most of it, and not the width its label happens to need — the whole column.
+
+Two side by side is what this replaces. On the narrowest screen each gets half a column minus the gap, which is rarely enough for a real label: the words wrap inside the pills, the two buttons come out different heights, and the pair reads as a broken row rather than as a choice. Stacked, each has the whole width and neither has to shorten its words to fit.
+
+A single action fills too, and that is the part worth saying, because it is the one that looks unnecessary. A lone button has the room to sit at its natural width and still should not: a full-width control is the phone's convention for the thing the screen is asking you to do, and a pill hugging its label reads as one option among others that are not there. It also makes the target predictable — the whole width, wherever the thumb lands — which a centred pill does not.
+
+Filling is the row's job rather than the button's. A button has no width of its own and is not given one; the row it sits in becomes a column and stretches its children, so nothing about the control changes and the same button is full width here and its own size on a desktop.
+
+This is the phone's breakpoint, size.breakpoint.md, and not the wider one that decides whether a heading is centred. Those are different questions and they break at different widths: a heading stops being centred when the measure is the screen, while a button stops being full width much sooner than that — stretched across a tablet it is a long way from its own label, and a label centred in a metre of pill is harder to hit than one in a pill the size of the words.
+
+What this is not about is every row of controls. A set of filter chips, a pagination strip, a toolbar, a link sitting after a sentence — none of these is the page asking for something, and stacking them to full width would turn a strip the eye skims into a list it has to read. The test is whether the row is the call to action the section was written for.
+  Guidance only — cannot be checked automatically.
+- **Never nest one interactive element inside another** — Nested interactive elements produce ambiguous hit targets and an unreachable inner control for keyboard and screen-reader users. This is why the rule cannot live on any single component — it constrains Button, Link, Input and Switch simultaneously.
+  Guidance only — cannot be checked automatically.
+- **A section that paints a ground sets the ink to go with it** — A page sits on color.bg.page, and a section that separates itself from it takes one of three grounds. color.bg.subtle is the light one and needs nothing further — the page's own ink still reads on it. The other two are dark and do not: color.bg.brand-strong takes color.fg.on-brand-strong, and color.bg.brand takes color.fg.on-solid. Both are white, and both are written as the role rather than the white they resolve to. Set one of those backgrounds without its ink and the text inherits whatever the page was already using, which is near-black on a dark band — legible to nobody, and invisible to every check here, because each pair passes contrast on its own and nothing can tell whether a section used both.
+
+color.bg.brand carries a second limit that is not about forgetting. Its ink measures 3.39:1, which clears the 3:1 a heading needs and misses the 4.5:1 running copy needs. A coral band may carry a headline and a call to action; a paragraph on one is text the reader has to work through at a ratio the waiver on that role does not cover — the waiver says so itself. A section with copy in it takes color.bg.brand-strong, which is near-black and carries white at full contrast.
+
+color.bg.strong is not a section ground. It is the inverted fill for an action that has to outrank what surrounds it, and the components that paint it — Button and ButtonIcon in their inverse form — already set both halves in one rule, which is the pattern a hand-painted section has to copy.
+  Guidance only — cannot be checked automatically.
+- **Every gap inside a section names the relationship it expresses, and the same relationship keeps its measure when it turns on its side** — A section's spacing is named by the relationship it expresses, not chosen by size. Every gap in a section has a role token, and reaching for a step off the generic scale because it happens to be the right number is how two sections written by two people stop lining up: the numbers agree today and drift the first time one of them is tuned.
+
+The heading group is three steps, not one gap. An eyebrow sits nearer its title than the title sits to its description, and the actions sit further from the description than either — space.heading.eyebrow-title, space.heading.title-description, space.heading.description-actions, in that order. A single `gap` on the group cannot say this; it sets all three the same and the block reads as evenly spaced lines rather than as a mark, a name and a paragraph. The eyebrow has to identify itself for this to work, because a group that opens with a title must not give its description the eyebrow's tighter step.
+
+The step between a title and its description follows the size of the title, which is why there are two of it. What a reader sees is not the gap but the gap plus the leading above it, and leading scales with the type: under a display title the leading is most of the space, under a card's title it is half as deep. One value for both makes a card look loose at the size that made a section look right. So space.heading.title-description is the display step and space.heading.title-description-compact is the step at a card's size, and the choice is made by how big the title is rather than by what kind of block it sits in.
+
+Every one of those steps is smaller than the gap below the group, and that ordering is what holds the group together as one thing. space.heading.content is the step between a heading group and the content it introduces, and it is the widest measure inside a section: the one gap the eye reads as a change of subject rather than as a continuation.
+
+That step is the same whether the content is under the heading or beside it. A split is the same relationship turned on its side — a heading group and the content it introduces — so the space between the two halves is space.heading.content, not a gutter. When the split collapses to one column on a phone the gap becomes vertical again, which is where it started, and nothing has to change for that to be right.
+
+space.grid.gutter is between two things of the same kind. Two cards in a row are the same kind; the two halves of a split are not, which is why the gutter is the wrong measure there even when the number would have looked acceptable. The gutter runs on both axes, so a grid reads as an even field rather than as rows with a seam down them.
+
+space.inset.card is the card's, not the page's. A row of cards padded differently is a row of different cards, and the fill is the only edge they have. A page composing a row does not get to choose it.
+
+Column count is not a breakpoint decision. A row holds as many columns as fit before a column would be narrower than size.grid.column-min, and drops one when they would not. Written as a fixed count that collapses at a breakpoint, a four-up row keeps four columns at every width above the phone and sets its copy two or three words to a line through the whole of the tablet range — and on a narrow desktop, which no breakpoint sits on at all. The threshold is a property of the row rather than of a card: a card fills whatever cell it is given.
+
+What this does not cover is the space above and below a section, which is space.section.default and space.section.compact, and the page's own side margin, which is space.inset.page. Those are the section's outside; everything here is its inside.
+  Guidance only — cannot be checked automatically.
+- **A section's title is centred over stacked content, starts beside content in columns, and starts on a phone** — Two arrangements, and the title's alignment is decided by which one it is introducing rather than chosen per section.
+
+Content stacked under the title — a row of cards, an accordion, a set of steps — takes a centred title. The heading group and the block below it share one axis, so a centred title is symmetric with the thing it names, and the eye drops from the middle of the words to the middle of the set. A title starting at the left over a centred or full-width block reads as belonging to the first column rather than to all of them.
+
+Content beside the title — a split, a picture in the other half, anything laid out in columns — takes a title that starts where its content starts. The two share a left edge, and that edge is what says they are one thing read across rather than two stacked. Centring the title there breaks the only alignment the reader has to hold the halves together, and it drifts further from its content the wider the page gets.
+
+The heading group is what carries this, not the heading alone. An eyebrow, a title and a description are read as one block and align together; aligning the title without them leaves a centred heading over start-aligned copy, which reads as a mistake rather than as a choice.
+
+Centred means all of it, not just the words. A badge, a row of actions, a picture — these are flex children, and a flex child is placed by align-items rather than by text-align, so a block that only sets the text leaves everything that is not text at the start. A hero is the case that shows it: its title and copy centred while its badge and its buttons did not.
+
+A capped block centres itself as well as its words. A heading group takes size.heading-group.max, and a cap that is not centred leaves the measure at the start of the column with the words centred inside it — composed, and a long way left of the middle it appears to be in.
+
+Both arrangements go to the start on a phone. A centred block reverts below the breakpoint, and the reason is the measure: on a phone the measure is the screen, so a centred title wraps to three or four ragged lines and the eye loses the left edge it was tracking — the same symmetry that reads as composure on a desktop is what makes it hard to scan on a phone. Centring there has to be asked for twice, and a section title is not one of the things that asks: it is centred because there is room for it, and on a phone there is not. Going back to the start means all of it too, and a capped block is the one that hides a leftover: its words go to the start while its measure stays in the middle of the column, which reads as a title still centred over a badge and buttons that are not — the box in the middle and the line inside it at the edge.
+
+A hero is a section like any other: its badge, title, copy and actions are one stacked block, so it is centred on a desktop and starts on a phone with everything else.
+
+What this is not about is a page whose body is a form or a document. A title over a sign-up form or a guide is not introducing a set of content — it is the first line of the thing itself, and it keeps the alignment the body has, which for running text is the start. The distinction is whether the block below is content the title names or content the title is part of.
+  Guidance only — cannot be checked automatically.
+- **Anything a pointer has to hit is at least 24px in both directions** — A control sized by its contents is as big as its contents, and a glyph is chosen for how it reads rather than for how easily it is hit. An icon-only button with no padding is a 16px target — smaller than the pad of a finger, and smaller than the tremor of a hand using a mouse.
+
+WCAG 2.2 asks for 24 by 24 CSS pixels at AA. The exceptions are narrower than they look: inline targets inside a sentence are exempt, and so is a small target with 24px of clear space around it — but a clear button sits against the field it empties, and a field is itself a target, so the spacing exemption does not apply to the case that keeps arising.
+
+The target and the mark are separate decisions, and conflating them is what produces both faults. Growing the glyph to 24px makes it shout; leaving the button at 16px makes it hard to hit. So the glyph keeps the size that reads correctly beside its text, and the box around it declares a minimum of its own — which is what size.target.min is for.
+
+Declared rather than emergent. Padding plus contents does clear 24px in several components today, and it is the weaker statement: it is a size nobody wrote down, so it moves when the type scale or the glyph does, and nothing says it was meant to be a target at all.
+  Guidance only — cannot be checked automatically.
+
+## Anti-examples
+
+❌ Spinner for: The wait is the page's own first load
+   Nothing here does this, and the useful thing is knowing why. A landing page that opens on a spinner has replaced its first impression with a placeholder — the reader has not asked for anything yet, so there is no wait they are party to, only a page that is not ready. That is a build and delivery problem, and a ring turning in the middle of it makes it look deliberate.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ Spinner for: How much is done is known, or could be
+   Nothing in this package shows progress yet, and a spinner is not a stand-in for it: a ring turning says only that something is happening, which is the right answer when it is the true one and a worse one than a bar whenever a share of the work can be named.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ showLabel=true + label missing or empty
+   A label shown on screen with no text in it is a gap held open under the ring, and a centred block that is no longer centred on anything
+
+## Example
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+<Spinner label="Sending your details" showLabel />
+```
+
+## In use
+
+### Three sizes, three places
+
+The size follows what the reader is looking at when the wait starts — a line of copy, a form, or a whole section holding space.
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+// sm — in a line of body copy, or in a control just pressed
+<Spinner size="sm" label="Checking that address" />
+
+// md — the default: a form that has just been submitted
+<Spinner size="md" label="Sending your details" />
+
+// lg — a section holding space for an embed or live figures
+<Spinner size="lg" label="Loading live spreads" />
+```
+
+### Three colours, and the one that borrows
+
+Brand says the page is working on what the reader asked for. Neutral is a wait nobody is watching. Inherit takes currentColor, which is how a ring gets its colour on a filled button or a dark band.
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+// accent — the default, and the wait the page owes the reader
+<Spinner variant="accent" label="Sending your details" />
+
+// neutral — a figure refreshing in a readable card
+<Spinner variant="neutral" label="Refreshing prices" />
+
+// inherit — inside something that has already set a colour
+<Spinner variant="inherit" label="Sending your details" />
+```
+
+### Named, drawn, or neither
+
+A standalone spinner has to name itself, and showLabel decides only whether the words are drawn. Omitting the label is the third mode: no role, nothing announced.
+
+```tsx
+import { Spinner } from '@deriv-com/dds-marketing'
+
+// Named and announced, not drawn — the default
+<Spinner label="Sending your details" />
+
+// Drawn as well — the wait is visible, its reason is not
+<Spinner label="Loading live spreads" showLabel size="lg" />
+
+// Neither — decorative, beside copy that names the wait
+<Spinner />
+```