@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/icon.md

@@ -0,0 +1,194 @@
+<!-- GENERATED from icon.contract.json. Do not edit. -->
+
+# Icon
+
+Renders a Quill system glyph at a token size, taking its colour from the text around it. The glyph is imported from @deriv-com/quill-icons-web and passed as the only child. Its components are named shape, then weight, then Icon — MagnifyingGlassRegularIcon, EnvelopeRegularIcon, CircleCheckSolidIcon — and the weight is chosen at the import site because Icon has no weight prop and cannot have one.
+
+The same component Product has, on Marketing's own ramp. The last one here was a copy that nothing had asked for and it was deleted for that; what asks for this one is three components already drawing glyphs by hand — Breadcrumb's separator, AccordionItem's chevron and whatever a page puts in CardBody's mark — each repeating the same two bindings and the same reason.
+
+## Use when
+
+- A glyph stands beside words to speed recognition — a mark on a feature card, a chevron on a row, a separator in a trail
+- A page is composing something a component offers a slot for, and the slot takes a mark rather than a component that draws one
+
+## Do not use
+
+- The mark identifies a company or a product — a payment method, an app store, a social network → `Logo` *(not built yet — raise it with the design system team)*
+- The artwork is a scene rather than a symbol → `Illustration` *(not built yet — raise it with the design system team)*
+- Flag, market, currency or payment glyphs — they carry fixed brand colour, and tinting them corrupts the mark while still rendering. Render one bare, outside an Icon: it keeps its own colour and its own proportions, which is what a mark is
+- Information that appears nowhere else. A glyph a reader has to interpret unaided is a label the page failed to write, and a marketing page has room for the words
+- The picture in a card. A mark is a symbol at a step on this ramp; a photograph or a render is CardBody's `src`, which reaches the card's edges and is measured by the card rather than by a scale of glyph sizes
+
+## Anatomy
+
+Icon renders one element.
+
+- `root` — `<svg>`, class `dds-icon`. The glyph itself. Icon applies its class to the SVG it is handed rather than wrapping it, so the size tokens land on the element that renders — and a CSS width overrides the width attribute every Quill glyph ships with. That is not a detail: sizing a box around a glyph does nothing to the glyph, which is the mistake CardBody's mark had to answer with an impl sheet and a rule reaching into a child.
+  
+  It can turn. A mark that says whether something is open — a chevron on an accordion row, a fold in a menu — is one glyph rotated rather than two swapped, and the rotation wants a duration. Here rather than in each of them, because every such mark is an Icon and none of them owns the box it sits in. Only `rotate` transitions, so an icon taking a new colour still takes it at once.
+
+Apply these classes from the generated `iconParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `QuillSystemIcon`
+- Never contains: `Icon`, `Card`, `CardButton`, `Accordion`, `AccordionItem` — in children or in any prop that takes a node
+- Holds at least 1 and at most 1
+
+## Props
+
+### size — `xs` | `sm` | `md` | `lg` | `xl` (default `md`)
+
+- `xs` — Inline and supporting content — a separator in a trail, a mark against small text
+- `sm` — A mark beside text that must not outweigh it: the chevron on a list row, an affordance next to a label
+- `md` — The default. Body content and lists, where the glyph sits with the words rather than above them
+- `lg` — Cards and content sections — the mark a feature card leads with, read before its title is
+- `xl` — The largest step, for a callout or a highlighted block where the glyph does as much work as the copy
+
+Use when: The step the glyph is drawn at. It is a size and not an instruction: what a mark means comes from where it is, and this decides only how large it is drawn there
+Never for: Setting the step of a glyph you are handing to a component. A slot takes the glyph and its component draws it at the step its own contract names, so an Icon arriving there is a call site written against something else — it is unwrapped and the outer step is what draws. A name on the inner one is carried out, so nothing announced is lost on the way
+
+### label — `string`
+
+Use when: The glyph is the only thing naming its control — an icon-only button, a mark with no words beside it
+Never for: A glyph beside a label that already says the same thing, which makes a screen reader announce it twice
+
+## 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: `presentation`
+- role="presentation" and no accessible name when label is omitted, so a decorative glyph is not announced. A label of no characters, or of spaces, counts as omitted: an empty aria-label is a name of no characters rather than no name.
+- role="img" and an accessible name taken from label when label is given.
+
+## 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.
+- **Solid weight means selected** *(applies to a variant not built yet)* — Solid is not an alternative style, it is what a selected icon looks like. A tab or a navigation item renders regular at rest and swaps to solid when it becomes the current one, so the weight change is what carries the selection. The swap changes weight only — the same glyph at the same size, so the shape stays recognisable and just fills in. Marketing has fewer selected states than Product does, which is the reason to hold the meaning rather than to relax it: a solid glyph used decoratively here teaches a reader that solid means nothing, and they carry that into the product.
+  Guidance only — cannot be checked automatically.
+- **Match the glyph weight to the icon size** *(applies to a variant not built yet)* — Quill ships every system glyph three times — light, regular and solid — as separate components chosen at the import site. Icon has no weight prop and cannot have one, so nothing in this system can observe the choice, let alone enforce it. Size is what should decide it: a glyph carries its stroke weight through any scale, so a regular-weight glyph drawn for 24px renders its strokes at over three times that width when placed at display size, and reads as heavy rather than confident. At rest, use regular from sm through lg, and light at xl, 2xl and display — selection is the one thing that overrides this, and it only ever moves regular to solid.
+  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
+
+❌ Icon for: The mark identifies a company or a product — a payment method, an app store, a social network
+   A brand mark carries fixed colour, and Icon tints whatever it is given
+   → `Logo` is not built yet. Raise it with the design system team.
+
+❌ Icon for: The artwork is a scene rather than a symbol
+   A marketing page reaches for illustration where Product reaches for a glyph, and an illustration is raster, sized by its own proportions rather than by this ramp. It is also the more likely of the two to be wanted here
+   → `Illustration` is not built yet. Raise it with the design system team.
+
+## Example
+
+```tsx
+import { Icon } from '@deriv-com/dds-marketing'
+import { EnvelopeRegularIcon } from '@deriv-com/quill-icons-web'
+import { EnvelopeRegularIcon } from '@deriv-com/quill-icons-web'
+
+<Icon><EnvelopeRegularIcon /></Icon>
+```
+
+## In use
+
+### The ramp, at the steps a page uses
+
+One glyph at every step, because the variable is the size. A new shape in each row is noise a reader has to look past to compare the thing the rows are for.
+
+```tsx
+import { Icon } from '@deriv-com/dds-marketing'
+import { EnvelopeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// xs — inline and supporting, against small text
+<Icon size="xs"><EnvelopeRegularIcon /></Icon>
+
+// sm — beside text it must not outweigh
+<Icon size="sm"><EnvelopeRegularIcon /></Icon>
+
+// md — the default — body content and lists
+<Icon size="md"><EnvelopeRegularIcon /></Icon>
+
+// lg — the mark a feature card leads with
+<Icon size="lg"><EnvelopeRegularIcon /></Icon>
+
+// xl — the largest step, and the end of the ramp
+<Icon size="xl"><EnvelopeRegularIcon /></Icon>
+```
+
+### Named, or not announced at all
+
+A glyph beside words that already say the same thing is announced twice, so it stays decorative. One that is the only thing naming its control takes a label.
+
+```tsx
+import { Icon } from '@deriv-com/dds-marketing'
+import { EnvelopeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// Decorative — role="presentation", no name
+<Icon><EnvelopeRegularIcon /></Icon>
+
+// Named — role="img", announced as its label
+<Icon label="Email us"><EnvelopeRegularIcon /></Icon>
+```

package/.llm/components/link.md

@@ -0,0 +1,354 @@
+<!-- GENERATED from link.contract.json. Do not edit. -->
+
+# Link
+
+A destination named inside a sentence, or standing on its own under one. Inside a sentence it takes everything from the copy around it — the size, the face, the ink — and is told apart by an underline alone. On its own line it takes the brand ink and a mark instead, because there is no sentence to belong to.
+
+Button is the other half of this, and the two are the same act — go somewhere — at different volumes. A Button is a pill a reader aims at; a Link is words a reader is already reading. The test is whether taking it out would leave a hole in the sentence: if it would, it is a link, and if the sentence would read fine without it, the page wanted a Button.
+
+That boundary is worth stating because Marketing's Button is also an anchor, so nothing about the element tells the two apart. What tells them apart is position: one interrupts the copy to ask for a press, and the other is copy.
+
+## Use when
+
+- A term inside running copy has a page of its own — a market named in a paragraph, a fee mentioned in a sentence, a product referred to in passing
+- The page must offer a destination without pushing it: terms, a full fee schedule, a regulatory notice. A pill would give it the weight of the thing the page is actually asking for
+- A second destination beside the call to action, where a second pill would be two things asking to be pressed and a reader would have to choose between them before reading either
+
+## Do not use
+
+- The destination is the step the page was built to produce → `Button`
+- Pressing it does something on this page rather than going somewhere → nothing here does this
+- The whole card or panel is the target rather than some words in it → `CardButton`
+- The page's main call to action. That is Button, and a page whose primary step is a link in a paragraph has hidden it in the copy
+- Words that do not name the destination — 'click here', 'read more', 'this page'. The words are the link's accessible name, and a screen reader offering a list of links reads that list on its own: a page of 'read more' is a menu of identical entries
+- A disabled or pending state. There is none, for the reason Button has none: the browser owns a navigation in flight, and an anchor cannot be honestly disabled — stripping the href is the only thing that truly stops it, and that costs the link role and the focus with it
+- Opening a new tab because the page would rather keep the reader. `external` exists for a destination that is genuinely elsewhere; taking over tab management for its own sake is a decision that belongs to the reader
+
+## Anatomy
+
+Link renders 3 elements. A token binding names the part it applies to.
+
+- `root` — `<a>`, class `dds-link`. The words, and the whole of the control. An `<a>` with a real `href`, so the browser's own affordances all work: cmd-click opens a tab, the status bar shows the destination before the press, the address can be copied, and a screen reader announces a link.
+  
+  A standalone link is `inline-flex` and an inline one is `inline`, which is the difference from every other pressable thing in this package and the one place the two variants disagree about layout.
+  
+  The flex line is what centres the mark. `vertical-align: middle` puts a box's centre at the baseline plus half the x-height, which is below the optical centre of cap-height text — measured, the arrow's ink sat 1.73px low beside a sixteen-pixel label. Centring on the line box instead puts it within a hundredth of a pixel. An inline link cannot have that: it has to break across lines with the sentence it is part of, and a flex box does not wrap. It keeps the alignment `vertical-align` can give and the small offset that comes with it, which is the price of being part of a line rather than a line of its own.
+  
+  `display: inline` for that variant, which is the difference from every other pressable thing in this package. A link is part of a line of text and has to break across lines with it — a Button is `inline-flex` because it is a box the copy flows around, and a link that behaved that way would leave a hole at the end of a line rather than wrapping.
+  
+  The type is inherited rather than bound, in the inline variant. `font-size`, `font-family` and `line-height` all take `inherit`, so a link in a body paragraph is body copy and a link in a caption is caption — which is the whole idea, and the thing that would break if the component set a size of its own. Only `standalone` binds a step — `font.label.md`, sixteen — because a link sitting on its own line has no sentence to take one from. One step and no axis to choose another: Product's Link carries three and this package has shown twice now that it does not need them, Tab having settled the same question the same way. Eighteen exists in the ramp and a standalone link set in it would be a heading that happens to navigate.
+  
+  The underline belongs to the inline variant and not to the component, and inside a sentence it is the whole of what marks the link. Not most of it — all of it: an inline link takes the paragraph's ink as well as its type, so there is no colour difference to fall back on. That is deliberate rather than a concession. A word set in brand red mid-paragraph has been shouted, and what a link in running copy needs is to be findable, which an underline does without interrupting the line. It thickens on hover.
+  
+  A standalone link has no sentence to be told apart from. It is on its own line, in brand ink, usually beside a mark, and an underline there reads as an inline link that has lost its paragraph. So the rule is bound per variant rather than once: `underline` for inline, `none` for standalone.
+  
+  `focusable`, declared rather than inferred. An anchor takes focus only because it carries an href, and no element name reveals that — so a reader and a check see the same answer the browser will give only if the contract states it.
+  
+  The ink is `color.bg.brand`, which is a background role doing a foreground's job, and that is worth naming rather than hiding. `color.fg.brand` exists and is the readable one at 7.75:1 — but it is the dark red a Badge sets on a pale tint, not the coral the page is built from, and a link that did not match the buttons would read as a different kind of thing. The brand primary is one colour in this system and it is spelled `color.bg.brand`; a `fg` alias for the same value would be a second name for one decision.
+  
+  A link whose ink is the ground's gets its underline back on hover, and only on hover. That covers a standalone link at `tone: inherit` — one on a brand card, a dark band, a scrim. The list variant has the same problem and answers it with its mark instead: a column whose rows underline one at a time reads as a table of contents being corrected. At rest they are told apart by position, which is what a column of links or a line of its own already provides; under the pointer there was nothing at all, because the colour cannot change when it belongs to the ground and there is no mark to move. Product reaches the same conclusion from the other side, keeping the underline at all times for `tone: inherit` — these designs do not have one at rest, so it arrives with the pointer instead. It is in the impl sheet because `structure` carries no state.
+- `icon-leading` — `<span>`, class `dds-link__icon-leading`. A glyph before the words, when the destination has a mark a reader recognises faster than its name — a document, a download, a platform. Rare in running copy and ordinary in the standalone variant, which is where it earns its place.
+  
+  A box of the tab's own rather than the glyph itself, because Icon clones onto the SVG and this part is the place in the line. Drawn at `icon.size.xs` — sixteen, a step below what a control takes, because this sits beside words rather than inside a target and twenty next to a sixteen-pixel label outweighs the words it is there to qualify. The part carries the gap and nothing else: the colour comes from the link, which is what `fill="currentColor"` on the glyph is for.
+  
+  Solid, like the arrow after the words. Both marks on a link take the same weight, and what earns it is the size rather than emphasis — see the trailing slot, which carries the argument and the exception it makes to `icon-solid-marks-selection`. Rendered only when `iconLeading` is set.
+- `icon-trailing` — `<span>`, class `dds-link__icon-trailing`. The mark after the words, and the component decides all of it — whether there is one, which one it is, and when it shows.
+  
+  Three answers. An external link is always marked. A standalone or list link is marked unless it opts out, though a list one holds its mark at zero until the pointer arrives. An inline link is bare unless it asks.
+  
+  `presentWhen` names the two props that force the part and cannot name the rest: the variant decides the default, and a list of prop names has no way to say "unless the variant already did". So the part reaches the DOM in more cases than the field lists, which is a simplification rather than a contradiction — everything it does name is true.
+  
+   Which arrow depends on where the link goes: `arrow-right` for a destination on this site, `arrow-up-right` for one off it, and nothing a page passes can change either. That is the point of owning it — an external link that carried a plain right arrow would be telling the reader their tab is about to stay put.
+  
+  The weight follows the words the mark sits beside, which is the only thing the variants disagree about here.
+  
+  A standalone link sets its label at `font.label.md` — semibold — and against that the regular cut's strokes read as a smudge rather than a direction, so its arrow is solid, and so is its leading glyph. That is a deliberate exception to `icon-solid-marks-selection`: the rule reserves the weight for a selected item, this is not one, and what earns it is legibility at sixteen pixels beside a heavier neighbour. Named here so the exception is on the record rather than discovered.
+  
+  An inline link has no label of its own — it takes the paragraph, which is body copy at the regular weight. A solid arrow there outweighs every word around it, so the exception does not reach it and the regular cut is what it draws. The mark matches its neighbours in both cases; only the neighbours differ.
+  
+  Drawn at `icon.size.xs` like the leading slot, so a link carrying both draws them alike. It is decorative and announced as nothing, which is why the accessibility requirement below asks an external link to say so in its words as well.
+  
+  On hover it moves a little way in the direction it is already pointing, and stays there until the pointer leaves. Right for the arrow that points right, up and to the right for the one that points that way — a mark that slid sideways while pointing diagonally would be moving across its own direction. That is the hover affordance for a standalone link, which has no underline to thicken the way an inline one does: the movement says the link is live where the line would have.
+  
+  A transition rather than a keyframe animation, on `motion.duration.normal` and `motion.easing.standard` — the same two tokens ButtonIcon transitions its background and outline on. What was here before sent the arrow out past its own edge, faded it to nothing and brought it back from the other side over `motion.duration.reveal`, which is a gesture with a beginning, a middle and an end for what is a hover on a link. Losing it loses the split `exit`/`enter` curves and the fade at the edges, both of which only existed because something was making a round trip.
+  
+  The distance is 25% of the glyph, which at sixteen pixels is the four pixels `motion.translate.hover` already moves anything else that shifts under a pointer. Of the glyph rather than the box around it: that box carries the gap between the words and the arrow as padding, so it is twenty by sixteen, and a percentage measured on it moved five pixels across and turned the external arrow's diagonal into 39 degrees. A percentage rather than that token because an inline link's mark is `1.1em` and tracks the paragraph, so a fixed nudge would be proportionally large in fourteen-pixel copy and small in twenty. The external arrow takes 18% on each axis, which is that same distance measured along the diagonal rather than four pixels twice.
+  
+  `inline-flex` and `vertical-align: middle` are what make it possible rather than being decisions: a transform does not apply to a non-replaced inline element, so the mark needs a box, and the alignment keeps that box on the words. `overflow: hidden` used to sit beside them and has gone with the keyframes — it was there for the arrow to disappear behind rather than slide out over the words, and a box clipped to its own contents would now cut four pixels off a mark that only means to lean.
+  
+  In a list it is drawn and held at zero until the pointer arrives — see the variant. Drawn rather than rendered on hover, so the row does not change width when it appears and the column does not shift under the reader.
+  
+  Where it travels is the component's to say, handed over as a custom property. `external` decides it and is not a styling axis — it cannot honestly become one, because the only thing it changes is a pair of offsets, and the check asked what `external="true"` changes and the honest answer was nothing a stylesheet can see. A list link's mark rests displaced the other way and at zero opacity, so its arrival and every other mark's nudge are the same declarations read in opposite directions — it travels further to reach the place every hovered mark ends up, rather than having an arrival of its own. Rendered when any of `showIcon`, `external` is set, and not otherwise.
+
+Apply these classes from the generated `linkParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `text`
+- Never contains: `Link`, `Button`, `CardButton`, `Card`, `Accordion`, `AccordionItem`, `Tab`, `TabList` — in children or in any prop that takes a node
+
+## Props
+
+### variant — `standalone` | `list` | `inline` (default `standalone`)
+
+- `standalone` — The default, and what a marketing page mostly has: a link on its own line — under a card, at the foot of a section, beside a call to action. Brand ink and a mark, no underline, because there is no sentence for it to be told apart from.
+- `list` — One of a column of links — a footer sitemap, a navigation menu, a set of related pages under a heading. It takes the ink around it, because a column of coral is a column nobody reads.
+
+Its mark waits for the pointer. A mark on every row of a column distinguishes nothing, and a column with none has no way of saying which row is live — its ink cannot change, because the ink belongs to the column. So the arrow is drawn and held at zero, and the pointer brings it in.
+
+An external link's mark stays. That one is a fact about the destination rather than an affordance, and it is what lets one row in a list of fifty say something before anybody has touched it.
+- `inline` — Inside a sentence, and it takes the sentence's type and the sentence's colour. Nothing about it is coloured brand: a word set in a different ink mid-paragraph is a word that has been shouted, and what it needs is to be findable rather than loud. The underline is what tells it apart, and it is the only thing that does — which is why it is not optional here.
+Never for: Making a link louder or quieter. The three are positions rather than volumes: standalone is alone on its line, list is one of a column, and inline is part of a sentence. None of them means important.
+
+### tone — `brand` | `inherit` (default `brand`)
+
+- `brand` — The default. The brand primary — the same coral the buttons are filled with — so a standalone link and a call to action are recognisably the same colour of intent, and a reader scanning for the way onward finds both.
+
+It is 3.39:1 against the page, below the 4.5:1 that normal text is held to. This package already carries an unsigned waiver for that pairing on a button's label, and this is the second thing leaning on it. What makes it survivable is that it is never the only signal — a standalone link sits on its own line beside a mark — but the ink alone does not carry it, and if the waiver is ever refused this is the binding that moves. color.bg.brand-active is the same hue at 5.56:1 and is what it would move to.
+- `inherit` — A standalone link on a ground that has already set its ink — a brand card, a dark band, a scrim over an image. There the brand ink is either invisible or wrong, and the mark is left to carry the link alone. It is the same argument CardBody makes for setting no colour in its regions.
+
+Use when: Which ink a standalone link takes. It reaches no other variant: an inline link takes the paragraph's colour and a list link takes the column's, which are decisions those positions have already made — the same shape `showIcon` has here.
+Never for: Reaching an inline link. One takes the paragraph's colour already and there is nothing here to choose — this prop governs a standalone link and no other.
+
+### external — `boolean` (default `false`)
+
+Use when: The destination is off this site. Sets `target="_blank"` and `rel="noopener noreferrer"` together — the rel is not optional and not the consumer's job, which is how a page ends up handing `window.opener` to a site it does not control. It also fills the trailing slot with the box-and-arrow, so every external link on the site is marked the same way
+Never for: A new tab on a destination that is not external. Taking over tab management is a decision the reader has already made in their own browser, and a page that overrides it has told them their back button is not to be trusted
+
+### href — `string` **Required.**
+
+Use when: Always. An anchor without one is not a link: it takes no focus, is announced as plain text, and none of the browser's navigation affordances work — so there is no default that could stand in for one, and it is required for exactly that reason
+
+### iconLeading — `node`
+
+Accepts: QuillSystemIcon
+Use when: A mark the destination is known by, before its name — a document, a download. Pass the glyph; the link draws it at sixteen, which is icon.size.xs.
+
+The solid weight, always: `FileSolidIcon` rather than `FileRegularIcon` or `FileLightIcon`. Both marks on a standalone link are solid, which is what keeps one carrying two from wearing two weights. Nothing here can enforce it — Icon has no weight prop and cannot have one, because a Quill glyph's weight is chosen when it is imported — so this is the call site's to get right and the guidance is the only place the rule can live.
+
+Standalone only, and the type says so. This is the slot a page chooses, unlike the trailing one: what a destination is known by is the page's to say, where which direction an arrow points is the system's.
+Never for: Naming the destination. The words are the accessible name and the glyph is announced as nothing, so a link whose meaning is its mark is a link with no meaning at all to a screen reader.
+
+The regular or light weights. Every glyph on a *standalone* link is solid — this slot only reaches one — and the argument is size rather than emphasis: at sixteen pixels beside a semibold label the regular cut's strokes are thin enough to read as a smudge. That applies to a document or a download exactly as it applies to the arrow beside it. An inline link's arrow is the regular cut instead, because there the neighbours are body copy; the rule is that a mark takes the weight of the words beside it, not that this component is solid.
+
+An inline link, which will not compile. There is no version of a glyph mid-sentence that reads as anything but an interruption — the words are the link and the underline is the mark.
+
+### showIcon — `boolean`
+
+Use when: Whether the link carries a mark after its words. It reaches both variants: a standalone link on its own line, and an inline one that wants the arrow inside a sentence.
+
+Left unset it follows the variant, which is the only sensible default and is not one a contract can write: a standalone link is marked, because it is alone on its line with nothing else saying it goes anywhere, and an inline link is not, because an arrow after every linked word would interrupt every sentence carrying one. Set it either way to override that — false for a footer column, where a column of arrows is a column of noise; true for a sentence whose link is the thing being pointed at.
+
+An external link draws its mark whether or not this is set, and draws a different one.
+Never for: Suppressing the external mark. Leaving the site is a fact about the destination rather than a flourish, so `external` marks itself whatever this says — a page that could turn it off could hand a reader a new tab with no warning.
+
+Also accepts everything from `AnchorHTMLAttributes<HTMLAnchorElement>`.
+
+## 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: `link`
+- `Tab` — Reaches the link. It is an ordinary stop in the reading order, which is where a link inside a sentence belongs
+- `Enter` — Follows it, which is what an anchor does and what a button would not
+- accessible name from the words, which have to name the destination. A screen reader can list a page's links on their own, out of the sentences that held them — so 'read more' three times is a menu of three identical entries, and the reader has to visit each to learn which is which
+- No link without an href. An anchor missing one takes no focus and is announced as plain text, which removes the destination from anyone not using a mouse — the prop is required rather than optional for that reason and no other.
+- rel="noopener noreferrer" wherever target is _blank, which `external` sets for itself. Without noopener the opened page can reach back through window.opener to the page that opened it.
+- An external link says so in its words, not only in its glyph. The arrow is decorative and announced as nothing, so "(opens in a new tab)" belongs in the link's text — a reader who cannot see the mark is otherwise told nothing before their tab changes under them.
+- An inline link is underlined, always, and it is the only thing marking it. The link takes the paragraph's colour, so there is no second signal and no tone that changes that — remove the line and a reader has an ordinary word that happens to navigate.
+
+A standalone link carries no underline, and that is a different case rather than an exception. What the rule protects against is a link that cannot be told from the text around it; a standalone link has no text around it. It sits on its own line, in brand ink, next to a mark — three things that are not colour.
+
+## 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
+
+❌ Link for: The destination is the step the page was built to produce
+   A link inside a sentence is read at the speed of the sentence, which is the wrong speed for the one thing the page is asking for. The pill is what makes a call to action findable by someone who is scanning rather than reading
+   → use `Button` instead.
+
+❌ Link for: Pressing it does something on this page rather than going somewhere
+   Nothing here does this. An anchor that does not navigate is a control wearing a link's clothes: it announces itself as a link, offers cmd-click and a status-bar destination, and then does none of it. A marketing page rarely needs one, and the honest answer when it does is a button the page writes itself
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ Link for: The whole card or panel is the target rather than some words in it
+   A link inside a card gives a reader a small target inside a large one they can already see is pressable, and two hit areas where the design showed one
+   → use `CardButton` instead.
+
+❌ variant=inline + iconLeading is set
+   An inline link is part of a sentence and a glyph mid-line breaks the run of words it belongs to. Every mark on this component is a standalone decision — the trailing arrow already refuses to draw inside a sentence, and this is the same rule said in the type rather than in guidance.
+
+## Example
+
+```tsx
+import { Link } from '@deriv-com/dds-marketing'
+
+<Link href="/markets">Learn more</Link>
+```
+
+## In use
+
+### On its own line, and inside one
+
+Two positions rather than two volumes. Standalone is the default and carries no underline — the mark and the line of its own tell it apart. Inline is in a sentence, and the underline is what tells it 
+
+```tsx
+import { Link } from '@deriv-com/dds-marketing'
+
+// standalone — the default, marked
+<Link href="/markets">Learn more</Link>
+
+// inline — underlined, because it is in a sentence
+<Link variant="inline" href="/fees">our fee schedule</Link>
+```
+
+### One of a column
+
+A footer sitemap or a navigation menu. The ink is the column's and nothing is marked — except an external link, which is the one arrow in a list where nothing else has one.
+
+```tsx
+import { Link } from '@deriv-com/dds-marketing'
+
+// list — takes the column's ink, no mark
+<Link variant="list" href="/forex">Forex</Link>
+
+// list, external — the one row that is marked
+<Link variant="list" external href="https://example.com">SmartTrader</Link>
+
+// standalone, for contrast — brand ink and an arrow
+<Link href="/markets">See all markets</Link>
+```
+
+### On a ground that has set its own ink
+
+Brand ink is either invisible or wrong on a coral card or a dark band, so inherit leaves the underline to carry the link alone. The line is never optional — colour cannot carry a link by itself.
+
+```tsx
+import { Link } from '@deriv-com/dds-marketing'
+
+// brand — the ordinary ground
+<Link href="/terms">the terms that apply</Link>
+
+// inherit — a brand or dark card
+<Link tone="inherit" href="/terms">the terms that apply</Link>
+```
+
+### What decides the mark
+
+Unset, the variant answers: a standalone link is marked and an inline one is not. Set, the page has. External marks itself either way, and with a different arrow.
+
+```tsx
+import { Link } from '@deriv-com/dds-marketing'
+
+// standalone — marked, unasked
+<Link href="/markets">See all markets</Link>
+
+// standalone, opted out — a footer column
+<Link href="/markets" showIcon={false}>See all markets</Link>
+
+// inline — bare, unasked
+<Link variant="inline" href="/fees">our fee schedule</Link>
+
+// inline, asked — the regular cut, beside body copy
+<Link variant="inline" href="/fees" showIcon>our fee schedule</Link>
+
+// external — marked either way, and differently
+<Link external href="https://example.com">our licence (opens in a new tab)</Link>
+```
+
+### Leaving the site
+
+external carries the target, the rel and the mark together. The arrow is decorative and announced as nothing, so the words have to say so too.
+
+```tsx
+import { Link } from '@deriv-com/dds-marketing'
+
+// external
+<Link external href="https://example.com/licence">our licence (opens in a new tab)</Link>
+
+// internal — no mark
+<Link href="/licence">our licence</Link>
+```
+
+### A mark before the words
+
+Standalone only, and solid like the arrow — every glyph on a standalone link takes the weight of the semibold label beside it. An inline link may not carry one at all; the type refuses it.
+
+```tsx
+import { Link } from '@deriv-com/dds-marketing'
+import { FileShieldSolidIcon, WalletSolidIcon } from '@deriv-com/quill-icons-web'
+
+// A destination with a mark of its own
+<Link href="/licence" iconLeading={<FileShieldSolidIcon />}>Read the licence</Link>
+
+// Leading and trailing together
+<Link href="/statements" iconLeading={<WalletSolidIcon />}>Download statements</Link>
+
+// Words alone, which is most links
+<Link href="/markets">See all markets</Link>
+```