@deriv-com/dds-marketing 1.0.2 → 1.1.1

package/.llm/components/stickycards.md

@@ -0,0 +1,251 @@
+<!-- GENERATED from sticky-cards.contract.json. Do not edit. -->
+
+# StickyCards
+
+A section whose cards pile up as the page scrolls: a heading, and under it a set of cards that each stop near the top of the window while the next one slides up over them, so the cards are read one at a time and the edges of the ones already read stay showing above the one being read. A covered card draws back a little and darkens as the next one crosses it, which is what makes the pile read as depth.
+
+Two layouts. `compact` is the reference design's StickyMarketCards: text-first cards in a column held to the heading's measure, any number of them, a picture or an animation beside the words where a card has one, and at most four edges showing however long the set is. `feature` is its StickyStackedCards: a few large cards the width of the page, each its words beside a picture filling its half from the fold.
+
+The pile is CSS — `position: sticky`, and a scroll timeline for the drawing back — so nothing waits for a script. Where the browser has no scroll timeline the cards still pile, without drawing back. A reader who asked for less motion, or a window too short to hold a card, gets the cards as a plain column, every one in full.
+
+The reference design's StickyMarketCards, StickyMarketCardsLottie and StickyStackedCards, as one block.
+
+## Use when
+
+- A set of markets, products or benefits a page wants read one at a time as the reader scrolls — the reference design's "What we offer" — where each is a title and a sentence, and a picture or an animation is optional
+- Three steps or benefits that each need a picture of their own — Sign up, Deposit, Trade — told as a sequence the reader scrolls through rather than a row they compare
+
+## Do not use
+
+- Three or four things a reader should compare side by side, at a glance → `FeatureCards`
+- Several things of the same kind, each with a picture worth a screen and room for more than a sentence → `FeatureScroll`
+- One or two items → nothing here does this
+- Anything the reader must see at once — terms, prices compared across plans, a risk warning. A covered card is out of sight until the reader scrolls back to it
+- Cards a reader presses. The pile covers each card as the next arrives, and a control under another card is one the eye cannot find; a card's way on belongs in the section after it
+- The page's opening band. This sits under the page's heading, never in place of it
+
+## Anatomy
+
+StickyCards renders 12 elements. A token binding names the part it applies to.
+
+- `root` — `<section>`, class `dds-stickycards`. The section. It paints the ground and the ink to go with it — see `ground` — and asks its own width, so the cards fold on the section's measure rather than the window's. A region named by its heading. Nothing between it and the page may clip with `overflow: hidden`: that makes a box a scroll container, which unpins the cards and freezes their timelines.
+- `inner` — `<div>`, class `dds-stickycards__inner`. The measure and the gutter, the same column every band holds its content in, and the step from the heading to the cards: space.heading.content.
+- `header` — `<div>`, class `dds-stickycards__header`. The heading and the line under it. Ranged to the start on a phone and centred from the fold in both layouts — both references turn at 768px — FeatureCards' header and its reason: the cards are stacked under it. It sets no gap: the title's own margin is the step, so a header without a line closes up.
+- `title` — `<h2>`, class `dds-stickycards__title`. What the set is. `h2` because a section sits under the page's own heading; each card's title comes below it in the outline as an `h3`.
+- `description` — `<p>`, class `dds-stickycards__description`. The line under the heading, at the description measure. Rendered only when `description` is set.
+- `list` — `<ul>`, class `dds-stickycards__list`. The cards, a list a screen reader counts — `role="list"` said outright, because Safari drops a list's role once its markers are styled away. One column, every row as tall as the tallest card, so each card hides the one under it completely and only the edges show. Held to size.sticky-cards.compact-max and centred in `compact`, the page's measure in `feature`. Its rows are space.grid.gutter apart, the room each card is read in before the next one reaches it.
+- `item` — `<li>`, class `dds-stickycards__item`. One card's place in the pile. Sticky where the pile runs: it stops under the room a navigation bar takes, space.pile.peek lower than the card before it, so the edge of each covered card shows. Past four cards the earliest share the first card's place, so no more than four edges show. Once the next card starts across it, it draws back by motion.scale.pile-covered from its top edge, scrubbed by the scroll. While anything inside it has focus it comes to the top of the pile and stands at full size, so focus is never behind another card. It holds a Card at the variant the record names, filling it.
+- `backdrop` — `<span>`, class `dds-stickycards__backdrop`. A `compact` card's background photograph, behind the whole card under an 72% wash of the card's own fill, so the words keep their contrast and the picture reads as texture — the reference design's market cards. Rounded with the card. Drawn only for a card with a `background`, and only in `compact`.
+- `body` — `<div>`, class `dds-stickycards__body`. Inside the Card, its one child: a CardBody holding the title (`h3`) and the sentence, and after it the picture. The words come first in reading order on every screen. Stacked on a phone; from the fold the words and the picture sit side by side — the words at the start — and a `compact` card with no picture sets its title beside its sentence instead, the reference design's two columns.
+- `media` — `<div>`, class `dds-stickycards__media`. Where a card's picture goes, or the player the `media` callback returns for it. In `compact` it is a landscape container, aspect.landscape, inset from the card's edges and rounded at radius.surface-compact — beside the words from the fold, under them on a phone — and the picture fills it, cropped to fill; a player stretches to it. In `feature` it reaches the card's edges and fills its half, cropped to fill — landscape on a phone. Drawn only for a card with a picture or a player.
+- `image` — `<img>`, class `dds-stickycards__image`. The card's picture, with the record's `alt`, its width and height so its shape is held before it loads, and loaded lazily. Rounded with the media in `compact`, square-cornered in `feature`, where the card's own corner clips it. Not drawn when `media` returns a player for the card.
+- `scrim` — `<span>`, class `dds-stickycards__scrim`. The darkening a covered card takes: color.bg.overlay laid over the whole card at the card's corner, faded in from nothing as the next card crosses it. Drawn only where the pile animates — no scroll timeline, or a reader who asked for less motion, and it is not shown at all. Empty, so it says nothing to a screen reader, and never in the way of a pointer.
+
+Apply these classes from the generated `stickyCardsParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `StickyCards`, `LandingHero`, `ProductHero`, `PageHeader`, `Footer`, `Navbar` — in children or in any prop that takes a node
+
+## Props
+
+### ground — `page` | `subtle` | `strong` (default `page`)
+
+- `page` — The default, and the page's own white. The reference design's sticky stacked cards sit on it
+- `subtle` — A quiet step off the page — the reference design's slate band, which its market cards sit on. Painted as the band's tint laid over the page's own ground; the light and dark cards are raised a step so their edges do not sink into it, FeatureCards' answer
+- `strong` — `color.bg.brand-strong`, the dark band, for a section a reader should arrive at. The heading turns white; a dark card on it is told apart by its edge in the pile more than by its fill, so alternate the cards
+
+Use when: Which of the page's three grounds this section paints, and with it the ink of the heading. The cards keep their own fills on every ground. A page builds its rhythm from these, and the section above knows nothing about the one below it, so the page is the only thing that can decide.
+Never for: Marking importance. Every section on a page painted a ground is a page with no emphasis left. And never the brand's coral, `color.bg.brand`, which is not offered: that ground belongs to the band that asks a reader to do something.
+
+### layout — `compact` | `feature` (default `compact`)
+
+- `compact` — The default — the reference design's StickyMarketCards and their animation sibling. Cards held to the heading's measure, at least size.sticky-cards.compact-min tall, the title at the card's own step: a photograph behind the card where it has a `background`, and a landscape container beside the words from the fold — under them on a phone — for its `image` or the page's player. With neither, the title beside its sentence. Any number of cards, three or more; past four, the earliest share an edge so no more than four ever show
+- `feature` — The reference design's StickyStackedCards — about three large cards, each the width of the page and at least size.sticky-cards.feature-min tall, the title at the h3 step, its words beside a picture that runs to the card's edges and fills its half from the fold, under them on a phone. Give every card an `image` or a `media`: a card here without one is words beside an empty half
+
+Use when: Which pile this is: text-first cards in a narrow column, or a few large cards the width of the page with a picture each.
+
+### title — `string` **Required.**
+
+Use when: Always. What the set is, in the fewest words — "What we offer", "Start trading in minutes". It names the section as a region, so a screen reader can jump to it and past it.
+Never for: A sentence. The line under it is for the sentence.
+
+### description — `string`
+
+Use when: A line saying what the cards have in common, when the title alone does not.
+Never for: A paragraph, or an introduction to each card. The cards say what each one is.
+
+### cards — `data` `StickyCardsItem[]` **Required.**
+
+Use when: Always. The cards, in the order the reader meets them — the first is the first one covered, the last ends the pile on top. Each has a title, a sentence, a fill (`variant`), and where it has them an `image` — the card's container in `compact`, its half in `feature` — and in `compact` a `background` photograph under the card's wash. Every card is drawn the height of the tallest, so the pile covers cleanly: keep the descriptions about the same length. An empty list draws the heading alone. A picture on every card or on none: a pile is one set, and it takes one arrangement — words beside the picture, or, where no card has one, each title beside its sentence. A card left without a picture in a pile of pictured cards keeps its words stacked at the top like the rest, beside an empty half.
+Never for: A card a reader has to press, or one or two cards. See the block's own guidance. Mixing cards with and without a picture in one pile. Give every card one, or none.
+
+### media — `callback`
+
+Use when: A card shows something the page plays itself — a Lottie animation, a video — in the place its picture would take, the reference design's StickyMarketCardsLottie. Given each card and its place in the list, return the player for that card, or nothing to fall back to the card's `image`. The block ships no player of its own and imports none: the page mounts its own. The slot is the picture's place — beside the words from the fold, under them on a phone — and the player should fill it: landscape in `compact`, the whole half in `feature`.
+Never for: A control that only works while its card is on top, or anything a reader must press to read the card. Whatever this returns is covered when the next card arrives; a focusable control in it brings its card to the top of the pile while it has focus, but a reader scrolling past never sees it. Start an animation on its own, paused under reduced motion, rather than behind a play button.
+
+## 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: `region`
+- `Tab` — The block has no controls of its own and adds no tab stop. Anything focusable a page renders through `media` is reached in reading order, card by card, and the card holding it comes to the top of the pile while it has focus.
+- accessible name from title, so the section is a named region a screen reader can jump to and skip
+- The cards are a list with role="list", each card's title an h3 under the section's h2, so the set is counted and a reader can move card to card.
+- Reading order is the order the cards are drawn in, words before the picture in every card, and no card is hidden from assistive technology while it is covered: the pile is a picture of the list, not a reveal of it.
+- A card holding focus is never covered: it comes to the top of the pile and stands at full size until focus leaves it.
+- A reader who asked for less motion gets no pile and no drawing back: the cards as a plain column, every one in full.
+
+## 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 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
+
+❌ StickyCards for: Three or four things a reader should compare side by side, at a glance
+   A pile shows one card at a time and covers the rest; cards that are compared need to be seen together
+   → use `FeatureCards` instead.
+
+❌ StickyCards for: Several things of the same kind, each with a picture worth a screen and room for more than a sentence
+   A card in a pile is the height of the tallest one in it, and covered as soon as the next arrives; a long explanation needs a band that stays put while it is read
+   → use `FeatureScroll` instead.
+
+❌ StickyCards for: One or two items
+   A pile of one is a card, and two cards one over the other is a transition with nothing to stack. Lay them out as a FeatureSplit or a pair of FeatureCards instead
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+## Example
+
+```tsx
+import { StickyCards } from '@deriv-com/dds-marketing'
+
+<StickyCards title="What we offer" description="A full suite of markets, all in one place." cards={[{"title":"Forex","description":"Trade the world’s major and minor currency pairs with tight spreads.","variant":"accent-strong"},{"title":"Commodities","description":"Gold, oil and more — trade global commodities.","variant":"accent"},{"title":"Derived indices","description":"Markets that run around the clock, every day of the year.","variant":"accent-strong"},{"title":"Stocks and indices","description":"Get exposure to the world’s largest companies and markets.","variant":"surface-light"}]} />
+```
+
+## In use
+
+### Two layouts
+
+Compact piles any number of text-first cards in a narrow column; feature piles about three large cards, each its words beside a picture filling its half.
+
+```tsx
+import { StickyCards } from '@deriv-com/dds-marketing'
+
+// Compact, words alone
+<StickyCards title="What we offer" layout="compact" cards={[{"title":"Forex","description":"Trade the world’s major and minor currency pairs with tight spreads.","variant":"accent-strong"},{"title":"Commodities","description":"Gold, oil and more — trade global commodities.","variant":"accent"},{"title":"Derived indices","description":"Markets that run around the clock, every day of the year.","variant":"accent-strong"},{"title":"Stocks and indices","description":"Get exposure to the world’s largest companies and markets.","variant":"surface-light"}]} />
+
+// Feature, a picture on every card
+<StickyCards title="Start trading in minutes" layout="feature" cards={[{"title":"Sign up","description":"Create a free account in minutes with just your email.","variant":"surface-light","image":{"src":"/sample-card-image.svg","alt":"","width":800,"height":600}},{"title":"Deposit","description":"Fund your account with the payment method that suits you.","variant":"accent","image":{"src":"/sample-aspect-art.svg","alt":"","width":1200,"height":1200}},{"title":"Trade","description":"Pick a market and place your first trade.","variant":"accent-strong","image":{"src":"/sample-tall-image.svg","alt":"","width":600,"height":900}}]} />
+```
+
+### A background and a container
+
+Compact cards: a photograph behind the card under its wash, and a landscape container beside the words — under them on a phone.
+
+```tsx
+import { StickyCards } from '@deriv-com/dds-marketing'
+
+// Background, wash and container
+<StickyCards title="What we offer" layout="compact" cards={[{"title":"Forex","description":"Trade the world’s major currency pairs with tight spreads.","variant":"accent-strong","background":{"src":"/sample-card-image.svg","alt":"","width":1600,"height":900},"image":{"src":"/sample-card-image.svg","alt":"","width":800,"height":600}},{"title":"Commodities","description":"Gold, oil and more, around the clock.","variant":"accent","background":{"src":"/sample-card-image.svg","alt":"","width":1600,"height":900},"image":{"src":"/sample-card-image.svg","alt":"","width":800,"height":600}},{"title":"Stocks","description":"Get exposure to the world’s largest companies.","variant":"surface-light","background":{"src":"/sample-card-image.svg","alt":"","width":1600,"height":900},"image":{"src":"/sample-card-image.svg","alt":"","width":800,"height":600}}]} />
+```
+
+### Card fills
+
+The dark card is the default; coral for a title and a short sentence; the light card stays light in both themes. Alternate them so each edge reads.
+
+```tsx
+import { StickyCards } from '@deriv-com/dds-marketing'
+
+// Dark, coral and light
+<StickyCards title="What we offer" cards={[{"title":"Forex","description":"Trade the world’s major and minor currency pairs with tight spreads.","variant":"accent-strong"},{"title":"Commodities","description":"Gold, oil and more — trade global commodities.","variant":"accent"},{"title":"Stocks and indices","description":"Get exposure to the world’s largest companies and markets.","variant":"surface-light"}]} />
+```
+
+### Grounds
+
+The page's three grounds. The cards keep their fills on each; the light and dark cards lift a step on the subtle band.
+
+```tsx
+import { StickyCards } from '@deriv-com/dds-marketing'
+
+// Page
+<StickyCards title="What we offer" ground="page" cards={[{"title":"Forex","description":"Trade the world’s major and minor currency pairs with tight spreads.","variant":"accent-strong"},{"title":"Commodities","description":"Gold, oil and more — trade global commodities.","variant":"accent"},{"title":"Derived indices","description":"Markets that run around the clock, every day of the year.","variant":"accent-strong"}]} />
+
+// Subtle
+<StickyCards title="What we offer" ground="subtle" cards={[{"title":"Forex","description":"Trade the world’s major and minor currency pairs with tight spreads.","variant":"accent-strong"},{"title":"Commodities","description":"Gold, oil and more — trade global commodities.","variant":"accent"},{"title":"Derived indices","description":"Markets that run around the clock, every day of the year.","variant":"accent-strong"}]} />
+
+// Strong
+<StickyCards title="What we offer" ground="strong" cards={[{"title":"Commodities","description":"Gold, oil and more — trade global commodities.","variant":"accent"},{"title":"Derived indices","description":"Markets that run around the clock, every day of the year.","variant":"accent-strong"},{"title":"Stocks and indices","description":"Get exposure to the world’s largest companies and markets.","variant":"surface-light"}]} />
+```

package/.llm/components/tableheadercell.md

@@ -104,6 +104,14 @@ Never for: Marking a group. A missing line is not a heading — a table that wan
 - `upper` — The house setting. Column names in capitals at font.overline — eleven pixels with wide tracking — which reads as a different texture from the values rather than a louder version of them. A header is read once where the data under it is read many times, and capitals are what stop it competing
 - `title` — Names drawn as they were written, at font.label.sm — twelve pixels, medium, ordinary tracking. Right where the names are long, are proper nouns whose own capitals capitals would flatten, or are in a script that has no case at all, and right wherever a product has decided its tables read as sentences rather than as labels
 
+### scope — `col` | `row` (default `col`)
+
+- `col` — The default. A name in the header row, announced before every value beneath it
+- `row` — The first cell of a data row when that cell is what the row is about — an instrument, a plan, a country — rather than one more value in it. It sits in the body, in a TableRow, where a TableCell would otherwise go
+
+Use when: Which way the cell names: down its column, the usual case, or across its row. A row header is the cell that says what a row is — the market in a list of instruments — and a screen reader announces it before every value in that row, the way it announces a column's name before every value under it.
+Never for: A row header that can be sorted. Sorting orders rows by a column, so the control belongs on the column's name in the header row, never on the name of one row
+
 ### sortable — `boolean` (default `false`)
 
 Use when: The reader can order the table by this column. It draws the control and the mark; what pressing it does is the page's, reported through `onSort`
@@ -304,3 +312,14 @@ import { TableHeaderCell } from '@deriv-com/dds-marketing'
 // title — as written
 <TableHeaderCell headerCase="title">Name</TableHeaderCell>
 ```
+
+### Naming a row
+
+The first cell of a data row when it is what the row is about — a market, a plan. Announced before every value in its row, the way a column's name is before every value under it.
+
+```tsx
+import { TableHeaderCell } from '@deriv-com/dds-marketing'
+
+// scope="row" — the row's name
+<TableHeaderCell scope="row">EUR/USD</TableHeaderCell>
+```

package/.llm/components/teamgrid.md

@@ -0,0 +1,243 @@
+<!-- GENERATED from team-grid.contract.json. Do not edit. -->
+
+# TeamGrid
+
+A section that sets out the people behind a company: a heading, and a grid of people under it — each a square photograph, their name, what they do and, where they have one, a link to a profile of theirs elsewhere. The first few show at once, and a button under the grid shows the rest and hides them again.
+
+One column on a phone, two from the fold and four at full width, so the first four people are one row on a desktop and the button under that row is what makes the list longer.
+
+The reference design's Leaders template — AvatarGrid in its source.
+
+## Use when
+
+- A leadership team, an advisory board or a regional management list on an about page
+- A responsive grid of person/profile cards — photo, name, role, and an optional external profile link — with an optional line under its heading and a "View all" that shows the rest of a longer list
+
+## Do not use
+
+- One person, spotlit, in their own words → `TestimonialSlider`
+- The items are not people — logos, features, figures → `FeatureCards`
+- People who are not who the card says. A name, a face and a role are a claim about a real person — keep each in step with the person, and leave the profile link out unless it is theirs
+- The page's opening band. This sits under the page's heading, never in place of it
+
+## Anatomy
+
+TeamGrid renders 14 elements. A token binding names the part it applies to.
+
+- `root` — `<section>`, class `dds-teamgrid`. The section. It paints the ground and the ink to go with it — see `ground` — and asks its own width, so the grid folds on the section's measure rather than the window's. A region named by its heading.
+- `inner` — `<div>`, class `dds-teamgrid__inner`. The measure and the gutter, the same column every band holds its content in, and the step from the heading to the grid: space.heading.content.
+- `header` — `<div>`, class `dds-teamgrid__header`. The heading and the line under it. Ranged to the start on a phone and centred from the fold, FeatureCards' header and its reason. It sets no gap: the title's own margin is the step, so a header without a line closes up.
+- `title` — `<h2>`, class `dds-teamgrid__title`. Who these people are. `h2` because a section sits under the page's own heading; each person's name comes below it in the outline.
+- `description` — `<p>`, class `dds-teamgrid__description`. The line under the heading, at the description measure. Rendered only when `description` is set.
+- `people` — `<div>`, class `dds-teamgrid__people`. The grid and the button under it, held together at space.gap.xl — closer than the section's step from the heading, so the button reads as belonging to the list it lengthens.
+- `list` — `<ul>`, class `dds-teamgrid__list`. The people, a list a screen reader counts. One column on a phone, two from the fold and four at full width, at space.grid.gutter across and down. Its id is what the button controls. The people past `collapsedCount` are in it from the first render and hidden — gone from the page, the accessibility tree and the tab order alike — until the button shows them.
+- `item` — `<li>`, class `dds-teamgrid__item`. One person: the photograph over the words, at space.gap.md — closer than the grid's gutter between people, so a name reads as its own photograph's and never as the next one's. No fill and no inset of its own — the reference design sets the people straight on the section's ground, and the photograph's corners are the card's only edge. A person the button shows fades and rises into place a step behind the one before; under reduced motion they are simply there.
+- `media` — `<div>`, class `dds-teamgrid__media`. The photograph's frame, holding an AspectRatio at `square` — the reference design's 1:1 — so every face in the grid is the same shape whatever was uploaded, rounded at radius.surface. Its fill is the grey a picture sits on while it loads, and it follows the ground.
+- `text` — `<div>`, class `dds-teamgrid__text`. The name, the role and the profile link at space.gap.xs: one block of words under the picture.
+- `name` — `<h3>`, class `dds-teamgrid__name`. Who they are, at the smallest heading step. `h3`, under the section's `h2`, so a reader moving by heading moves person to person.
+- `role` — `<p>`, class `dds-teamgrid__role`. What they do, at the body step and quieter than the name: muted on the page and the grey band, the band's own quieter ink on the dark one.
+- `profile` — `<div>`, class `dds-teamgrid__profile`. A standalone Link to a profile of theirs elsewhere — LinkedIn — opening in a new tab with the external mark that says so. Named for the person as well as the site, see `profileName`, and at least size.target.min tall. Brand ink on the page and the grey band, the band's ink on the dark one. Drawn only for a person who gives a `profile`.
+- `actions` — `<div>`, class `dds-teamgrid__actions`. The button that shows the rest of the list and hides it again — Button in its secondary variant at md, `aria-expanded` saying which and `aria-controls` naming the list. Full width on a phone, the rule for a section's actions; its own width and centred from the fold. Drawn only when there are more people than `collapsedCount`.
+
+Apply these classes from the generated `teamGridParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `TeamGrid`, `LandingHero`, `ProductHero`, `PageHeader`, `Footer`, `Navbar` — in children or in any prop that takes a node
+
+## Props
+
+### ground — `page` | `subtle` | `strong` (default `page`)
+
+- `page` — The default, and the page's own white. Most people sections have nothing to separate themselves from
+- `subtle` — A quiet step off the page — the reference design's slate band — for a section that wants to read as its own. Painted as the band's tint laid over the page's own ground, so it is the same grey whatever is behind the section; the photographs' placeholder is raised to color.bg.surface-card-raised so it does not vanish into the band
+- `strong` — `color.bg.brand-strong`, the dark band, for a section a reader should arrive at. The heading, the names and the roles turn white, the profile links take the band's ink rather than the brand's, and the button takes Button's inverse tone
+
+Use when: Which of the page's three grounds this section paints, and with it the ink and the photographs' placeholder — the grey a picture sits on before it arrives, which follows the ground so it never vanishes into the band. A page builds its rhythm from these, and the section above knows nothing about the one below it, so the page is the only thing that can decide.
+Never for: Marking importance. Every section on a page painted a ground is a page with no emphasis left. And never the brand's coral, `color.bg.brand`, which is not offered: that ground belongs to the band that asks a reader to do something.
+
+### title — `string` **Required.**
+
+Use when: Always. Who these people are, in the fewest words — "Meet our leadership team". It names the section as a region, so a screen reader can jump to it and past it.
+Never for: A sentence. The line under it is for the sentence.
+
+### description — `string`
+
+Use when: A line saying who the set is, when the title alone does not — "The people steering Deriv's products, markets and teams".
+Never for: A paragraph, or an introduction to each person. The cards say who each one is.
+
+### people — `data` `TeamGridMember[]` **Required.**
+
+Use when: Always. The people, in the order the page wants them read — by seniority or by relevance, the first `collapsedCount` of them showing at once. Each has a name, a role, a picture with its `alt`, and where there is one a `profile` link. The same framing in every photograph: the grid crops each to a square, and a set of faces at different distances reads as a set of different sources. An empty list draws the heading alone.
+Never for: Anyone who has not agreed to be on the page, or a profile link that is not theirs.
+
+### collapsedCount — `number` (default `4`)
+
+Use when: How many people show before the rest are asked for. Four, the default, is one row at full width, so the button sits under a complete row. A list no longer than this has no button at all — there is nothing more to show.
+Never for: Hiding one or two people behind a button. A person more than a row is better shown than asked for: raise this to the length of the list.
+
+### expandLabel — `string` (default `View all`)
+
+Use when: The button's words while the rest of the list is hidden. Translate it with the page, and keep it parallel to collapseLabel.
+
+### collapseLabel — `string` (default `View less`)
+
+Use when: The button's words once the whole list is showing, for the reason expandLabel exists.
+
+### profileName — `callback`
+
+Use when: The accessible name of a person's profile link, given the person. The visible word is the profile's own — "LinkedIn" — and it is the same on every card, so the link is named for its person too. Without this the name is the profile's label and then the person's, "LinkedIn, Alex Morgan": the visible word first, so a reader using speech can say what they see. Pass it to translate that with the page.
+Never for: Visible text. It names the link to assistive technology and is never drawn.
+
+### externalLabel — `string` (default `(opens in a new tab)`)
+
+Use when: Said after every profile link's name, because a profile opens in a new tab and a reader should know before they press it — ResourceBanner's words for the same thing. Translate it with the page.
+Never for: Visible text. It is added to the link's name for assistive technology and never drawn.
+
+## 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: `region`
+- `Tab` — Moves through the profile links of the people showing, in reading order, and then to the button. People the button has not shown are not in the tab order.
+- `Enter` — On the button, shows the rest of the list or hides it again; focus stays on the button. On a profile link, opens it in a new tab.
+- `Space` — On the button, the same as Enter.
+- accessible name from title, so the section is a named region a screen reader can jump to and skip
+- The people are a list, each person's name a heading under the section's, so the set is counted and a reader can move person to person.
+- The button says whether the rest of the list is showing with aria-expanded and names the list with aria-controls. Pressing it leaves focus where it is; the people it shows come straight before it in reading order, and the people it hides leave the tab order with them.
+- Each profile link is named for its person as well as its site, so a list of links heard on its own says whose each one is.
+
+## 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 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
+
+❌ TeamGrid for: One person, spotlit, in their own words
+   A grid of one is a portrait with nothing to compare it to; a quote with the name under it says why the person is on the page
+   → use `TestimonialSlider` instead.
+
+❌ TeamGrid for: The items are not people — logos, features, figures
+   A square photograph over a name and a role is a person's card; anything else in that shape reads as a team page with the wrong team on it
+   → use `FeatureCards` instead.
+
+## Example
+
+```tsx
+import { TeamGrid } from '@deriv-com/dds-marketing'
+
+<TeamGrid title="Meet our leadership team" description="The people steering Deriv's products, markets and teams across 20 countries." people={[{"name":"Alex Morgan","role":"Chief Executive Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/alex-morgan","label":"LinkedIn"}},{"name":"Sam Rivera","role":"Chief Operating Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/sam-rivera","label":"LinkedIn"}},{"name":"Jordan Lee","role":"Chief Technology Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jordan-lee","label":"LinkedIn"}},{"name":"Taylor Brooks","role":"Chief Financial Officer","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Casey Quinn","role":"Head of Compliance","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/casey-quinn","label":"LinkedIn"}},{"name":"Morgan Hayes","role":"Head of Product","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Riley Chen","role":"Head of Marketing","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/riley-chen","label":"LinkedIn"}},{"name":"Jamie Patel","role":"Head of People","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jamie-patel","label":"LinkedIn"}}]} />
+```
+
+## In use
+
+### A row, and the rest behind a button
+
+Four show at once, one row at full width. View all shows the rest; a list of four or fewer has no button at all.
+
+```tsx
+import { TeamGrid } from '@deriv-com/dds-marketing'
+
+// Eight people, four showing
+<TeamGrid title="Meet our leadership team" people={[{"name":"Alex Morgan","role":"Chief Executive Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/alex-morgan","label":"LinkedIn"}},{"name":"Sam Rivera","role":"Chief Operating Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/sam-rivera","label":"LinkedIn"}},{"name":"Jordan Lee","role":"Chief Technology Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jordan-lee","label":"LinkedIn"}},{"name":"Taylor Brooks","role":"Chief Financial Officer","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Casey Quinn","role":"Head of Compliance","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/casey-quinn","label":"LinkedIn"}},{"name":"Morgan Hayes","role":"Head of Product","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Riley Chen","role":"Head of Marketing","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/riley-chen","label":"LinkedIn"}},{"name":"Jamie Patel","role":"Head of People","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jamie-patel","label":"LinkedIn"}}]} />
+
+// Four people, no button
+<TeamGrid title="Meet our leadership team" people={[{"name":"Alex Morgan","role":"Chief Executive Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/alex-morgan","label":"LinkedIn"}},{"name":"Sam Rivera","role":"Chief Operating Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/sam-rivera","label":"LinkedIn"}},{"name":"Jordan Lee","role":"Chief Technology Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jordan-lee","label":"LinkedIn"}},{"name":"Taylor Brooks","role":"Chief Financial Officer","image":{"src":"/sample-card-image.svg","alt":""}}]} />
+```
+
+### How many show at first
+
+collapsedCount sets how many people show before the button. Eight here, so a board of eight is shown whole.
+
+```tsx
+import { TeamGrid } from '@deriv-com/dds-marketing'
+
+// collapsedCount 8, the whole board
+<TeamGrid title="Our advisory board" description="Industry voices who guide how we build for traders." people={[{"name":"Alex Morgan","role":"Chief Executive Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/alex-morgan","label":"LinkedIn"}},{"name":"Sam Rivera","role":"Chief Operating Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/sam-rivera","label":"LinkedIn"}},{"name":"Jordan Lee","role":"Chief Technology Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jordan-lee","label":"LinkedIn"}},{"name":"Taylor Brooks","role":"Chief Financial Officer","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Casey Quinn","role":"Head of Compliance","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/casey-quinn","label":"LinkedIn"}},{"name":"Morgan Hayes","role":"Head of Product","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Riley Chen","role":"Head of Marketing","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/riley-chen","label":"LinkedIn"}},{"name":"Jamie Patel","role":"Head of People","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jamie-patel","label":"LinkedIn"}}]} collapsedCount={8} />
+```
+
+### On the grey band and the dark one
+
+ground="subtle" tells the section apart from the one above; ground="strong" stops the page, and the links and button turn white.
+
+```tsx
+import { TeamGrid } from '@deriv-com/dds-marketing'
+
+// Subtle ground
+<TeamGrid title="Meet our leadership team" description="The people steering Deriv's products, markets and teams across 20 countries." people={[{"name":"Alex Morgan","role":"Chief Executive Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/alex-morgan","label":"LinkedIn"}},{"name":"Sam Rivera","role":"Chief Operating Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/sam-rivera","label":"LinkedIn"}},{"name":"Jordan Lee","role":"Chief Technology Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jordan-lee","label":"LinkedIn"}},{"name":"Taylor Brooks","role":"Chief Financial Officer","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Casey Quinn","role":"Head of Compliance","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/casey-quinn","label":"LinkedIn"}},{"name":"Morgan Hayes","role":"Head of Product","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Riley Chen","role":"Head of Marketing","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/riley-chen","label":"LinkedIn"}},{"name":"Jamie Patel","role":"Head of People","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jamie-patel","label":"LinkedIn"}}]} ground="subtle" />
+
+// Strong ground
+<TeamGrid title="Meet our leadership team" description="The people steering Deriv's products, markets and teams across 20 countries." people={[{"name":"Alex Morgan","role":"Chief Executive Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/alex-morgan","label":"LinkedIn"}},{"name":"Sam Rivera","role":"Chief Operating Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/sam-rivera","label":"LinkedIn"}},{"name":"Jordan Lee","role":"Chief Technology Officer","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jordan-lee","label":"LinkedIn"}},{"name":"Taylor Brooks","role":"Chief Financial Officer","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Casey Quinn","role":"Head of Compliance","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/casey-quinn","label":"LinkedIn"}},{"name":"Morgan Hayes","role":"Head of Product","image":{"src":"/sample-card-image.svg","alt":""}},{"name":"Riley Chen","role":"Head of Marketing","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/riley-chen","label":"LinkedIn"}},{"name":"Jamie Patel","role":"Head of People","image":{"src":"/sample-card-image.svg","alt":""},"profile":{"href":"https://example.com/people/jamie-patel","label":"LinkedIn"}}]} ground="strong" />
+```