@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/tooltip.md

@@ -0,0 +1,267 @@
+<!-- GENERATED from tooltip.contract.json. Do not edit. -->
+
+# Tooltip
+
+A brief description of the element it is anchored to, shown on demand.
+
+## Use when
+
+- Naming a control whose icon or abbreviation cannot say what it does
+- Showing the full text of a value the layout has truncated
+
+## Do not use
+
+- The guidance is needed before the reader acts, rather than after they point at something → nothing here does this
+- The message must persist, be dismissed, or contain something to press → nothing here does this
+- Information the user must have to finish the task — a tooltip is invisible to anyone who never points at it, and absent entirely on touch
+- Anything interactive — a tooltip cannot be focused, so a control inside it cannot be reached
+- More than a sentence — this is a label, not a panel
+- A tooltip that finds its own way out of the viewport's edge. The caret sits at one of twelve fixed points — three along each of the four edges — and the consumer names which one. TooltipAnchor holds the chip against the anchor so the named point is where the caret lands, and it still measures nothing: a chip whose named side has no room will overflow rather than move to the side that does.
+- A Tooltip rendered on its own. `hidden` defaults to false, so a chip with nothing driving it is visible the moment it mounts, sitting in the layout rather than over it and pointing at nothing — and the aria-describedby that makes it a description belongs to the anchor, which a chip on its own does not have. Render it through TooltipAnchor, or drive it with useTooltip. See Behaviour below.
+- Anything but text inside the chip. Composition allows `text` alone and names Button, Input and Card as forbidden: a control in there cannot be reached, and a Card in there is a panel wearing a label's clothes.
+- Reporting that something failed. There is no danger ground here, on the same reasoning Badge gives for having none: those roles report what happened to a reader who did something, and a landing page's reader has not done anything yet. A tooltip is the wrong carrier for it besides — it is not on screen until it is pointed at, and on touch there is nothing to point with, so a message that matters is one a reader may never see.
+
+## Anatomy
+
+Tooltip renders 3 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-tooltip`. Holds the caret against the chip. Carries the axis attributes, which is the only place a consumer's prop can land and therefore the only place the caret can read them from. It is also the element that moves: the transition and the transform-origin are declared here, so the reveal's scale grows out of the edge facing the anchor instead of the chip's centre.
+  
+  The chip is set at `font.body.sm` — fourteen — where Product's takes the default step. A tooltip is not the page: it is a sentence about something the reader is already looking at, and set at the same size as the copy it interrupts it reads as a second paragraph rather than as an aside. Smaller is also what keeps `size.tooltip.max` honest — the measure was chosen so the eye finds the start of the next line, and a wider glyph at the same measure gives fewer words per line to find it by.
+- `caret` — `<svg>`, class `dds-tooltip__caret`. The triangle that points at the anchor. Takes its fill from the body's own background so the two read as one silhouette, and is not rendered at all when showCaret is false — an empty box of the caret's own bound size would hold the chip off its anchor by a caret nobody can see.
+- `body` — `<div>`, class `dds-tooltip__body`. The chip — the surface the description sits on. Separate from the root because a caret has to sit outside the surface it points away from, and a caret inside the painted box is a notch rather than a point. Carries the width ceiling, so the measure is the same whichever edge the caret leaves from.
+
+Apply these classes from the generated `tooltipParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `text`
+- Never contains: `Tooltip`, `Card`, `CardButton`, `Accordion`, `TabList` — in children or in any prop that takes a node
+
+## Props
+
+### placement — `top` | `right` | `bottom` | `left` (default `top`)
+
+- `top` — The tooltip sits above its anchor, so the caret drops from the bottom edge to meet it
+- `right` — The tooltip sits on the trailing side of its anchor — the right in English, the left in Arabic — so the caret reaches back across to meet it. The name is physical and the behaviour is logical: the chip's own direction mirrors this, caret and all
+- `bottom` — The tooltip sits below its anchor, so the caret rises from the top edge to meet it
+- `left` — The tooltip sits on the leading side of its anchor — the left in English, the right in Arabic — so the caret reaches across to meet it. The name is physical and the behaviour is logical: the chip's own direction mirrors this, caret and all
+
+### alignment — `center` | `start` | `end` (default `center`)
+
+- `center` — The chip is centred on its anchor and the caret's point lands on the middle of it. Use this unless the chip is much wider than the thing it points at
+- `start` — The chip's leading edge lines up with the anchor's own, so a chip wider than its anchor grows away from it rather than back across the layout. For an anchor at the start of a row
+- `end` — The mirror of start: the chip's trailing edge lines up with the anchor's, for an anchor at the end of a row
+Never for: Moving a caret that is not there. With showCaret false nothing about the chip itself changes — though whatever places the chip still reads this to decide which of its edges meets the anchor's.
+
+### hidden — `boolean` (default `false`)
+
+Use when: Whatever reveals the tooltip has not revealed it yet, or has dismissed it. Defaults to false, which means visible — so something has to drive this, or the chip is simply on. Keeping it mounted and hidden rather than unmounting it is what lets it fade in, and what keeps the anchor's aria-describedby pointing at something real.
+
+Flipping it is the whole animation. The chip fades from opacity.hidden and scales up from motion.scale.enter over motion.duration.fast on motion.easing.enter, growing out of the edge nearest its anchor rather than its own middle. The dismissal is not animated at all — transition-duration is motion.duration.instant while hidden, because by then the pointer has already gone somewhere else. Do not write a transition of your own: the stylesheet declares transition-property from what this axis changes, and a second declaration would both override that list and escape the prefers-reduced-motion guard generated with it.
+Never for: Hiding a description the user still needs. A tooltip nobody can reveal is a sentence nobody reads — if it must always be legible it is helperText, not a tooltip.
+
+### showCaret — `boolean` (default `true`)
+
+Use when: Drawn by default. Leave it on whenever something holds the chip against its anchor — the point is what ties a floating description to the control it belongs to
+Never for: A chip that whatever positions it does not hold against the anchor's edge, or an anchor unmistakable without one. A caret aimed at nothing is worse than no caret. With it off `alignment` is not dead — it still decides which of the chip's edges meets the anchor's; there is simply no point left for it to move.
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Behaviour
+
+A tooltip does not reveal itself and does not place itself. useTooltip is the state machine that does the first: when the chip arrives, how long it waits before it does, what dismisses it, and the id the anchor points at with aria-describedby. TooltipAnchor is the wrapper that does the second, holding a trigger and its chip in one positioning context so the caret lands on the edge it is aimed at. Neither measures anything — the placement is the one the consumer names, and a chip with no room on that side overflows rather than flipping to the side that has some.
+
+Reach for TooltipAnchor unless the trigger is something it cannot wrap. This is the usage the Example section below does not show — that one renders the chip alone, which is a different thing from a tooltip:
+
+```tsx
+import { TooltipAnchor } from '@deriv-com/dds-product'
+
+<TooltipAnchor content="Delete this row" placement="top">
+  <button type="button" aria-label="Delete">×</button>
+</TooltipAnchor>
+```
+
+It takes `content` — the description — and exactly one `children` element, which it clones to attach the pointer and focus handlers and the aria-describedby. That element has to be something focus can rest on: a button or a link, not a span, or the description is one no keyboard ever reaches. `placement`, `alignment`, `status` and `showCaret` pass straight through to the chip, and every useTooltip option is accepted here too.
+
+Accessibility is the part neither the markup nor the props can carry alone. `role="tooltip"` is already on the chip, so do not add it. The `aria-describedby` that turns the chip into this control's description lives on the anchor, and only these two modules put it there — unconditionally, whether the chip is visible or not, because a reference that exists only while something is on screen is one assistive technology never sees. The accessible name is the children.
+
+useTooltipDefaults holds what the options fall back to: `delay` 200ms before a reveal, `hideDelay` 0 before a dismissal, `focusTrigger` `auto` — keyboard focus only — and `isEnabled` true. Read that export rather than repeating the numbers.
+
+Reach past TooltipAnchor to useTooltip when the trigger is not something a wrapper can hold. Spread its `anchorProps` on the trigger and its `tooltipProps` on the chip, and then place the chip yourself — the hook positions nothing.
+
+- `useTooltip`, `useTooltipDefaults` — with `UseTooltipOptions`, `UseTooltipResult`
+- `TooltipAnchor` — with `TooltipAnchorProps`
+
+All from `@deriv-com/dds-marketing`, the same import as the component.
+
+## 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: `tooltip`
+- an accessible name, which is the description itself
+- the anchor points at this tooltip with aria-describedby, so the description is announced with the control it explains rather than never
+
+## 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
+
+❌ Tooltip for: The guidance is needed before the reader acts, rather than after they point at something
+   Nothing here does this, and it is the more common case on a marketing page. A tooltip is not on screen until it is asked for, and on touch there is nothing to hover — so anything a reader needs in order to decide belongs in the copy. Product answers this with a field's helperText; this package has no field yet, and when it does that will be the answer here too.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ Tooltip for: The message must persist, be dismissed, or contain something to press
+   Nothing here does this either. A tooltip cannot hold focus, so anything interactive inside one is unreachable by keyboard. Product reaches for a Popover; this package has none, and a marketing page wanting one usually wants a section of the page instead.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+## Example
+
+```tsx
+import { Tooltip } from '@deriv-com/dds-marketing'
+
+<Tooltip>Rates update every minute</Tooltip>
+```
+
+## In use
+
+### The chip, and what it is not
+
+A sentence about the thing it is anchored to, and never more than that. There is one ground: no danger, no success — a landing page reports nothing that a reader has done.
+
+```tsx
+import { Tooltip } from '@deriv-com/dds-marketing'
+
+// Describing the control it belongs to
+<Tooltip>Rates update every minute</Tooltip>
+
+// Qualifying a claim the page has made
+<Tooltip>Not available in every region</Tooltip>
+```
+
+### Which side it sits on
+
+The side the consumer names. Nothing measures the room available, so a chip with none on that side overflows rather than flipping to the side that has some.
+
+```tsx
+import { Tooltip } from '@deriv-com/dds-marketing'
+
+// Top — the default, caret dropping to the anchor
+<Tooltip>No fee on deposits</Tooltip>
+
+// Bottom — for an anchor near the top of the view
+<Tooltip placement="bottom">No fee on deposits</Tooltip>
+
+// Left — leading side, which mirrors in Arabic
+<Tooltip placement="left">No fee on deposits</Tooltip>
+
+// Right — trailing side, mirroring the same way
+<Tooltip placement="right">No fee on deposits</Tooltip>
+```
+
+### Where it lines up
+
+Which of the chip's edges meets the anchor's. Centre is right until the chip is much wider than the thing it points at — then it grows back across the layout instead of away from it.
+
+```tsx
+import { Tooltip } from '@deriv-com/dds-marketing'
+
+// Centre — the default
+<Tooltip>Based on the last 30 days</Tooltip>
+
+// Start — for an anchor at the beginning of a row
+<Tooltip alignment="start">Based on the last 30 days</Tooltip>
+
+// End — the mirror, for an anchor at the row's end
+<Tooltip alignment="end">Based on the last 30 days</Tooltip>
+```
+
+### The caret
+
+The point is what ties a floating description to the control it belongs to. No row for hidden: it paints nothing, and a blank specimen reads as a fault.
+
+```tsx
+import { Tooltip } from '@deriv-com/dds-marketing'
+
+// Without a caret — nothing holds it to an edge
+<Tooltip showCaret={false}>Delayed by 15 minutes</Tooltip>
+```
+
+### When it wraps
+
+The chip caps at size.tooltip.max and the text wraps inside it. The box does not shrink back to the wrapped lines — CSS settles a width before it breaks the text and never revisits it — so a sentence 
+
+```tsx
+import { Tooltip } from '@deriv-com/dds-marketing'
+
+// One line — the chip hugs its words
+<Tooltip>Minimum deposit is $5</Tooltip>
+
+// Two lines — the chip stays at its cap
+<Tooltip>Verified within one working day</Tooltip>
+```

package/.llm/components/typography.md

@@ -0,0 +1,245 @@
+<!-- GENERATED from typography.contract.json. Do not edit. -->
+
+# Typography
+
+Copy, set in one of the page's type roles. It is the component that finally separates what a line of text is in the document from how large it is drawn — `as` says the first and `variant` says the second, and neither implies the other.
+
+That separation is the whole reason it exists. Every heading role in this package carries the same sentence — a size, not an instruction — because a page that wants a hero-sized line reaches for h1 and gets an <h1>, and the second one on the page is a document with two top-level headings. Here the scale is a prop and the element is a different prop, so a section heading set at hero scale is `as="h2" variant="h1"` and says exactly that.
+
+It sets type and nothing else. No colour, which the container paints and this inherits; no margin, which belongs to whatever is stacking the page — a paragraph that carries its own spacing argues with the gap around it, and the gap wins or the page is wrong.
+
+## Use when
+
+- A heading, a paragraph, or a caption on a marketing page — anything the page writes rather than a component draws
+- A heading whose level and whose size disagree, which is most of them past the first section
+- An eyebrow above a headline, where the capitals are a setting rather than something typed
+
+## Do not use
+
+- The text is inside a component that already sets its own type → nothing here does this
+- The words are a control's name rather than copy → nothing here does this
+- The page needs the text coloured, spaced or aligned → nothing here does this
+- Choosing an element by picking a size. `as` is the document and `variant` is the scale — a page with six h1 elements is still wrong however it was set
+- Carrying a token this does not offer. label and field-label belong to controls, and a paragraph set at a button's weight is a paragraph pretending to be one
+
+## Anatomy
+
+Typography renders one element.
+
+- `root` — `<p>`, class `dds-typography`. The text, and the only element here. Its tag is the `as` prop rather than a fixed one, because what a line is in the document and how large it is drawn are two decisions and this component exists to keep them apart.
+  
+  Its margin is unset. A browser gives <p> and every heading a margin of its own, which would arrive here as spacing nobody asked for and nothing in the contract could see — so the page's own gap is the only thing between two blocks of copy.
+  
+  The figure variant is the one that sets a property no token holds. Its size and weight are font.figure like every other variant's are their own role, but tabular numerals are a literal here rather than a binding: a composite font token carries family, size, weight, line height and tracking and nothing else, and the numeric form is not a value that varies anyway. A figure is always tabular — that is most of what makes it a figure rather than a heading with a number in it, because a column of counts whose digits do not line up is a column the eye cannot compare.
+
+Apply these classes from the generated `typographyParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `text`
+- Never contains: `Typography`, `Button`, `ButtonIcon`, `Card`, `CardButton`, `TextInput`, `TextArea`, `SearchInput` — in children or in any prop that takes a node
+
+## Props
+
+### variant — `h1` | `h2` | `h3` | `h4` | `h5` | `subtitle` | `body-lg` | `body-md` | `body-sm` | `eyebrow` | `figure` (default `body-md`)
+
+- `h1` — The line a landing page is built around, and there is one of them
+- `h2` — A headline opening a major section of a long page
+- `h3` — A section heading under an h1 and h2
+- `h4` — A subsection heading, the first step below the extrabold the larger headings carry
+- `h5` — A label over a group of cards, a list, or a short block of copy
+- `subtitle` — A secondary title under a heading — a pricing plan's name, a sub-feature group
+- `body-lg` — An introductory paragraph under a headline, a hero description, a section intro
+- `body-md` — The default, and most of the copy on a page — feature descriptions, article text
+- `body-sm` — De-emphasised copy: legal lines, disclaimers, help text
+- `eyebrow` — A category label above a headline — a section tag, a plan badge. Drawn in capitals by this component, so write it in the case it should be read in
+- `figure` — A number that is the point of its block — a count, a total, a span of time — with a label under it
+Never for: Picking an element. A variant is a size, and the element is `as`
+
+### as — `p` | `span` | `h1` | `h2` | `h3` | `h4` | `h5` | `h6` (default `p`)
+
+- `p` — The default, and any block of prose
+- `span` — Text inside a sentence, or inside something that is already a block
+- `h1` — The page's one document-level heading
+- `h2` — A section heading
+- `h3` — A heading under an h2
+- `h4` — A heading under an h3
+- `h5` — A heading under an h4
+- `h6` — The deepest heading level
+Never for: Anything interactive. A link is Link and a control is Button — an element that responds to a click needs a name, a focus ring and a keyboard route, none of which this has
+
+Also accepts everything from `HTMLAttributes<HTMLElement>`.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- the element is the one `as` names, so a heading is a heading in the accessibility tree whatever size it is drawn at
+
+## 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
+
+❌ Typography for: The text is inside a component that already sets its own type
+   Button, Badge, Tab and the fields all bind their own roles. Wrapping their content in Text puts two type decisions on one line and the inner one wins silently.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ Typography for: The words are a control's name rather than copy
+   That is the control's own label prop. A control named by a nested element is one whose accessible name depends on what happens to be inside it.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ Typography for: The page needs the text coloured, spaced or aligned
+   The container. Colour is inherited here, margin is never set, and a component that owned either would disagree with the layout that placed it.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+## Example
+
+```tsx
+import { Typography } from '@deriv-com/dds-marketing'
+
+<Typography variant="body-md">Trade the world's markets with a platform built for the way people actually trade.</Typography>
+```
+
+## In use
+
+### Headings
+
+Five sizes, each a scale rather than a level. The element is a separate decision, which is the next block.
+
+```tsx
+import { Typography } from '@deriv-com/dds-marketing'
+
+// h1 — the line the page is built around
+<Typography variant="h1" as="h1">Trade anywhere</Typography>
+
+// h2 — a major section opens
+<Typography variant="h2" as="h2">Why Deriv</Typography>
+
+// h3 — a section under that
+<Typography variant="h3" as="h3">Asset classes</Typography>
+
+// h4 — a subsection
+<Typography variant="h4" as="h4">Clear pricing</Typography>
+
+// h5 — a label over a group
+<Typography variant="h5" as="h5">Included</Typography>
+```
+
+### Elements
+
+A page has one h1 as a document and many lines that want its size. Passing as and variant apart is what lets both be true at once.
+
+```tsx
+import { Typography } from '@deriv-com/dds-marketing'
+
+// as h2, variant h1 — hero scale, second level
+<Typography variant="h1" as="h2">Hero scale</Typography>
+
+// as h6, variant h5 — deep level, readable size
+<Typography variant="h5" as="h6">Deep heading</Typography>
+
+// as p — a heading size on a paragraph is wrong
+<Typography variant="subtitle" as="p">A paragraph</Typography>
+
+// as span — inline, inside a sentence
+<Typography variant="body-sm" as="span">inline aside</Typography>
+```
+
+### Body copy
+
+One regular weight and one line height across the three, so this is body text set larger or smaller rather than three kinds of text.
+
+```tsx
+import { Typography } from '@deriv-com/dds-marketing'
+
+// body-lg — an intro under a headline
+<Typography variant="body-lg">The paragraph that follows a headline and carries the promise.</Typography>
+
+// body-md — most of the page
+<Typography variant="body-md">Feature descriptions, article copy, and anything else the page has to say at length.</Typography>
+
+// body-sm — the fine print
+<Typography variant="body-sm">Trading involves risk. Past performance is not indicative of future results.</Typography>
+```
+
+### Other roles
+
+subtitle sits under a heading as a secondary title. eyebrow sits above one as a category, and draws its own capitals so the words stay in the case they were written.
+
+```tsx
+import { Typography } from '@deriv-com/dds-marketing'
+
+// subtitle — a plan name, a group title
+<Typography variant="subtitle">Standard account</Typography>
+
+// eyebrow — written in sentence case, drawn in caps
+<Typography variant="eyebrow" as="span">Now live</Typography>
+
+// figure — a number, in fixed-width digits
+<Typography variant="figure" as="span">9,482</Typography>
+```

package/.llm/digest/accordion.md

@@ -0,0 +1,43 @@
+<!-- GENERATED from accordion.contract.json. Do not edit. -->
+
+# Accordion
+
+A stack of rows whose headings stay and whose detail is put away until the reader asks for it. …
+
+`import { Accordion } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- Questions a reader asks near a decision — what it costs, whether their money is safe, how long a withdrawal takes. …
+- The long version of something the page has already said shortly — specifications, trading hours, the full terms. …
+- A run of rows at one depth in the page's outline, sitting under a section heading of their own
+
+## Something else, when
+
+- There is one thing to disclose rather than a set → **AccordionItem**
+- The reader is meant to read all of it → **Card**
+
+## Never
+
+- Hiding what a reader has to know before deciding — a fee, a restriction, a condition on an offer. Disclosure a page is obliged to make is disclosure that stays on the page
+- Navigation. A row that goes somewhere when pressed is a link wearing a chevron, and a reader who opens it expecting words gets a page instead
+- A single row on its own. Two at least, because a heading is scanned against its neighbours and one heading has none
+- Steps in a sequence. Rows here are independent and in no order — a reader may open the third without the first, and nothing about the set says otherwise
+
+## Props
+
+- **headingLevel** `enum` · default "3" — Where the rows sit in the page's outline. …
+  - `2` — The rows are the page's own sections, sitting directly under its title — a page that is nothing but questions is the case
+  - `3` — The default. The set sits under a section heading of its own, which is where an accordion usually is
+  - `4` — The set is inside a subsection that already carries a heading above it
+  - never: Making a row's words larger or smaller. The level is the outline, not the type: every row takes the same step whatever depth it sits at, because a question is a question wherever the set is on the page
+
+## Inside it
+
+- Takes only AccordionItem.
+- At least 2, no ceiling — fewer is not this component and more is a different one.
+- 3 components are refused inside it; the list and the reasons are in the long document.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/accordion.md`.

package/.llm/digest/accordionitem.md

@@ -0,0 +1,47 @@
+<!-- GENERATED from accordionitem.contract.json. Do not edit. -->
+
+# AccordionItem
+
+One row of an Accordion: a heading that is always there, and the detail under it that is not. …
+
+`import { AccordionItem } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- One row inside an Accordion — every row of a set is one of these
+- A single disclosure with no set around it: one topic whose detail is worth offering and not worth showing. …
+
+## Something else, when
+
+- The heading goes somewhere rather than opening something → **CardButton**
+
+## Never
+
+- A control inside the heading. The whole heading is one button, so a second one inside it is unreachable to a keyboard and ambiguous to a pointer — the rule about it is the one rule in this system that cannot live on any single component
+- A heading that is a sentence. It is scanned against the rows above and below it, and a row nobody can scan is a row nobody opens
+- Copy the reader is obliged to see. What is behind the control is what a reader goes looking for, not what the page needs them to have read
+- A panel that holds another Accordion. Rows inside rows put a reader two folds deep with no way to see where they are, and the outline they navigate by stops describing the page
+
+## Props
+
+- **expanded** `boolean` · optional — Whether the panel is showing. Inside an Accordion this is injected on every render and the set owns it — a row cannot see its siblings, so it cannot know it is the one that should close. …
+  - never: Forcing a row open so its words are always visible. A panel that never shuts is copy behind a control that lies about what it does, and the reader who closes it once will not open it again. …
+- **onExpandedChange** `callback` · optional — The page needs to know the row was pressed — to record which question was asked, or to hold the answer itself. …
+  - never: Doing something other than opening the row. It fires because a reader asked to see the words; navigating or submitting from it makes the chevron a lie
+- **title** `string` · required — Always — it is the half of the row that is always on screen. A question in the reader's own words, or the name of the thing the panel details. …
+  - never: The answer, shortened. A heading that summarises the panel gives the reader no reason to open it, and a set of them is the long page again in smaller type
+- **headingLevel** `enum` · default "3" — Where this row sits in the page's outline. Inside an Accordion it is injected, because every row of one set is at one depth by definition. Set it here only on a row standing alone
+  - `2` — The rows are the page's own sections. Set on the Accordion rather than here, which pushes it down
+  - `3` — The default, and where an accordion usually sits — under a section heading of its own
+  - `4` — The set is inside a subsection that already carries a heading
+  - never: Changing how large the words are. The level is the outline and the type is `font.subtitle` either way — a row at h2 is not a bigger question than a row at h4
+
+## Inside it
+
+- At least 1, no ceiling — fewer is not this component and more is a different one.
+- 3 components are refused inside it; the list and the reasons are in the long document.
+- Renders 7 parts: root, heading, trigger, title, marker, panel, content.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/accordionitem.md`.