@deriv-com/dds-marketing 1.1.2 → 1.2.0

package/.llm/components/illustrationcode.md

@@ -0,0 +1,192 @@
+<!-- GENERATED from illustration-code.contract.json. Do not edit. -->
+
+# IllustrationCode
+
+A drawn row of code boxes, filled or not, for a picture of the product asking for a code.
+
+## Why it is built this way
+
+The boxes a verification code is typed into, drawn as a picture of the product: a row of equal boxes, each filled with a dot or waiting. It is never a field; a page that asks for a code uses one.
+
+It can fill once on arrival — the boxes fill one after another — so a pane shows the code going in rather than a code already entered. At rest, and for a reader who asked for less movement, the boxes are simply as filled as `filled` says.
+
+## Use when
+
+- A pane, or any picture of the product, showing a verification step — confirming it is you, two-step sign-in
+- The code going in is the point of the picture, played once with `motion="fill"`
+
+## Do not use
+
+- The reader types a code on this page → `TextInput`
+- A real code entry. Nothing in it can be focused or typed into, and it holds no digits — only dots, because a picture should never show a code
+- More than one moving thing in a pane. One lead motion per pane
+
+## Anatomy
+
+IllustrationCode renders 2 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-illustrationcode`. The row of boxes, `length` of them in equal columns a space.gap.sm apart. Decoration to assistive technology unless `label` names it as an image. Under `motion="fill"` it moves once on arrival (`data-arrival`).
+- `box` — `<span>`, class `dds-illustrationcode__box`. One box, an outline of border.width.emphasis at radius.control.sm, in color.border.strong while empty and in the text's ink once filled with its dot, at font.label.md. Filling, each box takes its dot and its ink a step of motion.duration.stagger after the one before.
+
+Apply these classes from the generated `illustrationCodeParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+
+## Props
+
+### length — `number` (default `6`)
+
+Use when: How many boxes: six, the default, for the usual verification code; four for a short one
+Never for: A code longer than eight. A row of more boxes than that is too narrow to read as boxes
+
+### filled — `number`
+
+Use when: How many boxes are filled, from the start. Left out, all of them — a code entered
+Never for: Showing a code half typed with `motion="fill"`. The motion fills the boxes it is given; a picture of a code mid-entry is still, with no motion
+
+### motion — `fill`
+
+- `fill` — The boxes fill one after another, a step of motion.duration.stagger apart
+
+Use when: The row moves once, on arrival — in an IllustrationCard when the pane has landed, otherwise when it is well into view. At rest, and for a reader who asked for less movement, the boxes are as filled as `filled` says
+Never for: A row beside another moving part in the same pane. One lead motion per pane
+
+### label — `string`
+
+Use when: Where the picture stands on its own — "A verification code, entered". It names the row as one image
+Never for: A row inside an IllustrationCard, which is one image named by its own label
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- it is never a field: nothing in it can be focused or typed into. Decoration unless `label` names it as one image, and its motion is never announced
+
+## 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, CardButton and TextInput simultaneously.
+  Guidance only — cannot be checked automatically.
+- **A page has at most one patterned band, between its hero and its closing call to action** — A patterned ground — the halftone, the aurora, the mesh, the grid or the rings — is what makes a band the one a reader stops at, and it only works by being the exception. So a page has at most one, placed between its hero and its closing call to action; the hero's and the call to action's own patterns are theirs and do not count, and the band never goes on either of them.
+
+The pattern is the band's first layer, under its content and over nothing. A block that can carry one says so with its own `background` prop — FeatureCards, Stats, TestimonialRow and LogoRows — and draws it there; a section built by hand places a Background with nothing in it as its first child. Never wrap a block in a Background: the block paints its own ground over the pattern and hides it.
+
+Only a band whose content is stacked can carry one. Every pattern rises from the band's foot, so the band needs a heading over what it introduces, centred, with the foot left open. A band whose content runs side by side — words beside a picture, a split, columns reaching the foot — puts the glow behind the picture or under the words; it stays on its flat ground.
+  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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
+
+## Anti-examples
+
+❌ IllustrationCode for: The reader types a code on this page
+   A real code is entered into a field a reader can focus; this is a picture of one and takes no input
+   → use `TextInput` instead.
+
+## Example
+
+```tsx
+import { IllustrationCode } from '@deriv-com/dds-marketing'
+
+<IllustrationCode length={6} />
+```
+
+## In use
+
+### How full
+
+All the boxes filled — a code entered — or the first few, as a still picture of one going in.
+
+```tsx
+import { IllustrationCode } from '@deriv-com/dds-marketing'
+
+// six, all filled
+<IllustrationCode length={6} />
+
+// six, three filled
+<IllustrationCode length={6} filled={3} />
+
+// four, all filled
+<IllustrationCode length={4} />
+```
+
+### Filling once on arrival
+
+The boxes fill one after another.
+
+```tsx
+import { IllustrationCode } from '@deriv-com/dds-marketing'
+
+// motion="fill"
+<IllustrationCode length={6} motion="fill" />
+```

package/.llm/components/illustrationlist.md

@@ -0,0 +1,175 @@
+<!-- GENERATED from illustration-list.contract.json. Do not edit. -->
+
+# IllustrationList
+
+A drawn list of rows — a glyph and a name each — for a picture of the product listing things.
+
+## Why it is built this way
+
+Rows down a column, ruled apart by a hairline: the markets a platform offers, the steps an account has, drawn the way the product lists them. Each child is one row, usually an Icon beside a Typography.
+
+It can arrive once: the rows come in one after another and each glyph pops in as its row lands, so a pane shows the list filling rather than a list already there. At rest, and for a reader who asked for less movement, it is simply the list.
+
+## Use when
+
+- A pane, or any picture of the product, listing a few things — the forex pairs on a platform, the documents a check needs
+- The list arriving is the point of the picture, played once with `motion="arrive"`
+
+## Do not use
+
+- A list of benefits or features the page itself is making → `FeatureBullets`
+- A data table the reader compares across → `Table`
+- More than five or six rows. A picture of a long list reads as a list to scroll, and its arrival as a page loading
+- Rows a reader acts on. Nothing in it can be pressed
+- More than one moving thing in a pane. One lead motion per pane
+
+## Anatomy
+
+IllustrationList renders 2 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-illustrationlist`. The column of rows. Under `motion="arrive"` it moves once on arrival (`data-arrival`): the rows come in a step of motion.duration.stagger apart over motion.duration.reveal, and any glyph in a row pops as it lands.
+- `row` — `<div>`, class `dds-illustrationlist__row`. One row, holding one child: padded by space.inset.xs top and bottom, and ruled from the row above by a hairline of color.border.subtle, which the first row does not carry.
+
+Apply these classes from the generated `illustrationListParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: any content
+- Never contains: `IllustrationList`, `IllustrationCard` — in children or in any prop that takes a node
+
+## Props
+
+### motion — `arrive`
+
+- `arrive` — The rows come in one after another, and each glyph pops in as its row lands
+
+Use when: The list moves once, on arrival — in an IllustrationCard when the pane has landed, otherwise when it is well into view. At rest, and for a reader who asked for less movement, the list is simply there
+Never for: A list beside another moving part in the same pane. One lead motion per pane
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- its rows are read as plain content, in order; its motion is never announced
+
+## 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, CardButton and TextInput simultaneously.
+  Guidance only — cannot be checked automatically.
+- **A page has at most one patterned band, between its hero and its closing call to action** — A patterned ground — the halftone, the aurora, the mesh, the grid or the rings — is what makes a band the one a reader stops at, and it only works by being the exception. So a page has at most one, placed between its hero and its closing call to action; the hero's and the call to action's own patterns are theirs and do not count, and the band never goes on either of them.
+
+The pattern is the band's first layer, under its content and over nothing. A block that can carry one says so with its own `background` prop — FeatureCards, Stats, TestimonialRow and LogoRows — and draws it there; a section built by hand places a Background with nothing in it as its first child. Never wrap a block in a Background: the block paints its own ground over the pattern and hides it.
+
+Only a band whose content is stacked can carry one. Every pattern rises from the band's foot, so the band needs a heading over what it introduces, centred, with the foot left open. A band whose content runs side by side — words beside a picture, a split, columns reaching the foot — puts the glow behind the picture or under the words; it stays on its flat ground.
+  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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
+
+## Anti-examples
+
+❌ IllustrationList for: A list of benefits or features the page itself is making
+   Words the page says to the reader are a section's list; this is a picture of a list inside the product
+   → use `FeatureBullets` instead.
+
+❌ IllustrationList for: A data table the reader compares across
+   Rows compared column by column are a table; these are a few names in a picture
+   → use `Table` instead.
+
+## Example
+
+```tsx
+import { IllustrationList, Typography } from '@deriv-com/dds-marketing'
+
+<IllustrationList>
+  <Typography variant="body-md">EUR/USD</Typography>
+  <Typography variant="body-md">GBP/USD</Typography>
+  <Typography variant="body-md">USD/JPY</Typography>
+</IllustrationList>
+```
+
+## In use
+
+### Arriving once
+
+The rows come in one after another; a glyph in a row pops in as its row lands.
+
+```tsx
+import { IllustrationList, Typography } from '@deriv-com/dds-marketing'
+
+// motion="arrive"
+<IllustrationList motion="arrive">
+  <Typography variant="body-md">EUR/USD</Typography>
+  <Typography variant="body-md">GBP/USD</Typography>
+  <Typography variant="body-md">USD/JPY</Typography>
+</IllustrationList>
+```

package/.llm/components/illustrationscene.md

@@ -2,6 +2,10 @@
 
 # IllustrationScene
 
+A photograph with an IllustrationCard laid over it.
+
+## Why it is built this way
+
 A photograph with an IllustrationCard laid over it — the product shown in the hands of the people who use it: a trade ticket over a trader on the move, a balance over someone at a desk. The scene owns how the two meet, so every such picture across a site is composed the same way: the photograph fills one of three shapes, and the glass card sits over it at a fixed share of the frame, centred or towards one edge.
 
 The photograph is the scene and the card is what it says. The card's `label` describes the whole picture to assistive technology; the photograph is decoration unless `alt` says otherwise.
@@ -21,10 +25,11 @@ The photograph is the scene and the card is what it says. The card's `label` des
 
 ## Anatomy
 
-IllustrationScene renders 2 elements. A token binding names the part it applies to.
+IllustrationScene renders 3 elements. A token binding names the part it applies to.
 
-- `root` — `<div>`, class `dds-illustrationscene`. The frame, and the shape: one of three proportions — the aspect tokens, the same three IllustrationCard takes — holding radius.surface like a Card and clipping the photograph to it. It places the card it holds over the photograph, at a share of its width that depends on the shape, so every scene across a site composes the same way.
+- `root` — `<div>`, class `dds-illustrationscene`. The frame, and the shape: one of three proportions — the aspect tokens, the same three IllustrationCard takes — holding radius.surface like a Card and clipping the photograph to it. It places the card it holds over the photograph, at a share of its width that depends on the shape, so every scene across a site composes the same way. At the foot the card is a strip at most two fifths of the frame tall, and the UI in it is scaled down to fit that, as a centred card's already is — so a narrow column never has the card bury its photograph or run off the top of it. Inside a block's arrival the scene arrives in two beats: the photograph with whatever holds it, the card three steps of motion.duration.stagger later, rising onto it.
 - `image` — `<img>`, class `dds-illustrationscene__image`. The photograph, filling the frame and cropped to it from the centre. Decoration unless `alt` says otherwise: the card's `label` already describes the whole picture, so most scenes leave the photograph out of the accessibility tree. While it loads, the frame shows color.bg.surface, so the card is never left floating on nothing.
+- `shade` — `<div>`, class `dds-illustrationscene__shade`. Under `shade`, a shade of color.bg.overlay between the photograph and the card, under the card only: up from the foot to just above a card at the foot and clear above it, or an oval behind a centred card and clear at the frame's edges. It is there for the card's small type, which on the glass over a bright photograph comes out below 4.5:1; the shade darkens what the glass blurs rather than the whole photograph. Decoration, with nothing in it. Rendered only when `shade` is set.
 
 Apply these classes from the generated `illustrationSceneParts` constant rather than writing the strings by hand.
 
@@ -51,7 +56,7 @@ Never for: Fitting a particular photograph. The shape is a decision about the la
 - `bottom` — The card centred along the foot of the frame, held off it by the card's own inset — for a photograph whose subject fills the top: a face, a person reaching up, a skyline
 
 Use when: Where the card sits over the photograph, so the subject of the photograph stays clear of it
-Never for: Anything but keeping the photograph's subject clear. The card's size is fixed by the shape; placement moves it and nothing else
+Never for: Anything but keeping the photograph's subject clear. The card's width is fixed by the shape; placement moves it, and at the foot holds it to at most two fifths of the frame's height
 
 ### src — `string` **Required.**
 
@@ -63,6 +68,11 @@ Never for: A data URI holding a photograph. A scene's photograph is the heaviest
 Use when: Empty by default, because the card's `label` describes the whole picture and the photograph is decoration. Write one only where the photograph says something the label does not
 Never for: Repeating the card's label. A screen reader would hear the picture described twice
 
+### shade — `boolean` (default `false`)
+
+Use when: The photograph is bright where the card sits — a sunny sky, a white wall — so the glass would come out mid-grey and the card's small lines would fall below AA. A shade under the card only, following the card's placement, so the rest of the photograph keeps its light.
+Never for: A photograph already dark where the card sits, or darkening the whole photograph. The shade is for the card's type, and on a dark photograph it only takes light out of the scene.
+
 Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
 
 ## Accessibility
@@ -88,6 +98,12 @@ What this is not about is every row of controls. A set of filter chips, a pagina
   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, CardButton and TextInput simultaneously.
   Guidance only — cannot be checked automatically.
+- **A page has at most one patterned band, between its hero and its closing call to action** — A patterned ground — the halftone, the aurora, the mesh, the grid or the rings — is what makes a band the one a reader stops at, and it only works by being the exception. So a page has at most one, placed between its hero and its closing call to action; the hero's and the call to action's own patterns are theirs and do not count, and the band never goes on either of them.
+
+The pattern is the band's first layer, under its content and over nothing. A block that can carry one says so with its own `background` prop — FeatureCards, Stats, TestimonialRow and LogoRows — and draws it there; a section built by hand places a Background with nothing in it as its first child. Never wrap a block in a Background: the block paints its own ground over the pattern and hides it.
+
+Only a band whose content is stacked can carry one. Every pattern rises from the band's foot, so the band needs a heading over what it introduces, centred, with the foot left open. A band whose content runs side by side — words beside a picture, a split, columns reaching the foot — puts the glow behind the picture or under the words; it stays on its flat ground.
+  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.
@@ -227,3 +243,17 @@ import { IllustrationScene } from '@deriv-com/dds-marketing'
 // bottom
 <IllustrationScene ratio="square" src="/sample-card-image.svg" placement="bottom">{illustrationcards}</IllustrationScene>
 ```
+
+### A shade for a bright photograph
+
+shade darkens under the card only, so its small type keeps AA over a bright photograph and the rest keeps its light.
+
+```tsx
+import { IllustrationScene } from '@deriv-com/dds-marketing'
+
+// bottom, shade
+<IllustrationScene ratio="square" src="/sample-banner-art.svg" placement="bottom" shade>{illustrationcards}</IllustrationScene>
+
+// center, shade
+<IllustrationScene ratio="square" src="/sample-banner-art.svg" placement="center" shade>{illustrationcards}</IllustrationScene>
+```

package/.llm/components/imagebanner.md

@@ -2,6 +2,10 @@
 
 # ImageBanner
 
+A dark card pairing a headline and one action with a photograph.
+
+## Why it is built this way
+
 A dark card in the middle of a page, pairing a headline and a line under it with a photograph — beside it or behind it, with one action.
 
 The reference site's ImageBanner, and a break rather than an opening: a dark, editorial moment between lighter sections that asks for one thing. The card is dark on every ground; `ground` paints the band it sits in, the way it does for every block.
@@ -27,8 +31,8 @@ ImageBanner renders 8 elements. A token binding names the part it applies to.
 
 - `root` — `<section>`, class `dds-imagebanner`. The section. It paints one of the page's three grounds and the ink that goes with it — see `ground` — and asks its own width, so the card folds on the section's measure rather than the window's. A region named by its headline.
 - `inner` — `<div>`, class `dds-imagebanner__inner`. The measure and the gutter, the same column every band holds its content in. On a phone the card gives up the gutter and runs the width of the screen, as the reference design's does.
-- `card` — `<div>`, class `dds-imagebanner__card`. The dark card holding everything: color.bg.brand-strong, or color.bg.surface-card-strong on the dark band so it is still a card there, with white ink on both. It clips the photograph to its rounded corners. From 48rem the words and the photograph sit side by side, in the order `mediaPosition` names; below it they stack.
-- `content` — `<div>`, class `dds-imagebanner__content`. The headline, the line under it and the action, inset from the card's edge. It sets no gap of its own: the step from a title to its description and the step from a description to what follows are two roles, carried by each part's own margin.
+- `card` — `<div>`, class `dds-imagebanner__card`. The dark card holding everything: color.bg.brand-strong, or color.bg.surface-card-strong-on-brand-strong on the dark band so it is still a card there, with white ink on both. It clips the photograph to its rounded corners. From 48rem the words and the photograph sit side by side, in the order `mediaPosition` names; below it they stack.
+- `content` — `<div>`, class `dds-imagebanner__content`. The headline, the line under it and the action, inset from the card's edge. It sets no gap of its own: the step from a title to its description and the step from a description to what follows are two roles, carried by each part's own margin. On a cover card it lays the shade under its words: color.bg.overlay across the column the words take, fading to clear from the words' end to space.section.default past the column's edge toward the photograph — across from the fold, downward on a phone — and nothing beyond that, so the photograph keeps its light everywhere the words are not.
 - `title` — `<h2>`, class `dds-imagebanner__title`. The headline. `h2` by default because the card sits under the page's own heading; `headingLevel` moves the level and never the size. Drawn at font.h2.
 - `description` — `<p>`, class `dds-imagebanner__description`. The line under the headline, at the body step and the description measure. Rendered only when `description` is set.
 - `action` — `<div>`, class `dds-imagebanner__action`. The one action, under the line. On a phone it fills the width of the card; from 48rem it is its own size. Rendered only when `action` is set.
@@ -47,7 +51,7 @@ Apply these classes from the generated `imageBannerParts` constant rather than w
 
 - `page` — The default, and the page's own white, with the dark card set into it. Most of the time: the card is already the break
 - `subtle` — The grey band, for a card that follows a white section the page wants told apart from this one. Painted as the band's tint laid over the page's own ground, so it is the same grey whatever is behind the section
-- `strong` — `color.bg.brand-strong`, the dark band, with the card a step lighter at color.bg.surface-card-strong so it still reads as a card. For a page whose dark band is already here and wants the card inside it
+- `strong` — `color.bg.brand-strong`, the dark band, with the card a step lighter at color.bg.surface-card-strong-on-brand-strong so it still reads as a card. For a page whose dark band is already here and wants the card inside it
 
 Use when: Which of the page's three grounds the band around the card paints. The card is dark whatever this says — that is what the block is — so this is about the rhythm of the page, white, grey or dark, and never about the card. The ink follows the ground and is not a second decision.
 Never for: Making the card darker. The card is dark on every ground; painting the band dark too spends the page's one dark band on a section that was already one.
@@ -55,10 +59,10 @@ Never for: Making the card darker. The card is dark on every ground; painting th
 ### variant — `split` | `cover` (default `split`)
 
 - `split` — The default. The words in one half and the photograph filling the other, edge to edge, with one action under the words. On a phone the card runs the width of the screen and the photograph stacks with the words
-- `cover` — The photograph fills the whole card, with the words over it behind a scrim that darkens the side they are on and leaves the photograph clear on the other. For a photograph wide enough to be the band rather than half of it
+- `cover` — The photograph fills the whole card, with the words over it on a shade that darkens the words' own column and fades out just past it, leaving the rest of the photograph clear. For a photograph wide enough to be the band rather than half of it
 
 Use when: What the photograph does: beside the words, or behind them. Both carry one action — two of the reference design's layouts.
-Never for: Choosing by how busy the page looks. Cover hides part of the photograph under the scrim; it is a decision about the photograph, not decoration.
+Never for: Choosing by how busy the page looks. Cover lays the words on part of the photograph behind a shade; it is a decision about the photograph, not decoration.
 
 ### mediaPosition — `end` | `start` (default `end`)
 
@@ -100,9 +104,14 @@ Never for: Artwork with words in it. The cover photograph sits under a scrim and
 
 ### parallax — `boolean` (default `true`)
 
-Use when: The photograph drifts against the scroll as the card passes through the view, by motion.distance.drift over the whole pass, so it reads as further away than the card — the reference design's ParallaxBanner, which this replaces. On by default, as every block's picture drifts: pass false for a card whose photograph must hold still under its button.
+Use when: The photograph drifts against the scroll as the card passes through the view, the drift every block's picture shares — drawn at motion.scale.parallax and moved from motion.translate.parallax-from to motion.translate.parallax-to over the whole pass — so it reads as further away than the card — the reference design's ParallaxBanner, which this replaces. On by default, as every block's picture drifts: pass false for a card whose photograph must hold still under its button.
 Never for: Holding still for a reader who asked for less motion — it already holds still for them, and in a browser that cannot drive it from the scroll.
 
+### stackOnPhone — `boolean` (default `false`)
+
+Use when: A cover photograph whose subject a phone's crop would put under the words or cut off — a person, a face, hands. On a phone the words stand on the card's own dark ground and the photograph follows them at the landscape shape, whole and clear; from the fold it is the cover card as before.
+Never for: A split card, which stacks on a phone already, or a photograph that is setting rather than subject. Stacked, the phone loses the cover look, so keep it for the photograph that would otherwise lose its subject.
+
 ## 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.
@@ -128,6 +137,12 @@ What this is not about is every row of controls. A set of filter chips, a pagina
   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, CardButton and TextInput simultaneously.
   Guidance only — cannot be checked automatically.
+- **A page has at most one patterned band, between its hero and its closing call to action** — A patterned ground — the halftone, the aurora, the mesh, the grid or the rings — is what makes a band the one a reader stops at, and it only works by being the exception. So a page has at most one, placed between its hero and its closing call to action; the hero's and the call to action's own patterns are theirs and do not count, and the band never goes on either of them.
+
+The pattern is the band's first layer, under its content and over nothing. A block that can carry one says so with its own `background` prop — FeatureCards, Stats, TestimonialRow and LogoRows — and draws it there; a section built by hand places a Background with nothing in it as its first child. Never wrap a block in a Background: the block paints its own ground over the pattern and hides it.
+
+Only a band whose content is stacked can carry one. Every pattern rises from the band's foot, so the band needs a heading over what it introduces, centred, with the foot left open. A band whose content runs side by side — words beside a picture, a split, columns reaching the foot — puts the glow behind the picture or under the words; it stays on its flat ground.
+  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.
@@ -205,6 +220,9 @@ Two things genuinely have no logical form and are not covered by this. A CSS gra
    A list of features is the content there, ruled lines a reader goes down; this card is a photograph and one action
    → use `FeatureBullets` instead.
 
+❌ variant=split + stackOnPhone=true
+   A split card already stacks its words and its photograph on a phone; there is nothing for this to change.
+
 ## Example
 
 ```tsx
@@ -276,3 +294,14 @@ import { AspectRatio, ImageBanner, Link } from '@deriv-com/dds-marketing'
 // Inside a section that has its h2 — headingLevel h3
 <ImageBanner variant="split" parallax title="Life at Deriv" description="We combine human values with AI precision. Collaboration, integrity and continuous learning guide every project, in every office and every time zone." action={<Link href="/careers/culture" tone="inherit">Culture at Deriv</Link>} media={<AspectRatio ratio="landscape" />} headingLevel="h3" />
 ```
+
+### Stacked on a phone
+
+stackOnPhone: below the fold the words stand on the card and the photograph follows them whole, so a person framed for the desktop strip keeps their head.
+
+```tsx
+import { AspectRatio, Button, ImageBanner } from '@deriv-com/dds-marketing'
+
+// cover, stackOnPhone
+<ImageBanner variant="cover" title="Trade on Deriv MT5" description="Forex, stocks, commodities and derived indices on the platform professionals use, with charting and order types built in." action={<Button variant="primary" tone="inverse" href="/platforms/deriv-mt5">Open a Deriv MT5 account</Button>} media={<AspectRatio ratio="landscape" />} stackOnPhone />
+```

package/.llm/components/landinghero.md

@@ -2,6 +2,10 @@
 
 # LandingHero
 
+Opens a main landing page with its headline over a dark background.
+
+## Why it is built this way
+
 The band that opens a main landing page: the one thing the page is about, said once, at the top, over a ground dark enough that nothing above it competes.
 
 One of three opening bands, and the widest. Which one a page takes follows from where the page sits rather than from a prop — this is the landing tier, the front page and the campaign pages under it.
@@ -133,6 +137,12 @@ What this is not about is every row of controls. A set of filter chips, a pagina
   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, CardButton and TextInput simultaneously.
   Guidance only — cannot be checked automatically.
+- **A page has at most one patterned band, between its hero and its closing call to action** — A patterned ground — the halftone, the aurora, the mesh, the grid or the rings — is what makes a band the one a reader stops at, and it only works by being the exception. So a page has at most one, placed between its hero and its closing call to action; the hero's and the call to action's own patterns are theirs and do not count, and the band never goes on either of them.
+
+The pattern is the band's first layer, under its content and over nothing. A block that can carry one says so with its own `background` prop — FeatureCards, Stats, TestimonialRow and LogoRows — and draws it there; a section built by hand places a Background with nothing in it as its first child. Never wrap a block in a Background: the block paints its own ground over the pattern and hides it.
+
+Only a band whose content is stacked can carry one. Every pattern rises from the band's foot, so the band needs a heading over what it introduces, centred, with the foot left open. A band whose content runs side by side — words beside a picture, a split, columns reaching the foot — puts the glow behind the picture or under the words; it stays on its flat ground.
+  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.