@deriv-com/dds-marketing 0.2.0 → 1.0.1

package/.llm/components/featurescroll.md

@@ -0,0 +1,284 @@
+<!-- GENERATED from feature-scroll.contract.json. Do not edit. -->
+
+# FeatureScroll
+
+A section that gives a set of things one screen each, with the picture pinned beside the words while a reader is on them.
+
+For a set too long to compare and too important to list — six markets, five platforms. A grid of cards asks a reader which to read first and most read none; this arrives at one at a time, at the cost of a screen of scrolling each.
+
+The stops are data rather than children, so a page can map them from a CMS. What that costs is slots: the picture is a path and the way onward two strings. `FeatureScrollStep` in `scroll-data` is the shape of one.
+
+The picture is held by `position: sticky`. Which picture is showing is the one thing here that is measured rather than styled.
+
+## Use when
+
+- A page has three or more things of the same kind to explain, each with a picture worth a screen — the markets a broker offers, the platforms it runs, the steps of an account opening
+- The set is meant to be walked through rather than compared, and a reader is expected to scroll it
+- The set comes from somewhere — a CMS, a registry, a filtered list — rather than being written out by hand
+
+## Do not use
+
+- There are three or four items a reader is meant to compare → `FeatureCards`
+- The set is lines rather than things — what an account includes → `FeatureBullets`
+- There is one point to make → `FeatureSplit`
+- The section opens the page → `LandingHero`
+- Two items. A set given a screen each has to be worth the travel, and a pair is worth one screen with both on it
+- A list of links. The stops are things with pictures and sentences; a set of destinations belongs in a navigation panel or a footer's columns
+- Anything a reader has to act on. This is a walk through a set, and a form or a price in the middle of it is a decision asked at the point a reader is least ready to make one
+- A set whose stops each need their own arrangement. Every stop here is the same shape by construction, which is what makes the set a set — a page wanting one stop to differ wants several FeatureSplits instead
+
+## Anatomy
+
+FeatureScroll renders 11 elements. A token binding names the part it applies to.
+
+- `root` — `<section>`, class `dds-featurescroll`. The section. It paints the ground that separates it from the page above and below, and asks its own width — so everything inside it, including the fold each stop takes, answers to the section rather than to the window.
+  
+  It paints one of the page's three grounds and the ink that goes with it, in one decision — see `ground`. The ink is set here and inherited by everything inside, which is the package's rule about a section that paints a ground: stated once, it cannot be half-applied.
+- `inner` — `<div>`, class `dds-featurescroll__inner`. The measure and the gutter, holding the section's content in the same column as every other section on the page.
+- `heading` — `<h2>`, class `dds-featurescroll__heading`. The line over the set. Held to a heading's measure and centred at full width, which is what says the set below it is the subject rather than a step in an argument.
+  
+  Named `heading` and not `title` because each stop has a title of its own, and two parts called the same thing in one component is a stylesheet nobody can read.
+- `steps` — `<div>`, class `dds-featurescroll__steps`. The set, one stop under the next below the fold, and a two-column grid at full width.
+  
+  The grid is what puts every picture in one place. Each stop stops being a box there — `display: contents` — so the words and the pictures become the grid's own items, and every picture is placed in the same column across every row. They overlap, which is the whole point: one is shown and the rest are held at nothing, so moving between them is a change in the same square rather than one picture leaving and another arriving from below.
+  
+  It carries a gap between the stops below the fold and none at full width, where the rows are a screen tall and the picture over them never moves.
+- `step` — `<div>`, class `dds-featurescroll__step`. One stop: a name, a line, a way onward and the picture that belongs to them.
+  
+  Below the fold it is a stack, and the only place these four are boxed together. At full width it is `display: contents` and has no box at all — the words and the picture are placed by the grid instead, into a column each, because a picture inside its own stop can only be pinned within it and the section needs one pinned across the whole set.
+  
+  It is still what groups them in the markup, which is what a reader's assistive technology and anybody reading the DOM sees: four things about one stop, in the order a phone reads them.
+- `content` — `<div>`, class `dds-featurescroll__content`. The words of one stop, centred in the stop's own height so they sit level with the picture beside them.
+  
+  Centring is `justify-content` on a column, which only says anything once the column is as tall as the stop — that is what the row's `stretch` is for. A column the height of its own text has nothing to centre within, and reads as correct right up until the stop is taller than the words, which here it always is.
+  
+  It sets no gap of its own — the steps inside it sit on each part's own margin, title-to-description and description-to-what-follows being two different roles that a single gap could only ever be one of.
+  
+  Below the fold it is `display: contents`, which is what lets the picture sit between the name and the line about it without a second copy of the markup. The reference design ships two DOM trees for this and hides one at each width; two trees are two things to keep in step, and a screen reader offered the hidden one finds every stop twice.
+  
+  Below the fold it also arrives on its own, a beat ahead of the picture under it. Above the fold neither moves: the pinned square being exchanged is the section's motion there, and a stop sliding in under it would be two arrivals for one thing.
+- `title` — `<h3>`, class `dds-featurescroll__title`. What one stop is called. `h3` because the section carries the page's `h2`, and the stops are subsections of it — which is also what lets a screen reader move between them rather than scroll through six screens.
+- `description` — `<p>`, class `dds-featurescroll__description`. The line under the name, held to a readable measure rather than the half it sits in — a column of body text as wide as a picture is a column a reader loses their place in.
+- `link` — `<div>`, class `dds-featurescroll__link`. The way onward from one stop, drawn only where that stop gives both a href and a label. It holds a Link, which the section builds rather than the page: a list of records cannot carry an element, so the two strings are what arrive and this is what turns them into the same Link the rest of the site uses.
+- `media` — `<div>`, class `dds-featurescroll__media`. The band one picture is pinned inside.
+  
+  Every stop has one and at full width they are stacked in the same column of the grid, pinned at the same line under the bar. One is shown and the rest are held at nothing, so a reader who scrolls past a stop's title sees the square change rather than travel — which is the section's whole effect and the reason the stops give up their boxes for it.
+  
+  One picture gives way to the next by fading in over it, rather than by the pair fading past each other. The arriving one is brought to the front and takes the full duration to become opaque, and the one beneath holds exactly as it was until it is covered — so at no moment is the square anything less than a complete picture. Fading both at once would leave them near half way together, the section's ground showing through the pair, and the square would brighten and dim: a pulse made of nothing but two opacities crossing.
+  
+  Front is the shown one rather than the later one in the markup, because a reader scrolls back as well as forward — going up, the arriving picture is earlier in the document and would fade in underneath what it is replacing.
+  
+  The duration and the easing are the roles this system names for art moving inside a frame that holds still, which is what the pinned square is. The easing is symmetric for the same reason it is on a hovered card: the change runs both ways as a reader scrolls up and down.
+  
+  Which one is shown is the only thing here that is not CSS: the component watches where each title has reached and marks the band whose stop is next. See FeatureScroll's own notes.
+  
+  It is a band rather than the picture itself because a sticky box holds only while its containing block has room left under it — a square pinned in a screen-tall column is released a third of the way down. The band is the height of a screen, so it never runs out.
+  
+  Below the fold it is static, hugs its picture, and every one of them is shown: there is one column there, nothing to pin against, and each stop carries its own.
+- `picture` — `<img>`, class `dds-featurescroll__picture`. The picture of one stop.
+  
+  Held to a square and cropped to fill it, so a section of six stops is six identical frames whatever the page passes — six different crops down a scroll is a column whose edge moves on every screen. `cover` rather than `contain`, because the square is the section's decision and a picture letterboxed inside it would show the ground through a corner the section rounded.
+  
+  The largest square the band can hold: as wide as the half it sits in, or as tall as the band, whichever runs out first. Both bounds are needed — a square capped on one axis alone is not a square, it is a picture the browser has flattened.
+  
+  Decorative, and hidden from assistive technology with an empty alt. What a stop says is its name and the line under it.
+  
+  The arrival below the fold is on the picture rather than on the band around it, because the band's own opacity belongs to the crossfade — two things writing one property is two things disagreeing. The gap between the words coming up and the picture following is the layout's rather than a delay: each watches for itself, and on a phone the picture reaches the viewport a beat later because it sits under the line it belongs to.
+
+Apply these classes from the generated `featureScrollParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `FeatureScroll`, `FeatureSplit`, `FeatureBullets`, `LandingHero`, `ProductHero`, `PageHeader`, `Footer`, `Navbar`, `Table`, `Accordion` — 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. A section that has nothing to separate itself from what is above it — most of them — and the ground a reader is already on
+- `subtle` — A quiet step off the page, for a band that wants to read as its own section without changing the page's voice. The one to reach for first when two sections need telling apart. Painted as the band's tint laid over the page's own ground, so it is the same grey whatever is behind the section — in dark mode the tint alone took on whatever it was set against, and on a light surface it was light ink on white.
+- `strong` — `color.bg.brand-strong`, the dark band. It stops the page rather than dividing it, so it is for a section a reader should arrive at — and one per page is usually one more than enough
+
+Use when: Which of the page's three grounds this section paints. A marketing page is white, and a band that wants to be seen as a band takes one of the other two — so this is how a page builds its rhythm: white, white, grey, white, dark. Two in a row is a deliberate pair rather than an accident, and the section above knows nothing about the one below it, so the page is the only thing that can decide.
+
+The ink follows the ground and is not a second decision: a dark band carries white type because this sets both halves in one value, which is what the painted-ground-carries-its-ink rule exists to stop a page getting wrong.
+Never for: Marking importance. Every section on a page painted dark is a page with no emphasis left, and a reader stops reading the grounds as meaning anything. Alternating for its own sake is the same mistake more slowly.
+
+And never the brand's own coral, `color.bg.brand`, which is not offered here. That ground belongs to the band that asks a reader to do something — the one place on a page where the brand colour is the point rather than decoration — and a feature section wearing it is a page with two calls to action, one of which does nothing. It is `color.bg.brand-strong` that this offers: the dark brand ground, which is a band breaking a page rather than a band asking for something.
+
+### mediaPosition — `end` | `start` (default `end`)
+
+- `end` — The default. The words are read first, which is the order a reader’s eye takes a two-up row in
+- `start` — The pictures lead, for a section following one that put its own the other way — two scrolls facing the same way read as one very long column
+
+Use when: Which side the pictures pin to, for every stop at once. It is one value rather than one per stop because the picture pins to a place and stays there for several screens — a reader who found it once looks for it in the same place on the next one, and a set that moved it would be a set they have to re-find.
+Never for: Moving the pictures on a phone. There is one column there, and the picture sits under each name whichever side this names
+
+### title — `string` **Required.**
+
+Use when: Always. What the set is a set of, in the fewest words that say it — 'All your markets in one place'. It is the only thing a reader sees before committing to several screens of scrolling, so it has to say what is coming
+Never for: A claim about the first stop. The heading is over the whole set; an argument belongs in the stop it argues for
+
+### steps — `data` `FeatureScrollStep[]` **Required.**
+
+Use when: Always. The stops, in the order a reader meets them. Three at least — the section is built on each one having a screen, and a pair is worth one screen with both on it.
+
+Every stop is the same shape, which is what makes the set a set: a name, a line, a picture, and a way onward where there is one.
+Never for: A set assembled to fill the section. Each stop costs a reader a screen of scrolling, so a stop that is there for symmetry is a screen nobody wanted
+
+## 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 ways onward, one per stop. Nothing else here is operable, and nothing about the pinning is reachable at all — it is the browser keeping a box in place while the page scrolls.
+- accessible name from title, so the section is a named region a screen reader can jump to and skip rather than several screens a reader has to walk
+- Each stop's name is a heading, so a reader moving by heading passes through the set at the speed they choose rather than at the speed the scroll imposes
+- The pictures are decoration and are hidden from assistive technology. What a stop says is its name and its line; a picture carrying something they do not is a stop that reads as half empty to anyone who cannot see it
+- Nothing here depends on scrolling having happened. Every stop is in the document, fully rendered, at the moment the page loads — the pinning is a visual arrangement of content that is already there, so a reader who never scrolls and a reader using a screen reader meet the same set
+
+## 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
+
+❌ FeatureScroll for: There are three or four items a reader is meant to compare
+   Comparing means seeing them at once, which is the one thing a screen-at-a-time set cannot offer
+   → use `FeatureCards` instead.
+
+❌ FeatureScroll for: The set is lines rather than things — what an account includes
+   A ruled list is countable at a glance where this is six screens of scrolling
+   → use `FeatureBullets` instead.
+
+❌ FeatureScroll for: There is one point to make
+   One claim beside one picture, at a section’s height rather than a screen’s, and the picture and the link are slots the page composes
+   → use `FeatureSplit` instead.
+
+❌ FeatureScroll for: The section opens the page
+   A page’s opening band is a claim, and a reader who meets a scroll-driven set first has not been told what the page is yet
+   → use `LandingHero` instead.
+
+## Example
+
+```tsx
+import { FeatureScroll } from '@deriv-com/dds-marketing'
+
+<FeatureScroll title="All your markets in one place" steps={[{"title":"Forex","description":"Trade the most popular currency pairs with high leverage, tight spreads and execution fast enough to matter on a pair that moves in the time it takes to read this.","href":"/markets/forex","linkLabel":"Learn more","image":"/sample-stop-brand.svg"},{"title":"Derived indices","description":"Trade around the clock on indices derived from a random number generator rather than from a market — the volatility is chosen rather than waited for.","href":"/markets/derived-indices","linkLabel":"Learn more","image":"/sample-stop-teal.svg"},{"title":"Stocks","description":"Trade the global names a reader already knows, on the same platform and out of the same account as everything else here.","href":"/markets/stocks","linkLabel":"Learn more","image":"/sample-stop-amber.svg"},{"title":"Commodities","description":"Trade gold, silver, oil and natural gas — the instruments a portfolio reaches for when it wants something that is not a currency or a company.","href":"/markets/commodities","linkLabel":"Learn more","image":"/sample-stop-purple.svg"},{"title":"Cryptocurrencies","description":"Trade the volatility of Bitcoin and Ethereum without holding either, on a market that does not close at the weekend.","href":"/markets/cryptocurrencies","linkLabel":"Learn more","image":"/sample-stop-blue.svg"}]} />
+```
+
+## In use
+
+### The ground it sits on
+
+The three grounds a page can put a section on. The page is white, so a band painting one of the other two is saying it is its own section — and the ink follows the ground.
+
+```tsx
+import { FeatureScroll } from '@deriv-com/dds-marketing'
+
+// On the page itself
+<FeatureScroll ground="page" title="All your markets in one place" steps={[{"title":"Forex","description":"Trade the most popular currency pairs with high leverage, tight spreads and execution fast enough to matter on a pair that moves in the time it takes to read this.","href":"/markets/forex","linkLabel":"Learn more","image":"/sample-stop-brand.svg"},{"title":"Derived indices","description":"Trade around the clock on indices derived from a random number generator rather than from a market — the volatility is chosen rather than waited for.","href":"/markets/derived-indices","linkLabel":"Learn more","image":"/sample-stop-teal.svg"},{"title":"Stocks","description":"Trade the global names a reader already knows, on the same platform and out of the same account as everything else here.","href":"/markets/stocks","linkLabel":"Learn more","image":"/sample-stop-amber.svg"},{"title":"Commodities","description":"Trade gold, silver, oil and natural gas — the instruments a portfolio reaches for when it wants something that is not a currency or a company.","href":"/markets/commodities","linkLabel":"Learn more","image":"/sample-stop-purple.svg"},{"title":"Cryptocurrencies","description":"Trade the volatility of Bitcoin and Ethereum without holding either, on a market that does not close at the weekend.","href":"/markets/cryptocurrencies","linkLabel":"Learn more","image":"/sample-stop-blue.svg"}]} />
+
+// On the quiet ground
+<FeatureScroll ground="subtle" title="All your markets in one place" steps={[{"title":"Forex","description":"Trade the most popular currency pairs with high leverage, tight spreads and execution fast enough to matter on a pair that moves in the time it takes to read this.","href":"/markets/forex","linkLabel":"Learn more","image":"/sample-stop-brand.svg"},{"title":"Derived indices","description":"Trade around the clock on indices derived from a random number generator rather than from a market — the volatility is chosen rather than waited for.","href":"/markets/derived-indices","linkLabel":"Learn more","image":"/sample-stop-teal.svg"},{"title":"Stocks","description":"Trade the global names a reader already knows, on the same platform and out of the same account as everything else here.","href":"/markets/stocks","linkLabel":"Learn more","image":"/sample-stop-amber.svg"},{"title":"Commodities","description":"Trade gold, silver, oil and natural gas — the instruments a portfolio reaches for when it wants something that is not a currency or a company.","href":"/markets/commodities","linkLabel":"Learn more","image":"/sample-stop-purple.svg"},{"title":"Cryptocurrencies","description":"Trade the volatility of Bitcoin and Ethereum without holding either, on a market that does not close at the weekend.","href":"/markets/cryptocurrencies","linkLabel":"Learn more","image":"/sample-stop-blue.svg"}]} />
+
+// On the dark band
+<FeatureScroll ground="strong" title="All your markets in one place" steps={[{"title":"Forex","description":"Trade the most popular currency pairs with high leverage, tight spreads and execution fast enough to matter on a pair that moves in the time it takes to read this.","href":"/markets/forex","linkLabel":"Learn more","image":"/sample-stop-brand.svg"},{"title":"Derived indices","description":"Trade around the clock on indices derived from a random number generator rather than from a market — the volatility is chosen rather than waited for.","href":"/markets/derived-indices","linkLabel":"Learn more","image":"/sample-stop-teal.svg"},{"title":"Stocks","description":"Trade the global names a reader already knows, on the same platform and out of the same account as everything else here.","href":"/markets/stocks","linkLabel":"Learn more","image":"/sample-stop-amber.svg"},{"title":"Commodities","description":"Trade gold, silver, oil and natural gas — the instruments a portfolio reaches for when it wants something that is not a currency or a company.","href":"/markets/commodities","linkLabel":"Learn more","image":"/sample-stop-purple.svg"},{"title":"Cryptocurrencies","description":"Trade the volatility of Bitcoin and Ethereum without holding either, on a market that does not close at the weekend.","href":"/markets/cryptocurrencies","linkLabel":"Learn more","image":"/sample-stop-blue.svg"}]} />
+```
+
+### Which side the pictures pin to
+
+One switch for the whole set, because the picture pins to a place and stays there for several screens. Two of these on a page take opposite sides, or they read as one very long column.
+
+```tsx
+import { FeatureScroll } from '@deriv-com/dds-marketing'
+
+// Pictures at the end
+<FeatureScroll title="All your markets in one place" mediaPosition="end" steps={[{"title":"Forex","description":"Trade the most popular currency pairs with high leverage, tight spreads and execution fast enough to matter on a pair that moves in the time it takes to read this.","href":"/markets/forex","linkLabel":"Learn more","image":"/sample-stop-brand.svg"},{"title":"Derived indices","description":"Trade around the clock on indices derived from a random number generator rather than from a market — the volatility is chosen rather than waited for.","href":"/markets/derived-indices","linkLabel":"Learn more","image":"/sample-stop-teal.svg"},{"title":"Stocks","description":"Trade the global names a reader already knows, on the same platform and out of the same account as everything else here.","href":"/markets/stocks","linkLabel":"Learn more","image":"/sample-stop-amber.svg"}]} />
+
+// Pictures at the start
+<FeatureScroll title="And the platforms they run on" mediaPosition="start" steps={[{"title":"Forex","description":"Trade the most popular currency pairs with high leverage, tight spreads and execution fast enough to matter on a pair that moves in the time it takes to read this.","href":"/markets/forex","linkLabel":"Learn more","image":"/sample-stop-brand.svg"},{"title":"Derived indices","description":"Trade around the clock on indices derived from a random number generator rather than from a market — the volatility is chosen rather than waited for.","href":"/markets/derived-indices","linkLabel":"Learn more","image":"/sample-stop-teal.svg"},{"title":"Stocks","description":"Trade the global names a reader already knows, on the same platform and out of the same account as everything else here.","href":"/markets/stocks","linkLabel":"Learn more","image":"/sample-stop-amber.svg"}]} />
+```
+
+### A stop with nowhere to go on to
+
+The way onward is the one optional part of a stop, and it takes both a href and a label — one without the other draws nothing rather than half of it.
+
+```tsx
+import { FeatureScroll } from '@deriv-com/dds-marketing'
+
+// No link on the last stop
+<FeatureScroll title="Three ways to trade" steps={[{"title":"Forex","description":"Trade the most popular currency pairs with high leverage, tight spreads and execution fast enough to matter on a pair that moves in the time it takes to read this.","href":"/markets/forex","linkLabel":"Learn more","image":"/sample-stop-brand.svg"},{"title":"Derived indices","description":"Trade around the clock on indices derived from a random number generator rather than from a market — the volatility is chosen rather than waited for.","href":"/markets/derived-indices","linkLabel":"Learn more","image":"/sample-stop-teal.svg"},{"title":"Stocks","description":"Trade the global names a reader already knows, on the same platform and out of the same account as everything else here.","image":"/sample-stop-amber.svg"}]} />
+```

package/.llm/components/featuresplit.md

@@ -0,0 +1,249 @@
+<!-- GENERATED from feature-split.contract.json. Do not edit. -->
+
+# FeatureSplit
+
+A section putting one claim, a line explaining it and a way onward beside a single picture.
+
+The plainest block here, and that is what it is for: somewhere to make one more point about something the page has already introduced, without opening a list or a set of cards. A split rather than a stack, because the same words over a full-width photograph read as a caption and beside one as a claim with evidence.
+
+It sits on the page's own ground by default; `ground` paints the grey or the dark band where the section needs setting apart from the ones around it.
+
+## Use when
+
+- A page needs one more point about something it has already introduced, with a picture to carry it
+- The point is a sentence rather than a list, and does not earn a set of cards
+- A section needs a way onward that is not a call to action — a link to the page that says more
+
+## Do not use
+
+- The point is several things the reader gets, each one line long → `FeatureBullets`
+- There are three or four points and each needs its own picture → `FeatureCards`
+- The section opens the page → `ProductHero`
+- A list. Two sentences separated by a full stop is not a list, and a reader scanning for several things will miss the second — that is what FeatureBullets is for
+- The page's opening or closing band. This is a section in the middle of a page and carries no navigation of its own
+- A call to action. The way onward here is a link to somewhere that says more, not the thing the page wants a reader to do
+
+## Anatomy
+
+FeatureSplit renders 8 elements. A token binding names the part it applies to.
+
+- `root` — `<section>`, class `dds-featuresplit`. The section. It paints the ground that separates it from the page above and below, and asks its own width so the split folds on the section's measure rather than the window's.
+  
+  It paints one of the page's three grounds and the ink that goes with it, in one decision — see `ground`. The ink is set here and inherited by everything inside, which is the package's rule about a section that paints a ground: stated once, it cannot be half-applied.
+- `inner` — `<div>`, class `dds-featuresplit__inner`. The measure and the gutter, holding the section's content in the same column as every other section on the page.
+- `split` — `<div>`, class `dds-featuresplit__split`. The two halves. A row at full width with the picture on whichever side `mediaPosition` names, and one column below the fold with the words first — because a reader on a phone came for the words, whichever side the picture takes on a desktop.
+- `content` — `<div>`, class `dds-featuresplit__content`. The claim, the line under it and the way onward. 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 different roles, and a single gap could only ever be one of them.
+- `title` — `<h2>`, class `dds-featuresplit__title`. The claim. `h2` because a section in the middle of a page sits under the page's own heading.
+- `description` — `<p>`, class `dds-featuresplit__description`. The line under the claim, held to a readable measure rather than the half it sits in — a column of body text as wide as a picture is a column a reader loses their place in. Rendered only when `description` is set.
+- `link` — `<div>`, class `dds-featuresplit__link`. The way onward. A slot rather than a label and a handler, so a link here is the same Link as anywhere else on the site — and the step above it is carried by whatever it follows. Rendered only when `link` is set.
+- `media` — `<div>`, class `dds-featuresplit__media`. The picture, and one of the section's two halves rather than an addition to it. Held to a square and cropped to fill it, so a section is the same shape whatever the page passes — three of these down a page with three different crops is three sections that do not line up.
+
+Apply these classes from the generated `featureSplitParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `FeatureSplit`, `FeatureBullets`, `LandingHero`, `ProductHero`, `PageHeader`, `Footer`, `Navbar`, `Table`, `Accordion` — 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. A section that has nothing to separate itself from what is above it — most of them — and the ground a reader is already on
+- `subtle` — A quiet step off the page, for a band that wants to read as its own section without changing the page's voice. The one to reach for first when two sections need telling apart. Painted as the band's tint laid over the page's own ground, so it is the same grey whatever is behind the section — in dark mode the tint alone took on whatever it was set against, and on a light surface it was light ink on white.
+- `strong` — `color.bg.brand-strong`, the dark band. It stops the page rather than dividing it, so it is for a section a reader should arrive at — and one per page is usually one more than enough
+
+Use when: Which of the page's three grounds this section paints. A marketing page is white, and a band that wants to be seen as a band takes one of the other two — so this is how a page builds its rhythm: white, white, grey, white, dark. Two in a row is a deliberate pair rather than an accident, and the section above knows nothing about the one below it, so the page is the only thing that can decide.
+
+The ink follows the ground and is not a second decision: a dark band carries white type because this sets both halves in one value, which is what the painted-ground-carries-its-ink rule exists to stop a page getting wrong.
+Never for: Marking importance. Every section on a page painted dark is a page with no emphasis left, and a reader stops reading the grounds as meaning anything. Alternating for its own sake is the same mistake more slowly.
+
+And never the brand's own coral, `color.bg.brand`, which is not offered here. That ground belongs to the band that asks a reader to do something — the one place on a page where the brand colour is the point rather than decoration — and a feature section wearing it is a page with two calls to action, one of which does nothing. It is `color.bg.brand-strong` that this offers: the dark brand ground, which is a band breaking a page rather than a band asking for something.
+
+### mediaPosition — `end` | `start` (default `end`)
+
+- `end` — The default. The claim is read first, which is the order the section argues in
+- `start` — The second of two on a page, so the two do not read as one column with a picture stuck to one side
+
+Use when: Which side the picture takes at full width. Alternating it down a page is what stops three of these in a row reading as one long column, and it is the page's decision rather than this section's — which is why it is a prop and not a rule.
+
+It is the arrangement at full width and never a promise about a phone: below the fold the words are always first, because a reader on a phone came for them.
+Never for: Moving the picture on a phone. There is one column there and the words lead it
+
+### title — `string` **Required.**
+
+Use when: Always. The one claim the section makes, in the fewest words that say it
+Never for: A sentence. The description underneath carries the argument; this only has to name it
+
+### description — `string`
+
+Use when: The lines under the title that say what the claim above means, for a reader not convinced by the claim alone. Two sentences is the normal length here and what the section is sized around — one is usually the title restated, and the column is wide enough to carry more than that.
+Never for: A paragraph. Past about two hundred characters the text column runs longer than the square beside it and the two halves stop lining up, which is the one thing a split has to get right. The reference design caps it at exactly that.
+
+### link — `node`
+
+Accepts: Link, Button
+Use when: The section has somewhere to send a reader who wants more than it says — the page this one is a summary of. "Learn more" is this site's wording for it, and using the same three words everywhere is what lets a reader stop reading them: a link that renames itself per section is a link somebody has to read before they know it is the way onward.
+Never for: The page's main call to action. This is a way onward from a supporting point, and a primary button here competes with the one the page actually wants pressed
+
+### media — `node` **Required.**
+
+Accepts: *
+Use when: Always. The picture that sits beside the claim — a screenshot, a photograph, an illustration. The section is a split and the picture is one half of it: without one the claim runs to a measure it was never sized for.
+Never for: Anything a reader has to read or press. It is held to a square and cropped to fill it, so words in it are cropped too
+
+## 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 to the way onward, where there is one, and past the section otherwise. Nothing else here is operable.
+- accessible name from title, so the section is a named region a screen reader can jump to and skip rather than an unlabelled one a reader has to walk
+- The picture is decoration and is hidden from assistive technology. What the section says is the title and the description; a picture carrying something they do not is a section that reads as half empty to anyone who cannot see it
+
+## 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
+
+❌ FeatureSplit for: The point is several things the reader gets, each one line long
+   The same split with a ruled list in it, which is what makes a set of inclusions countable
+   → use `FeatureBullets` instead.
+
+❌ FeatureSplit for: There are three or four points and each needs its own picture
+   A heading over a grid of cards, where a split repeated four times is four screens of scrolling
+   → use `FeatureCards` instead.
+
+❌ FeatureSplit for: The section opens the page
+   A page's opening band is a claim, not a supporting point
+   → use `ProductHero` instead.
+
+## Example
+
+```tsx
+import { FeatureSplit, Link, AspectRatio } from '@deriv-com/dds-marketing'
+
+<FeatureSplit title="Trade on the platform professionals use" description="Deriv MT5 brings charting, order types and risk controls into one place, on desktop, web and mobile. Your positions, watchlists and alerts follow you between all three." link={<Link href="/platforms/deriv-mt5">Learn more</Link>} media={<AspectRatio ratio="square" />} />
+```
+
+## In use
+
+### The ground it sits on
+
+The three grounds a page can put a section on. The page is white, so a band painting one of the other two is saying it is its own section — and the ink follows the ground.
+
+```tsx
+import { AspectRatio, FeatureSplit, Link } from '@deriv-com/dds-marketing'
+
+// On the page itself
+<FeatureSplit ground="page" title="Trade on the platform professionals use" description="Deriv MT5 brings charting, order types and risk controls into one place, on desktop, web and mobile. Your positions, watchlists and alerts follow you between all three." link={<Link href="/platforms/deriv-mt5">Learn more</Link>} media={<AspectRatio ratio="square" />} />
+
+// On the quiet ground
+<FeatureSplit ground="subtle" title="Trade on the platform professionals use" description="Deriv MT5 brings charting, order types and risk controls into one place, on desktop, web and mobile. Your positions, watchlists and alerts follow you between all three." link={<Link href="/platforms/deriv-mt5">Learn more</Link>} media={<AspectRatio ratio="square" />} />
+
+// On the dark band
+<FeatureSplit ground="strong" title="Trade on the platform professionals use" description="Deriv MT5 brings charting, order types and risk controls into one place, on desktop, web and mobile. Your positions, watchlists and alerts follow you between all three." link={<Link href="/platforms/deriv-mt5">Learn more</Link>} media={<AspectRatio ratio="square" />} />
+```
+
+### Which side the picture takes
+
+Alternating it down a page is what stops three of these in a row reading as one long column with a ragged edge. Below the fold there is one column and the claim leads it either way.
+
+```tsx
+import { AspectRatio, FeatureSplit, Link } from '@deriv-com/dds-marketing'
+
+// Picture last — the default
+<FeatureSplit mediaPosition="end" title="Trade on the platform professionals use" description="Deriv MT5 brings charting, order types and risk controls into one place, on desktop, web and mobile. Your positions, watchlists and alerts follow you between all three." link={<Link href="/platforms/deriv-mt5">Learn more</Link>} media={<AspectRatio ratio="square" />} />
+
+// Picture first — for the second of two
+<FeatureSplit mediaPosition="start" title="And on the one built for beginners" description="Deriv Trader is the same markets with the controls a first trade needs and none of the ones it does not. Nothing to install, and a demo account to practise on first." link={<Link href="/platforms/deriv-mt5">Learn more</Link>} media={<AspectRatio ratio="square" />} />
+```
+
+### How much the section carries
+
+Everything but the claim and the picture is optional, and the steps close up rather than leaving a gap where a part would have been.
+
+```tsx
+import { AspectRatio, FeatureSplit, Link } from '@deriv-com/dds-marketing'
+
+// A claim and a picture
+<FeatureSplit title="Trade on the platform professionals use" media={<AspectRatio ratio="square" />} />
+
+// With a line explaining it
+<FeatureSplit title="Trade on the platform professionals use" description="Deriv MT5 brings charting, order types and risk controls into one place, on desktop, web and mobile. Your positions, watchlists and alerts follow you between all three." media={<AspectRatio ratio="square" />} />
+
+// And a way onward
+<FeatureSplit title="Trade on the platform professionals use" description="Deriv MT5 brings charting, order types and risk controls into one place, on desktop, web and mobile. Your positions, watchlists and alerts follow you between all three." link={<Link href="/platforms/deriv-mt5">Learn more</Link>} media={<AspectRatio ratio="square" />} />
+```