@deriv-com/dds-marketing 1.1.3 → 1.2.0

package/.llm/digest/scenescrollword.md

@@ -0,0 +1,56 @@
+<!-- GENERATED from scenescrollword.contract.json. Do not edit. -->
+
+# SceneScrollWord
+
+Two full-screen photo scenes that cross-fade as the reader scrolls, under one title whose last word changes
+
+`import { SceneScrollWord } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- Two states of one thing that one claim covers with one word changed — trade all day and all night, markets open and markets closed, before and after
+- One immersive moment on a product or campaign page, where the claim is the argument and the two photographs show its two halves
+- The opening band of a campaign page built around that claim, at headingLevel h1
+
+## Something else, when
+
+- The two scenes say different things, each with a title of its own → **SceneScroll**
+- The two scenes are one claim with one word changed — "Trade all day", "Trade all night" → **SceneScrollWord**
+- There is one photograph, not two states of something → **ImageBanner**
+- Three or more things to show, each with a picture → **FeatureScroll**
+- The page's opening band, with an action to take → **LandingHero**
+- One statement on its own, revealed as the reader scrolls → **TextScroll**
+
+## Never
+
+- Two titles that only happen to share words. The shared words have to be a claim both words complete; one that reads as a sentence with the second word bolted on is two scenes' worth of title, which SceneScroll draws
+- Words a reader must not miss — a price, a disclaimer, a legal line. Each scene's words are on screen for only part of the pass
+- Two of these on one page, or one beside another pinned section. Each holds the screen for a screen and a half of scrolling, and two make the page feel stuck
+- Photographs with words in them. The words are the headings and the lines, where a screen reader and a translation reach them; a photograph saying them is cropped to fill and has the scene's words set over it
+- Words over a busy or mid-toned stretch of photograph. Nothing lies between the words and the photograph, so the photograph has to leave the words a calm, light or dark stretch to sit on, and the scene's ink has to name which
+
+## Props
+
+- **headingLevel** `enum` · default "h2" — Where the first scene's title sits in the page's outline. The second scene's title takes the level under it — h2 under an h1, h3 under an h2 — because it is the second half of the section the first one names, not a section of its own. …
+  - `h2` — The default: the section sits under the page's own h1, and the scenes' titles are drawn at font.h2
+  - `h1` — The section opens a campaign page and the first scene's title is the page's heading — the reference design's hero use. Drawn at font.h1, the opening band's size
+  - never: Making a mid-page section look like a hero. h1 is the page's heading, and a page has one
+- **titleBefore** `string` · optional — The words of the title that come before the changing word, the same in both scenes — "Trade all ", for "Trade all day" and "Trade all night". …
+  - never: Words that change between the scenes. Where the grammar makes a shared word agree with the changing one — Spanish "todo el día" and "toda la noche" — the agreeing words are part of each scene's `word`, not of what is shared
+- **titleAfter** `string` · optional — The words of the title that come after the changing word, the same in both scenes — " handeln", for German "Den ganzen Tag handeln" and "Die ganze Nacht handeln"; "取引" for Japanese "一日中取引" and "夜通し取引", with no space. …
+  - never: Punctuation alone. A heading takes no full stop, and a mark after the word holds still while the word changes before it, which reads as the mark belonging to neither
+- **first** `data` · required — Always. The scene the section opens on: the word that completes the title, a line under it where the title needs one, and the photograph filling the band behind them. With the shared words around it, it names the section. …
+  - never: A word that does not complete the shared words. Read together they are the heading; a word that only makes sense beside the other scene's is not one
+- **second** `data` · required — Always. The scene the section changes over to, in the same shape as the first. …
+  - never: The first scene's word again with a different picture. The changed word is the argument; two scenes that agree have nothing to change between
+- **action** `node` · optional — One thing for the reader to do or a way on — "Trade now", "See trading hours" — under the words. …
+  - never: Two actions, or a different one per scene. One thing to do for the section; something to press that changed under the pointer would be the one thing a reader could not rely on
+
+## Inside it
+
+- 8 components are refused inside it; the list and the reasons are in the long document.
+- Renders 12 parts: root, stage, scene, media, image, content, title, before, word, after, description, action.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/scenescrollword.md`.

package/.llm/digest/segmentedcontrol.md

@@ -46,6 +46,9 @@ Picks exactly one option from a short set of joined segments
   - never: Half of a controlled row. A value passed with no onChange to move it is a control that cannot respond to being pressed, which reads as broken rather than as fixed — and it is the shape a page falls into by adding the value first
 - **onChange** `callback` · optional — Whenever value is — together they are how a page holds the choice. It is called with the chosen segment's value after that segment's own onSelect, so a segment that reports its own presses keeps doing so inside a row
   - never: Side effects a choice should not have. This says which value is in force; a row that also navigated, submitted or fetched on it would be doing the thing its intent says it does not
+- **motion** `enum` · optional — The row moves once, on arrival — in an IllustrationCard when the pane has landed, otherwise when it is well into view. For a row shown as a picture of the product making a choice. …
+  - `slide` — The pill starts on the first segment and slides to the chosen one once, on arrival — a trade ticket set to Sell showing it was Buy first. …
+  - never: A row the reader is about to use. A live control that moves on its own before anyone touches it looks like it has been chosen for them
 
 ## Inside it
 

package/.llm/digest/stats.md

@@ -13,6 +13,7 @@ A heading over a few key figures, each with a short label
 
 ## Something else, when
 
+- Each figure is a moment rather than a column to compare, beside the awards behind it → **StatsCarousel**
 - Each item needs a sentence of its own, or a picture → **FeatureCards**
 - The number is part of a claim the page is making in words → **FeatureSplit**
 
@@ -29,6 +30,13 @@ A heading over a few key figures, each with a short label
   - `subtle` — The grey band, for a row of figures that should read as a section of its own without changing the page's voice. …
   - `strong` — `color.bg.brand-strong`, the dark band, for a set of figures a reader should arrive at — a home page's "Trade with confidence". …
   - never: Marking importance. Every section on a page painted a ground is a page with no emphasis left. And never the brand's own coral, which is not offered: that ground belongs to the band that asks a reader to do something
+- **background** `enum` · optional — The page's one patterned band, between its hero and its closing call to action — a band a reader should stop at. …
+  - `halftone` — A field of coral dots that grow towards a soft glow at the band's foot and settle to a fine screen away from it
+  - `aurora` — Curtains of the brand's light rising from the band's foot and swaying slowly
+  - `mesh` — The band in the brand's reds folded into one another like a liquid — the loudest of the five, for a dark band
+  - `grid` — Hairlines a pitch apart rising from a soft bloom at the band's foot — the quietest, and the one to reach for first
+  - `rings` — Hairline circles spreading out from the middle of the band's foot
+  - never: More than one band on a page, or a band that is already the hero or the call to action — those carry their own patterns. One pattern is what makes a band the one a reader remembers; two make neither, and a page of them is noise. …
 - **title** `string` · required — Always. What the numbers prove, in the fewest words — "Trade with confidence", "Deriv in numbers"
   - never: A figure. The figures are the content; the heading says what they add up to
 - **description** `string` · optional — A line under the heading, when the heading alone does not say whose numbers these are or since when — "For over 25 years, a trusted partner of traders worldwide."

package/.llm/digest/statscarousel.md

@@ -0,0 +1,48 @@
+<!-- GENERATED from statscarousel.contract.json. Do not edit. -->
+
+# StatsCarousel
+
+A heading over a card that turns through a few key figures, one at a time, with awards beside it
+
+`import { StatsCarousel } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- A trust band where each figure is a moment rather than a column to compare — monthly deals, customers, volume, years in business
+- The figures stand beside the awards behind them
+- A band between lighter sections that wants one moving thing in it
+
+## Something else, when
+
+- Three to five figures a reader compares at a glance → **Stats**
+- A page's full list of awards → **Awards**
+
+## Never
+
+- More than five figures. One turns in every second and a little; a sixth is waited for
+- A figure a reader must not miss — a price, a fee. It is on screen for a moment at a time
+- Two on one page, or beside another band that moves on its own
+
+## Props
+
+- **ground** `enum` · default "page" — Which of the page's three grounds this section paints, FeatureCards' axis and its reason: a band that wants to be seen as a band takes one of the other two, and the page decides the rhythm. …
+  - `page` — The default, and the page's own white. A row of figures between two sections that need nothing to separate them
+  - `subtle` — The grey band, for a row of figures that should read as a section of its own without changing the page's voice. …
+  - `strong` — `color.bg.brand-strong`, the dark band, for a set of figures a reader should arrive at — a home page's "Trade with confidence". …
+  - never: Marking importance. Every section on a page painted a ground is a page with no emphasis left. And never the brand's own coral, which is not offered: that ground belongs to the band that asks a reader to do something
+- **title** `string` · required — Always. What the numbers prove, in the fewest words — "Trade with confidence", "Deriv in numbers"
+  - never: A figure. The figures are the content; the heading says what they add up to
+- **description** `string` · optional — A line under the heading, when the heading alone does not say whose numbers these are or since when — "For over 25 years, a trusted partner of traders worldwide."
+  - never: A paragraph, or the figures again in words
+- **stats** `data` · required — Always. The figures, in the order they turn — three to five, each a short `value` exactly as it is to be read and a `label` of a few words. Two or more turn; one simply stands in the card. An empty list draws nothing
+  - never: A long value, or a label longer than one line: the card turns by one figure's height, and a figure that runs to two lines runs into the next
+- **awards** `data` · optional — Two to four awards the figures stand beside: the first half in a column at the card's start, the rest at its end; on a phone, the two columns side by side under the card. …
+  - never: A page's full list of awards — that is the Awards block — or more than four: a column of three beside a card reads as a list, not as the card's credentials
+
+## Inside it
+
+- Renders 17 parts: root, inner, header, title, description, stage, card, list, item, value, label, awards, award, award-laurel, award-copy, award-name, award-issuer.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/statscarousel.md`.

package/.llm/digest/statusdot.md

@@ -36,6 +36,13 @@ A small dot marking an item as notable or in a different state
   - never: Repeating the words already beside it, which is what makes a screen reader say the state twice. Nor for the explanation, which is tooltip. There is deliberately no default: a generic name would satisfy this without anybody choosing it, and it did — every unconfigured dot announced the word "Status" beside text that already said the state
 - **tooltip** `string` · optional — The state has a meaning the colour and the adjacent label together still do not explain — why a service is degraded, what "away" counts as. A few words, revealed on hover and on keyboard focus
   - never: A sentence the reader must have, or anything longer than a phrase. Setting this puts the dot in the tab order, because a description no keyboard can reach is one this system does not ship — so a tooltip on every dot in a list of twenty is twenty new tab stops, and worth spending only where the explanation is
+- **from** `enum` · optional — The state the dot starts in, which it leaves once on arrival — info's "Opening…" becoming success's "Position open". …
+  - `accent` — Starts as accent before becoming its own state
+  - `success` — Starts as success before becoming its own state
+  - `warning` — Starts as warning before becoming its own state
+  - `error` — Starts as error before becoming its own state
+  - `info` — Starts as info before becoming its own state
+  - never: A state the reader must notice. The first state is on screen for a second and never read out; and never more than one change — a dot that kept changing would be a live feed the page does not have
 
 ## The type refuses
 

package/.llm/digest/testimonialrow.md

@@ -24,11 +24,18 @@ An overall rating over a scrollable row of customer reviews
 
 ## Props
 
-- **ground** `enum` · default "page" — Which of the page's grounds the section paints, and with it the cards' fill: the recessed surface on the page, the raised white on the grey band — the reference design's slate band — and the strong card on the dark band, gray.900 in both themes. …
+- **ground** `enum` · default "page" — Which of the page's grounds the section paints, and with it the cards' fill: the recessed surface on the page, the raised white on the grey band — the reference design's slate band — and the strong card on the dark band, slate.850 in light and slate.900 in dark, a step above the band in both. …
   - `page` — The default, and the page's own white. The cards are the recessed gray that sets them off
   - `subtle` — The grey band, the reference design's ground for this section. The cards turn white on it. …
   - `strong` — `color.bg.brand-strong`, the dark band, for a section a reader should arrive at. …
   - never: Marking importance. Every section on a page painted a ground is a page with no emphasis left. And never a dark card on the dark band: a few sentences of white on dark gray is a paragraph a reader works through rather than a quote they take in
+- **background** `enum` · optional — The page's one patterned band, between its hero and its closing call to action — a band a reader should stop at. …
+  - `halftone` — A field of coral dots that grow towards a soft glow at the band's foot and settle to a fine screen away from it
+  - `aurora` — Curtains of the brand's light rising from the band's foot and swaying slowly
+  - `mesh` — The band in the brand's reds folded into one another like a liquid — the loudest of the five, for a dark band
+  - `grid` — Hairlines a pitch apart rising from a soft bloom at the band's foot — the quietest, and the one to reach for first
+  - `rings` — Hairline circles spreading out from the middle of the band's foot
+  - never: More than one band on a page, or a band that is already the hero or the call to action — those carry their own patterns. One pattern is what makes a band the one a reader remembers; two make neither, and a page of them is noise. …
 - **title** `string` · required — Always. Whose reviews these are, in a few words — "What our customers say"
   - never: A review, or the score. The reviews are the content and the summary states the score; the heading says whose they are
 - **reviews** `data` · required — Always. The reviews, in the order they run along the row — five to ten of a sentence or two, each with the reviewer's name, its `rating` and, where there is one, the `href` of the review itself. An empty list draws nothing

package/.llm/digest/testimonialslider.md

@@ -23,7 +23,7 @@ Customer quotes shown one at a time, each with who said it
 
 ## Props
 
-- **ground** `enum` · default "page" — Which of the page's grounds the section paints, and with it the card's fill: the recessed surface on the page, the raised white on the grey band — the reference design's slate testimonial — and the strong card on the dark band, gray.900 in both themes, so the card has an edge on each. …
+- **ground** `enum` · default "page" — Which of the page's grounds the section paints, and with it the card's fill: the recessed surface on the page, the raised white on the grey band — the reference design's slate testimonial — and the strong card on the dark band, slate.850 in light and slate.900 in dark, a step above the band in both, so the card has an edge on each. …
   - `page` — The default, and the page's own white. The card is the recessed gray that sets it off
   - `subtle` — The grey band, the reference design's ground for this section. The card turns white on it. …
   - `strong` — `color.bg.brand-strong`, the dark band, for a section a reader should arrive at. …

package/.llm/digest/typography.md

@@ -48,6 +48,24 @@ Sets text in one of the type roles
   - `h5` — A heading under an h4
   - `h6` — The deepest heading level
   - never: Anything interactive. A link is Link and a control is Button — an element that responds to a click needs a name, a focus ring and a keyboard route, none of which this has
+- **motion** `enum` · optional — The figure moves once, on arrival — when it is well into view, when the block bringing it in has landed, or, in an IllustrationCard, when the pane has. …
+  - `roll` — A figure the reader would call their own — an amount in a pane, a deposit, a balance in an illustration — rolls into place once: each digit a reel from nought to its value, left to right, a step of motion.duration.stagger apart, over motion.duration.dramatic …
+  - never: A product term — a leverage, a spread, a payout rate, a price. A figure counting up reads as a live quote, so it rolls only an illustrative amount, and never a profit climbing upward. Nor more than one moving thing in a pane: one lead motion per pane
+- **from** `string` · optional — The words this text starts as, which give way once to the words it is — "Opening…" to "Position open", "EUR/USD · Buy" to "EUR/USD · Sell". …
+  - never: Words a reader must read to act, or a sequence of more than two. The first words are on screen for a second and are not read out — what is read is the text's own words — so nothing the reader needs may live only in them. Nor beside `motion`, which wins: a figure that rolls draws no earlier words
+
+## The type refuses
+
+- variant="h1" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="h2" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="h3" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="h4" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="h5" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="subtitle" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="body-lg" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="body-md" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="body-sm" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
+- variant="eyebrow" with motion="*" — Only a figure rolls: the motion turns its digits, and a heading or a line of copy rolling digit by digit is a figure pretending to be words
 
 ## Inside it
 

package/.llm/index.md

@@ -9,7 +9,7 @@ need — loading all of them dilutes the relevant one.
 Paths here are from the package root, so they resolve whether this file is read in place
 or its content handed over on its own.
 
-Sections: Core (54) · Layout (5) · Blocks (31)
+Sections: Core (60) · Layout (5) · Blocks (35)
 
 
 ## Core
@@ -21,7 +21,7 @@ Domain-neutral building blocks.
 | Component | Use when | Not for |
 |---|---|---|
 | AccordionItem | One row inside an Accordion — every row of a set is one of these · A single disclosure with no set around it: one topic whose detail is worth offering and not worth showing. The row is whole on its own, and it keeps its own open state when nothing is injecting one | The heading goes somewhere rather than opening something → `CardButton` |
-| Background | A band that has to stand apart from the page around it with more than a change of fill — the opening of a landing page, a call to action, a section that closes a long page · A dark band that would otherwise be a flat slab. The glow gives it a centre for the eye, which is where the band's heading or its action should sit · A light page that wants one moment of brand colour without a coral block: the dots carry the colour at a fraction of the area a fill would | The band only needs separating from the page around it → nothing here · The ground is a picture or a video → `AspectRatio` |
+| Background | The page's one patterned band, between its hero and its closing call to action, on a section built by hand rather than from a block — a heading stacked over what it introduces, centred, with the band's foot left open, because every pattern rises from the foot · Inside a block that offers it, as that block's `background` prop — FeatureCards, Stats, TestimonialRow and LogoRows draw it as their first layer, and LandingHero, PageHeader, CtaBanner, CtaBannerSlider and DownloadBanner their own. Prefer those to a hand-built section | The band is a set of features with a picture each → `FeatureCards` · The band is three to five headline numbers → `Stats` · The band is a row of short reviews → `TestimonialRow` · The band is a strip of partner or payment logos → `LogoRows` · The band opens the page → `LandingHero` · The band asks the reader to act → `CtaBanner` · The ground is a picture or a video → `AspectRatio` |
 | Badge | One of a set is the one the page wants read first — the plan most people choose, the market most people start with · Something is new or has changed, and saying so is worth a word rather than a sentence · A number the page is promoting is worth marking as a saving rather than left in the copy — a percentage off, a period free | What it says is a state the reader's account is in → nothing here · The words are the point rather than the mark → `CardBody` |
 | Breadcrumb | The page sits inside a section hierarchy, and the levels above it are places the visitor can navigate to — a product page inside a markets section, a blog post inside a category · A visitor who arrived by search, social link or campaign URL needs to learn where they landed and how the site is organised around them | The visitor is moving through the stages of a sign-up or onboarding flow rather than standing in a hierarchy → nothing here · There is exactly one place to go back to, and it is the previous page rather than a parent section → nothing here |
 | BreadcrumbItem | Rendering one level of a Breadcrumb — every level in a trail is one of these · The level needs a short name the visitor recognises as a place: the section name, not a sentence about it | The destination is somewhere the visitor goes to act rather than a level they climb back to → nothing here |
@@ -32,10 +32,15 @@ Domain-neutral building blocks.
 | CardButton | The whole card is the target rather than a link buried in it — a grid of features each leading to its own page, a set of markets, a row of plans · Pressing it goes somewhere with a URL of its own. Pass href and the browser's own navigation works: cmd-click opens a tab, the status bar shows the destination, the link can be copied and it can be crawled · Pressing it opens something the page owns rather than leaving the page — a dialog, a video, a step in a sign-up | The card holds a control of its own as well → `Card` · Nothing happens when it is pressed → `Card` |
 | Checkbox | A choice the user makes now and confirms later — the form's Save or Continue is what applies it · Agreeing to something before proceeding — terms, a risk disclosure, a confirmation the user must actively give · One of several independent choices, each of which can be on or off without affecting the others | Choosing exactly one option from a short set, where picking one unpicks the others → `SegmentedControl` · Performing an action rather than recording a choice → `Button` |
 | Divider | Two groups inside one container that nothing else is separating — a footer's link columns, the tiers inside a pricing card, a card's summary above its detail. Where a heading or a surface of its own already tells the groups apart, that is doing this component's job better than it can · A row of items holding one that belongs to a different set from its neighbours — the vertical case. A legal line beside a copyright notice, a language picker at the end of a nav. It takes its height from the row rather than declaring one, so it is as tall as whatever it stands between · A word between two rules, where that word is the entire content of the divide: OR between two ways of signing up, and little else. The rules either side are what make it read as a fork rather than as a heading | The groups have names → `Typography` · The space between the groups already separates them → nothing here · The line wanted is the edge of a surface → `Card` · The line wanted is the rail under a tab strip → `TabList` |
+| DocumentLink | A document on a legal, regulatory or help page — a policy, a key information document, a licence, a form · Many documents of one kind, listed or laid in a grid inside a Documents block | One to four related pages or documents at the end of a section → `ResourceBanner` · A link inside a sentence, or a page rather than a document → `Link` |
 | DropdownMenu | A set of destinations too long for the navigation bar and too short to be a page of its own — languages, regions, the parts of a long index · The set is short enough to read at a glance, where a visitor is choosing rather than searching | The set reports a choice the visitor should find marked when they return → nothing here · The destinations belong in the page's navigation → nothing here · It is one destination rather than one of a set → nothing here · The set is long enough that a visitor would rather type than read → nothing here |
 | FooterGroup | A set of a footer's destinations belong under one word — Markets, Support, Legal · The footer has enough links that a reader scanning it needs sets rather than a list | The destinations are the ones a visitor most likely wants → `Navbar` · The group is a named set inside a navigation panel → `NavbarMenuGroup` · There is one link rather than a set → `Link` |
 | Icon | A glyph stands beside words to speed recognition — a mark on a feature card, a chevron on a row, a separator in a trail · A page is composing something a component offers a slot for, and the slot takes a mark rather than a component that draws one | The mark identifies a company or a product — a payment method, an app store, a social network → `Logo` *(not built yet)* · The artwork is a scene rather than a symbol → `Illustration` *(not built yet)* |
 | IllustrationCard | Product information laid over a photograph or a piece of art — a market's price and status over a picture of a trader, a balance over a device · A standalone image of the product beside a section's words, where a screenshot would be too literal: the pane is the picture the section shows · Several such pictures across a site that have to agree in shape and surface without each page deciding | A section has content to present — features, benefits, steps, a list → `FeatureCards` · The content is something a reader acts on — a link, a form, a set of options → `Card` · There is only a photograph → `AspectRatio` |
+| IllustrationCheck | A pane, or any picture of the product, showing that something has gone through — a deposit received, an identity verified · The moment of confirmation is the point of the picture, played once with `motion="resolve"` | Something is still loading on a real page → `Spinner` · A tick beside words in a list or a field → `Icon` |
+| IllustrationChoice | A pane, or any picture of the product, showing a choice — a demo account or a real one, a plan, a market · The choosing is the point of the picture, played once with `motion="pick"` | The reader makes the choice on this page → `SegmentedControl` · A choice between two or three short words, side by side → `SegmentedControl` |
+| IllustrationCode | A pane, or any picture of the product, showing a verification step — confirming it is you, two-step sign-in · The code going in is the point of the picture, played once with `motion="fill"` | The reader types a code on this page → `TextInput` |
+| IllustrationList | A pane, or any picture of the product, listing a few things — the forex pairs on a platform, the documents a check needs · The list arriving is the point of the picture, played once with `motion="arrive"` | A list of benefits or features the page itself is making → `FeatureBullets` · A data table the reader compares across → `Table` |
 | IllustrationScene | Product information shown over a photograph — a trade ticket, a balance, a market's status — where the photograph sets the scene and the card says what the product does · A hero or a feature section needs a picture of the product in use rather than a screenshot or a photograph alone | The card stands on its own, with no photograph behind it → `IllustrationCard` · There is only a photograph → `AspectRatio` |
 | Link | A term inside running copy has a page of its own — a market named in a paragraph, a fee mentioned in a sentence, a product referred to in passing · The page must offer a destination without pushing it: terms, a full fee schedule, a regulatory notice. A pill would give it the weight of the thing the page is actually asking for · A second destination beside the call to action, where a second pill would be two things asking to be pressed and a reader would have to choose between them before reading either | The destination is the step the page was built to produce → `Button` · Pressing it does something on this page rather than going somewhere → nothing here · The whole card or panel is the target rather than some words in it → `CardButton` |
 | MenuItem | A row in a menu of destinations — a language, a region, a page number an index skipped · A set short enough to read at a glance, where a reader is choosing rather than searching | The row reports a choice the reader should find marked when they return → nothing here · The destination belongs in the page's navigation → nothing here · It is one action rather than one of a set → nothing here |
@@ -43,6 +48,7 @@ Domain-neutral building blocks.
 | NavbarMenuGroup | A section's panel holds more destinations than a reader takes in at once, and they fall into sets — markets, tools, payments · Two lists in a panel would be told apart by nothing if the words above them were taken away | The panel holds few enough destinations that naming sets would be naming one thing each → `NavbarItem` · The set is a section of the site rather than a set within one → `NavbarMenu` |
 | Option | An answer inside a control that opens a list — a SelectChip today. One of these per option in the set | Pressing it should do something rather than record an answer → `MenuItem` · The row is one of a few and all of them fit on the page → `FilterChip` |
 | PaginationDots | Showing where the reader is in a short sequence they move through — a slider's slides, a carousel of cards, the steps of a walkthrough — and letting them jump to any of it | A set divided into pages of results → `Pagination` |
+| ProgressBar | A task has measurable completion and the user needs to see how much is done · A longer operation — uploads, setup, or processing — needs progress feedback to reassure the user | The work has no measurable end — connecting, waiting on a system that reports nothing → `Spinner` · The task finishes as fast as a reader can notice → nothing here |
 | SearchInput | A help centre, a knowledge base, or documentation — more pages than a menu can carry · A blog or resource index a reader arrives at knowing roughly what they want · A directory the page already holds and can filter as the reader types — markets, offices, partners | The field is part of a form the reader will submit → nothing here · The set is small enough to show at once → nothing here · The reader is choosing from known options rather than describing what they want → nothing here |
 | SegmentedControlItem | One option in a SegmentedControl — the thing a reader presses to change which of a few mutually exclusive values is in force · A choice worth showing beside its alternatives rather than hiding in a list, so the reader compares and picks in one glance | The option names a slice of the page the reader moves to rather than a value they set → `Tab` · The choice is on or off rather than one of several → `Button` · The option leads somewhere → `Link` |
 | Select | A form asks for one answer out of a set the visitor recognises — a country, a language, the reason they are getting in touch · An index or a table is worth narrowing, and the choice reshapes the page rather than being submitted — the sort on a list of articles, the market a pricing table shows · The set is long enough that showing it in full would crowd the page, which is what separates this from a row of chips or a segmented control | The set is a handful and worth comparing side by side → `SegmentedControl` · The choices are destinations rather than answers → `DropdownMenu` · The reader can pick more than one → nothing here · The answer is not on the list, and typing one should stand → nothing here |
@@ -104,6 +110,7 @@ The sections a page is built from, and the rhythm between them.
 | CtaBanner | A short, high-contrast promotion with one clear action — open an account, start trading, download the app · The band that closes a page, or breaks a long one, on the action the page exists to produce | Two or three promotions to rotate between → `CtaBannerSlider` · The band that opens the page → `LandingHero` · A message that needs a picture beside it → `FeatureSplit` |
 | CtaBannerSlider | Rotating between two or three genuinely different promotions without a hero's weight — open an account, try a tool, download the app | One promotion → `CtaBanner` · The band that opens the page → `LandingHero` · A message with more than a headline, a line and a button or two → `FeatureSplit` |
 | DataTable | Trading instruments and their specifications — contract size, minimum size, volume limits — on a market page · Trading conditions a reader looks up rather than reads through: spreads, leverage, margin, swaps · An MT5 or Deriv X specification page, where the set runs to dozens of rows and a reader is hunting for the one they trade | Three or four plans or accounts compared feature by feature, where every row is read rather than searched → `ComparisonTable` · A handful of rows with no need to search or page — a fee schedule of four lines → `Table` |
+| Documents | A legal or regulatory page's documents — key information documents grouped by product, policies, terms · A document per country, region or entity, each behind its flag or mark — `layout="grid"` · Any list of more documents than a ResourceBanner's four | One to four documents or pages at the end of a section → `ResourceBanner` · Questions and their answers → `FaqAccordion` |
 | DownloadBanner | Promoting an app across the stores and platforms it ships on — App Store, Google Play, AppGallery, a desktop download, the web · A trading platform's page, near its end, once the product has been explained and the next thing a reader wants is to get it | One download, or the web alone → `Button` · A promotion that has to argue for the download in a headline and a sentence → `CtaBanner` |
 | Estimator | A page lets a reader work something out before they act — a margin, a pip value, a swap charge, a conversion, an income estimate · The figures change as the reader types or picks, and should be announced as they do · The same tool appears on several pages in several forms — the margin, pip and swap calculators are one layout with different fields and figures | The figures are fixed facts rather than the result of anything the reader enters → `Stats` · Options are compared side by side rather than worked out from an input → `ComparisonCards` · The tool is a form that sends something — a sign-up, a contact request → `FeatureSplit` |
 | FaqAccordion | The questions a reader asks before acting — fees, limits, how long a withdrawal takes — near the end of a landing page or on a help page · Objections a page has to answer without making every reader read every answer | The answers are short enough to read all at once → `FeatureBullets` · Each item is a feature, not a question → `FeatureCards` |
@@ -113,6 +120,7 @@ The sections a page is built from, and the rhythm between them.
 | FeatureScroll | 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 | 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` |
 | FeatureSplit | 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 | 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` · The picture is the section's weight, wide or tall enough to stand under the words rather than beside them → `FeatureStack` |
 | FeatureStack | A statement with a picture that carries it — a global reach shown on a globe, a platform shown on a device — where the picture is the section's weight and the words introduce it · Closing a page or a stretch of one on an image, with a way on for the reader who wants more | The picture belongs beside the words, the two read side by side → `FeatureSplit` · The section is a set of figures read as a set → `Stats` · The section asks the reader to do one thing, now → `CtaBanner` |
+| FeatureTabs | Several versions of one thing a reader takes one at a time — a product's trade types, a platform's apps, the account types · A section whose versions each need a picture, a line and a way onward, and only one is worth showing at once | One claim and one picture, with nothing to list → `FeatureSplit` · Two or three plans or account types compared feature by feature → `ComparisonCards` · Showing the same section's content for a monthly or a yearly price → `TabList` |
 | ImageBanner | Driving a single mid-page or end-of-page action with a photograph to carry it — a community, a hub, a platform · A dark, editorial break between lighter sections | The section opens the page → `ProductHero` · The point wants the page's own light ground rather than a dark card → `FeatureSplit` · There is no photograph, only a headline and an action → `CtaBanner` · The section says what a programme or a product comes with, as a list of features → `FeatureBullets` |
 | LandingHero | A main landing page needs its opening band — the front page, or a campaign page under it · The claim has room to range to the reading edge with a subject beside it, which is what the landing tier is for · The steps between an eyebrow, a title, a description and the actions under them have to be the same on every landing page | The page is a product or a market page → `ProductHero` · The page is a company or a legal one — contact, about, terms → `PageHeader` · The band closes the page rather than opening it → `Footer` |
 | LogoColumns | Showing the partners, integrations or payment methods behind a claim — the names a reader recognises, as evidence for what the words say · Eight or more logos, enough that each column reads as running on past both edges of the wall | A handful of logos a reader should be able to count and compare → `Grid` · One picture beside the claim → `FeatureSplit` · Each logo needs to be pressed — a partner directory → `FeatureCards` |
@@ -120,8 +128,10 @@ The sections a page is built from, and the rhythm between them.
 | PageHeader | A company, legal or support page needs its opening band — contact, about, terms, a regulatory notice · The page is read rather than acted on, so its opening should name it and then get out of the way · The steps between an eyebrow, a title and a description have to be the same on every such page | The page is the front page, or a campaign page under it → `LandingHero` · The page is a product or a market page → `ProductHero` · The band closes the page rather than opening it → `Footer` |
 | ProductHero | A product or a market page needs its opening band — a platform, an instrument, an asset class · The thing the page is about is worth showing whole, under the claim rather than beside it · The steps between an eyebrow, a title, a description and the actions under them have to be the same on every product page | The page is the front page, or a campaign page under it → `LandingHero` · The page is a company or a legal one — contact, about, terms → `PageHeader` · The band closes the page rather than opening it → `Footer` |
 | ResourceBanner | Pointing readers at related guides, policies, or reference pages at the end of an informational section — the 'here's where to read more' block · A section of a legal, help or safety page has said what it has to and the detail lives elsewhere — the full terms, a risk disclosure, a help-centre article | The block asks the reader to do something — open an account, start trading → `CtaBanner` · The resources are a set of destinations each worth a heading and a sentence → `FeatureCards` · The reader's questions have short answers that can be given on the page → `FaqAccordion` |
-| SceneScroll | Two states of one thing a page wants felt rather than listed — the markets by day and by night, a trader's screen before and after, a market open around the clock · One immersive moment on a product or campaign page, between lighter sections, where two photographs carry the argument and the words are a heading and a line each · The opening band of a campaign page built around that change, at headingLevel h1 | There is one photograph, not two states of something → `ImageBanner` · Three or more things to show, each with a picture → `FeatureScroll` · The page's opening band, with an action to take → `LandingHero` · One statement on its own, revealed as the reader scrolls → `TextScroll` |
-| Stats | Three to five headline numbers that prove scale or credibility — traders, markets, years, the smallest deposit — where the set is the point — read along a row from the fold, turned through one at a time on a phone · A break between two heavier sections, when the numbers alone tell the story | Each item needs a sentence of its own, or a picture → `FeatureCards` · The number is part of a claim the page is making in words → `FeatureSplit` |
+| SceneScroll | Two states of one thing a page wants felt rather than listed — the markets by day and by night, a trader's screen before and after, a market open around the clock · One immersive moment on a product or campaign page, between lighter sections, where two photographs carry the argument and the words are a heading and a line each · The opening band of a campaign page built around that change, at headingLevel h1 | The two scenes are one claim with one word changed — "Trade all day", "Trade all night" → `SceneScrollWord` · There is one photograph, not two states of something → `ImageBanner` · Three or more things to show, each with a picture → `FeatureScroll` · The page's opening band, with an action to take → `LandingHero` · One statement on its own, revealed as the reader scrolls → `TextScroll` |
+| SceneScrollWord | Two states of one thing that one claim covers with one word changed — trade all day and all night, markets open and markets closed, before and after · One immersive moment on a product or campaign page, where the claim is the argument and the two photographs show its two halves · The opening band of a campaign page built around that claim, at headingLevel h1 | The two scenes say different things, each with a title of its own → `SceneScroll` · The two scenes are one claim with one word changed — "Trade all day", "Trade all night" → `SceneScrollWord` · There is one photograph, not two states of something → `ImageBanner` · Three or more things to show, each with a picture → `FeatureScroll` · The page's opening band, with an action to take → `LandingHero` · One statement on its own, revealed as the reader scrolls → `TextScroll` |
+| Stats | Three to five headline numbers that prove scale or credibility — traders, markets, years, the smallest deposit — where the set is the point — read along a row from the fold, turned through one at a time on a phone · A break between two heavier sections, when the numbers alone tell the story | Each figure is a moment rather than a column to compare, beside the awards behind it → `StatsCarousel` · Each item needs a sentence of its own, or a picture → `FeatureCards` · The number is part of a claim the page is making in words → `FeatureSplit` |
+| StatsCarousel | A trust band where each figure is a moment rather than a column to compare — monthly deals, customers, volume, years in business · The figures stand beside the awards behind them · A band between lighter sections that wants one moving thing in it | Three to five figures a reader compares at a glance → `Stats` · A page's full list of awards → `Awards` |
 | Steps | A page explains a get-started or onboarding flow — opening an account, funding it, starting to trade · A process has three to six steps that a reader follows in one order, each a short imperative and a sentence · A setup or a how-to page — a platform's install, a deposit or a withdrawal — needs its sequence shown beside one picture · The same how-it-works list, walked through on its own: with `autoplay` each step takes its turn, its rule filling as it holds, and the picture changes to that step's — a sequence shown in sequence rather than all at once | The items have no order a reader follows — they are things a product includes → `FeatureBullets` · Three or four things side by side, each with its own picture → `FeatureCards` · Each stage needs a screen and a picture of its own → `FeatureScroll` |
 | StickyCards | 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 | 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 |
 | TeamGrid | 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 | One person, spotlit, in their own words → `TestimonialSlider` · The items are not people — logos, features, figures → `FeatureCards` |

package/.llm/rules.md

@@ -29,6 +29,16 @@ Nested interactive elements produce ambiguous hit targets and an unreachable inn
 
 Guidance only — cannot be checked automatically.
 
+### A page has at most one patterned band, between its hero and its closing call to action
+
+A patterned ground — the halftone, the aurora, the mesh, the grid or the rings — is what makes a band the one a reader stops at, and it only works by being the exception. So a page has at most one, placed between its hero and its closing call to action; the hero's and the call to action's own patterns are theirs and do not count, and the band never goes on either of them.
+
+The pattern is the band's first layer, under its content and over nothing. A block that can carry one says so with its own `background` prop — FeatureCards, Stats, TestimonialRow and LogoRows — and draws it there; a section built by hand places a Background with nothing in it as its first child. Never wrap a block in a Background: the block paints its own ground over the pattern and hides it.
+
+Only a band whose content is stacked can carry one. Every pattern rises from the band's foot, so the band needs a heading over what it introduces, centred, with the foot left open. A band whose content runs side by side — words beside a picture, a split, columns reaching the foot — puts the glow behind the picture or under the words; it stays on its flat ground.
+
+Guidance only — cannot be checked automatically.
+
 ### A section that paints a ground sets the ink to go with it
 
 A page sits on color.bg.page, and a section that separates itself from it takes one of three grounds. color.bg.subtle is the light one and needs nothing further — the page's own ink still reads on it. The other two are dark and do not: color.bg.brand-strong takes color.fg.on-brand-strong, and color.bg.brand takes color.fg.on-solid. Both are white, and both are written as the role rather than the white they resolve to. Set one of those backgrounds without its ink and the text inherits whatever the page was already using, which is near-black on a dark band — legible to nobody, and invisible to every check here, because each pair passes contrast on its own and nothing can tell whether a section used both.

package/.llm/tokens.md

@@ -11,6 +11,8 @@ one value at every width.
 
 ## color
 
+- `--color-bg-accent-slate` — Decorative surface, no status meaning, e.g. a category badge. The dark, cool accent; it sits close to color.bg.brand-strong, so keep it off dark bands. Never the sole carrier of a distinction. Pair with color.fg.on-solid for text.
+- `--color-bg-accent-slate-subtle` — Lightweight decorative fill, e.g. a category badge, a tinted panel. No status reading. Pair with color.fg.accent-slate for text.
 - `--color-bg-active` — Pressed state for interactive elements. Alpha-based like the hover and one step heavier, so it tints whatever surface it lands on — ink on light and paper on dark.
 - `--color-bg-active-inverse` — Pressed state for an interactive element on a surface that runs against the mode, one step heavier than color.bg.hover-inverse. The mirror of color.bg.active, and paired with it on the same reasoning.
 - `--color-bg-active-on-brand-strong` — Pressed state for an interactive element standing on color.bg.brand-strong, one step heavier than color.bg.hover-on-brand-strong. White at eight in both modes. For a surface that flips with the mode use color.bg.active-inverse.
@@ -19,7 +21,7 @@ one value at every width.
 - `--color-bg-brand-active` — Pressed state for color.bg.brand. One step further along the ramp than the hover, in the same direction, so a press reads as more of what the hover began.
 - `--color-bg-brand-deep` — The brand's darkest red, the same in both themes — a shade in a pattern drawn in the brand's reds, e.g. the deepest pool of Background's mesh. Not a ground for words: color.bg.brand-subtle is the tint that turns with the theme.
 - `--color-bg-brand-hover` — Hover state for color.bg.brand.
-- `--color-bg-brand-strong` — A dark surface, for a band breaking a long page or a card carrying more weight than its neighbours, e.g. a feature band, the footer. gray.950 in light and dark alike, so the band is the same wherever it is drawn. Pair with color.fg.on-brand-strong for text.
+- `--color-bg-brand-strong` — A dark band breaking a long page, or a weightier card, e.g. a feature band, the footer. slate.900 in light, slate.950 in dark so it sits into a dark page. Pair with color.fg.on-brand-strong.
 - `--color-bg-brand-subtle` — A brand ground quiet enough to read dark ink on. The solid coral takes white at 3.39:1 and is waived for a word; this pairs with color.fg.brand well past the bar, so a mark can be brand-coloured without spending the waiver.
 - `--color-bg-danger` — Destructive action surface, e.g. cancel subscription, delete account. Pair with color.fg.on-solid for text.
 - `--color-bg-danger-subtle` — Lightweight danger fill, e.g. error banners, danger badges. Pair with color.fg.danger for text.
@@ -45,8 +47,9 @@ one value at every width.
 - `--color-bg-surface-card-light` — A light card that stays light whatever the theme, e.g. a surface-light Card or CardButton set among dark ones. gray.50 in both modes. Pair with color.fg.on-surface-card-light; for a card that follows the theme use color.bg.surface.
 - `--color-bg-surface-card-light-raised` — The light card on a subtle band. White in light mode, where the band is the light card's own gray.50 and it would vanish; gray.50 in dark, where the band is a tint over near-black. Pair with color.fg.on-surface-card-light.
 - `--color-bg-surface-card-raised` — A card lifting off the ground behind it, e.g. a Card or CardButton on a color.bg.subtle band. White in light, white at six in dark, so a dark card tints the band instead of sitting on it as grey. Menus and popovers take color.bg.surface-raised.
-- `--color-bg-surface-card-strong` — The dark fill of a card weightier than its neighbours, e.g. an accent-strong Card or CardButton. gray.900 in both modes, a step lighter than color.bg.brand-strong so it reads as a card, not a band.
-- `--color-bg-surface-card-strong-raised` — The strong card on a subtle band. gray.900 in light mode, the strong card's own fill, which already stands off the gray.50 band; gray.800 in dark, where the band is a near-black tint the strong card would blend into. Pair with color.fg.on-brand-strong.
+- `--color-bg-surface-card-strong` — The dark fill of a card weightier than its neighbours, e.g. an accent-strong Card or CardButton. slate.900 in both modes, the same as color.bg.brand-strong, so on a dark band it reads by its media and edge rather than by a step of fill.
+- `--color-bg-surface-card-strong-on-brand-strong` — The strong card on a color.bg.brand-strong band, e.g. a logo tile. A step above the band: slate.850 in light, slate.900 in dark. On the page use color.bg.surface-card-strong.
+- `--color-bg-surface-card-strong-raised` — The strong card on a subtle band. slate.900 in light mode, the strong card's own fill, which already stands off the gray.50 band; slate.800 in dark, where the band is a near-black tint the strong card would blend into. Pair with color.fg.on-brand-strong.
 - `--color-bg-surface-glass` — A pane of glass over whatever is behind it, e.g. an IllustrationCard on a band. Light glass in light mode, a faint frosted white in dark, with a blur behind it in both; ink is color.fg.default.
 - `--color-bg-surface-inverse` — The quieter of the two surfaces on a dark ground, for a panel rather than a pill. color.bg.surface-raised-inverse is the stronger lift and is right on a control the size of a navbar's; at that weight a card-sized box reads as a pale patch rather than a surface.
 - `--color-bg-surface-modal` — A surface that covers the page behind a scrim — dialogs, drawers, bottom sheets. The topmost plane there is, so it stays white in light where color.bg.surface is recessed. For one that floats without dimming what is under it use color.bg.surface-raised.
@@ -63,6 +66,7 @@ one value at every width.
 - `--color-bg-transparent` — A fill that is declared and not seen, for an element whose own surface must show through rather than whatever a page happens to sit it on. Needed because omitting the background would leave that surface showing instead.
 - `--color-bg-warning` — Caution surface, e.g. limited offer, expiring promotion. Pair with color.fg.on-solid for text.
 - `--color-bg-warning-subtle` — Lightweight warning fill, e.g. warning banners, warning badges. Pair with color.fg.warning for text.
+- `--color-border-accent-slate` — Decorative edge, no status meaning, e.g. an accent container's outline.
 - `--color-border-danger` — Error validation border, e.g. input with failed validation, error banner edge.
 - `--color-border-default` — Standard border for containers and controls, e.g. input outlines, grouped sections.
 - `--color-border-focus` — The keyboard focus indicator — a border on some controls, a ring on others. Never remove: required for accessibility. Neutral rather than blue, so it is never mistaken for the danger a control is also able to show. Inverts by mode.
@@ -72,10 +76,12 @@ one value at every width.
 - `--color-border-pattern` — The resting lines of a decorative rule grid on the page's ground. A step above color.border.subtle, which a hairline across a whole band thins to nothing; well below the default border, so the grid reads as texture.
 - `--color-border-pattern-inverse` — The resting lines of a decorative rule grid on a dark or coral ground. White at a quarter in both modes, as those grounds are; a step above color.border.subtle-inverse, which a hairline grid thins to nothing.
 - `--color-border-strong` — Emphasised border for active or prominent elements, e.g. active input, selected card edge.
+- `--color-border-strong-inverse` — An emphasised edge on a dark or coral ground, e.g. a secondary button's outline on color.bg.brand-strong or the brand band. The counterpart to color.border.strong; white at 64% in both modes, as the band is the same in both.
 - `--color-border-subtle` — A quiet separator, e.g. dividers, table rules. Alpha-based — works on any surface.
 - `--color-border-subtle-inverse` — A quiet rule on a dark ground. The counterpart to color.border.subtle, which is black at 5% and invisible on one.
 - `--color-border-success` — Success validation border, e.g. confirmed input, success banner edge.
 - `--color-border-warning` — Warning validation border, e.g. approaching-limit input, warning banner edge.
+- `--color-fg-accent-slate` — Decorative text and icons, no status meaning, e.g. a category label. Reads on the page and on color.bg.accent-slate-subtle.
 - `--color-fg-brand` — Brand-coloured text, for a mark or a line on color.bg.brand-subtle. Not for text on the page: the brand is a colour a page uses to point at something, and copy set in it is a page pointing at all of itself.
 - `--color-fg-brand-accent` — The brand label at full saturation — the brand fill's own red, the same in both modes, so a label and a fill agree. For the one row a reader is already on. Only on the bare page, never a tint. 3.11:1 as text, under AA: never the only thing saying it.
 - `--color-fg-danger` — Error and destructive text on neutral surfaces, e.g. validation messages, negative values.
@@ -86,6 +92,7 @@ one value at every width.
 - `--color-fg-muted-inverse` — Supporting copy on a dark ground, e.g. a footer's group labels. White at sixty-four, so it takes the hue of whatever the band is painted rather than sitting cool against a warm one — and so it stays muted on any dark ground instead of on one.
 - `--color-fg-on-brand` — Text and marks on color.bg.brand, e.g. a primary button's label, a checked accent checkbox's tick. White in light and dark alike, because the brand fill does not change with the theme. For other solid fills — danger, success, info — use color.fg.on-solid.
 - `--color-fg-on-brand-strong` — Text and glyphs on color.bg.brand-strong. White in both modes, that surface being dark in both — unlike color.fg.on-solid, which follows the theme.
+- `--color-fg-on-media-light` — Text set straight on a light photograph with no scrim, e.g. a SceneScroll scene over a daylight sky. gray.950 in both modes, because the photograph does not change. Over a dark photograph use color.fg.on-brand-strong.
 - `--color-fg-on-solid` — Text on solid status fills, e.g. danger, success, info buttons and badges. For text on color.bg.brand use color.fg.on-brand; on neutral surfaces use color.fg.default.
 - `--color-fg-on-strong` — Text on color.bg.strong. The opposite extreme from the fill, so the pair is always near-black on white or white on near-black.
 - `--color-fg-on-strong-on-brand` — Text and glyphs on color.bg.strong-on-brand, the near-black fill on the coral band. White in both modes, because the fill does not change — unlike color.fg.on-strong, which follows the theme.
@@ -172,6 +179,8 @@ one value at every width.
 - `--size-menu-panel-min` — The shortest a section's menu panel gets, whatever it holds. A bar's sections rarely have the same number of destinations, and panels that each took their own height would change size as the reader moved along the row.
 - `--size-menu-max` — The tallest a menu's surface gets before its commands scroll. Product's measure, and counted in rows: five whole and part of a sixth at either size. Neither lands on a row boundary — a ceiling cutting clean at the last full row looks like the whole set.
 - `--size-mesh-blur` — How far a mesh background blurs its pools into one another. Enough that no pool keeps an edge, so the reds read as one liquid rather than shapes.
+- `--size-progressbar-track-md` — Track height at size md. Default for standalone progress indicators.
+- `--size-progressbar-track-sm` — Track height at size sm. Thin enough for dense layouts and inline indicators.
 - `--size-review-card-min` — The shortest a TestimonialRow card gets. A floor, not a height: a one-line review keeps a card's shape, and a longer one still grows it.
 - `--size-rings-pitch` — How far apart the rings on a band sit, counted out from the middle of its foot. A pitch, as size.rule-grid.pitch is; tighter than the grid's, because rings spaced that wide read as a target rather than a ripple.
 - `--size-rings-spotlight` — How far the pointer's light reaches on the rings: the radius within which they brighten around the pointer and fade to the resting rings. The rule grid's reach, so the two answer the pointer alike.

package/AGENTS.md

@@ -55,6 +55,7 @@ a component you give `onChange` or `onClick` to goes in a file of your own that
 
 - **A component is written along the reading axis, not along the page's left and right**
 - **A navigation bar holds at most two buttons: one primary, and one secondary beside it**
+- **A page has at most one patterned band, between its hero and its closing call to action**
 - **A section that paints a ground sets the ink to go with it**
 - **A section's title is centred over stacked content, starts beside content in columns, and starts on a phone**
 - **Anything a pointer has to hit is at least 24px in both directions**
@@ -80,7 +81,7 @@ screen is built in is not something to reach for while building a control.
 
 - **Accordion** — Questions a reader asks near a decision
 - **AccordionItem** — One row inside an Accordion
-- **Background** — A band that has to stand apart from the page around it with more than a change of fill
+- **Background** — The page's one patterned band, between its hero and its closing call to action, on a section built by hand rather than from a block
 - **Badge** — One of a set is the one the page wants read first
 - **BottomSheet** — A task needs the screen's full width and the reader's undivided attention
 - **Breadcrumb** — The page sits inside a section hierarchy, and the levels above it are places the visitor can navigate to
@@ -92,12 +93,17 @@ screen is built in is not something to reach for while building a control.
 - **CardButton** — The whole card is the target rather than a link buried in it
 - **Checkbox** — A choice the user makes now and confirms later
 - **Divider** — Two groups inside one container that nothing else is separating
+- **DocumentLink** — A document on a legal, regulatory or help page
 - **DropdownMenu** — A set of destinations too long for the navigation bar and too short to be a page of its own
 - **FilterChip** — An index is long enough to be worth cutting down and its categories are few enough to show in full
 - **Footer** — A marketing page needs its closing band
 - **FooterGroup** — A set of a footer's destinations belong under one word
 - **Icon** — A glyph stands beside words to speed recognition
 - **IllustrationCard** — Product information laid over a photograph or a piece of art
+- **IllustrationCheck** — A pane, or any picture of the product, showing that something has gone through
+- **IllustrationChoice** — A pane, or any picture of the product, showing a choice
+- **IllustrationCode** — A pane, or any picture of the product, showing a verification step
+- **IllustrationList** — A pane, or any picture of the product, listing a few things
 - **IllustrationScene** — Product information shown over a photograph
 - **Link** — A term inside running copy has a page of its own
 - **MenuItem** — A row in a menu of destinations
@@ -111,6 +117,7 @@ screen is built in is not something to reach for while building a control.
 - **Option** — An answer inside a control that opens a list
 - **Pagination** — An index or archive has been split across pages and the reader needs to move through it
 - **PaginationDots** — Showing where the reader is in a short sequence they move through
+- **ProgressBar** — A task has measurable completion and the user needs to see how much is done
 - **RemovableChip** — An index shows the narrowings currently applied above its results, and each has to come off on its own without clearing the rest
 - **SearchInput** — A help centre, a knowledge base, or documentation
 - **SegmentedControl** — Two to four alternatives that exclude one another, where the whole set is worth showing at once and the reader decides by weighing them side by side rather than recalling which exist
@@ -149,6 +156,7 @@ screen is built in is not something to reach for while building a control.
 - **CtaBanner** — A short, high-contrast promotion with one clear action
 - **CtaBannerSlider** — Rotating between two or three genuinely different promotions without a hero's weight
 - **DataTable** — Trading instruments and their specifications
+- **Documents** — A legal or regulatory page's documents
 - **DownloadBanner** — Promoting an app across the stores and platforms it ships on
 - **Estimator** — A page lets a reader work something out before they act
 - **FaqAccordion** — The questions a reader asks before acting
@@ -158,6 +166,7 @@ screen is built in is not something to reach for while building a control.
 - **FeatureScroll** — A page has three or more things of the same kind to explain, each with a picture worth a screen
 - **FeatureSplit** — A page needs one more point about something it has already introduced, with a picture to carry it
 - **FeatureStack** — A statement with a picture that carries it
+- **FeatureTabs** — Several versions of one thing a reader takes one at a time
 - **ImageBanner** — Driving a single mid-page or end-of-page action with a photograph to carry it
 - **LandingHero** — A main landing page needs its opening band
 - **LogoColumns** — Showing the partners, integrations or payment methods behind a claim
@@ -166,7 +175,9 @@ screen is built in is not something to reach for while building a control.
 - **ProductHero** — A product or a market page needs its opening band
 - **ResourceBanner** — Pointing readers at related guides, policies, or reference pages at the end of an informational section
 - **SceneScroll** — Two states of one thing a page wants felt rather than listed
+- **SceneScrollWord** — Two states of one thing that one claim covers with one word changed
 - **Stats** — Three to five headline numbers that prove scale or credibility
+- **StatsCarousel** — A trust band where each figure is a moment rather than a column to compare
 - **Steps** — A page explains a get-started or onboarding flow
 - **StickyCards** — A set of markets, products or benefits a page wants read one at a time as the reader scrolls
 - **TeamGrid** — A leadership team, an advisory board or a regional management list on an about page
@@ -187,7 +198,7 @@ saying what to mount and where.
 ## Reading order
 
 1. This file.
-2. `.llm/rules.md` before writing anything — 5,200 tokens, and it is where the constraints
+2. `.llm/rules.md` before writing anything — 5,500 tokens, and it is where the constraints
    that no single component can state live.
 3. `.llm/digest/<name>.md` for every component you are using — **all of it, not the part
    you were looking for**. Around 1,400 tokens each: what it is for, what to reach for

package/dist/components/arrival.d.ts

@@ -0,0 +1,32 @@
+import { type RefObject } from 'react';
+/**
+ * Where a part that moves once on arrival has got to.
+ *
+ * `still` is the resting answer and the part's final state: what a server draws, what a reader who
+ * asked for less movement sees, and what a part with no motion turned on is. `waiting` holds the
+ * motion at its first frame; `playing` runs it, once.
+ */
+export type Arrival = 'still' | 'waiting' | 'playing';
+/**
+ * When a part with a motion of its own — a figure that rolls, a word that swaps, a bar that fills —
+ * plays it. The part sets the answer on itself as `data-arrival`, and its stylesheet holds its
+ * animation paused while that reads `waiting` and lets it run at `playing`. Nothing about the
+ * motion itself is here: the steps, the timings and the easing are the stylesheet's, in the
+ * package's motion tokens.
+ *
+ * A part plays where it is, which is what makes the same motion usable anywhere:
+ *
+ * - inside a host that is itself arriving — an IllustrationCard, which marks itself
+ *   `data-arrival-host` — it follows that, so a pane's parts play when the pane has landed rather
+ *   than each on its own;
+ * - inside a block's reveal (`data-revealed`, see use-reveal.ts) it waits for the block to bring
+ *   it in, and for the part of the block that holds it to finish moving, so it plays on something
+ *   that has come to rest;
+ * - anywhere else it plays once it is well into view — six tenths of it showing — so a figure at
+ *   the foot of a section is not over before a reader reaches it.
+ *
+ * It answers `still` until it is running, for use-reveal's reason: a motion that held a part at
+ * its first frame until a script arrived would leave a reader with no script looking at zeros and
+ * empty boxes. And it fires once, then lets go.
+ */
+export declare function useArrival<T extends HTMLElement>(enabled?: boolean): [ref: RefObject<T | null>, arrival: Arrival];