@deriv-com/dds-marketing 0.2.0 → 1.0.0

package/.llm/rules.md

@@ -95,6 +95,18 @@ Declared rather than emergent. Padding plus contents does clear 24px in several
 
 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.
+
 ## Component rules
 
 ### Destructive actions require a confirmation step (`Button`) *(applies to something not built yet)*
@@ -115,6 +127,18 @@ Quill ships every system glyph three times — light, regular and solid — as s
 
 Guidance only — cannot be checked automatically.
 
+### A navigation bar holds at most two buttons: one primary, and one secondary beside it (`Button`)
+
+The bar's actions are the conversion and the way back in for a reader who already has an account — sign up and log in. That is two things, and they rank: the one the site wants is primary and the other is secondary. A third button is a third thing the bar is asking for, and a row of three pills beside a mark and a set of destinations stops reading as a pair of actions and starts reading as a second navigation.
+
+A single button is the primary. Alone, there is nothing for a secondary to be quieter than, and a bar whose only action is the quiet one has hidden the thing it exists to offer. Two buttons are one primary and one secondary, never two of either: two primaries are two demands, and two secondaries leave the reader to guess which one the site meant.
+
+A switcher is not a button here — a DropdownMenu or a ButtonIcon for the language or the theme — and does not count against the two.
+
+Guidance rather than a count. The bar is drawn with a second copy of an action in compactAction for narrow widths, and a count of Buttons under Navbar cannot tell that slot from utilities or a ranked pair from two primaries. Navbar checks the pair itself, on what utilities is handed, and says so in the console.
+
+Guidance only — cannot be checked automatically.
+
 ### At most one primary button per view (`Button`)
 
 Two primary actions compete for attention; the user cannot tell which one the system wants them to take.

package/.llm/tokens.md

@@ -13,16 +13,19 @@ one value at every width.
 
 - `--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-brand` — Primary action surface, e.g. sign-up button, hero CTA, promotional banner. Pair with color.fg.on-solid for text.
+- `--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.
+- `--color-bg-band-subtle` — A recessed band across the page, e.g. a section of steps or features set apart from the ones around it. gray.50 in light, white at six in dark. For a fill inside a control — a secondary button, a badge — use color.bg.subtle.
+- `--color-bg-brand` — Primary action surface, e.g. sign-up button, hero CTA, promotional banner. The same coral in light and dark; pair with color.fg.on-brand for text.
 - `--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-hover` — Hover state for color.bg.brand.
-- `--color-bg-brand-strong` — A dark brand surface, for a band breaking a long page or a card carrying more weight than its neighbours. brand.1000 in light and brand.900 in dark, where a near-black band would disappear into the page rather than break it.
+- `--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-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.
 - `--color-bg-field` — The ground of a control a reader types into or picks from — a text field, a select, an upload zone. An alpha, so it can never come out the same colour as the container holding it, which a solid can. For the container itself use color.bg.surface.
 - `--color-bg-hover` — Hover state for interactive elements. Alpha-based, so it tints whatever surface it lands on rather than replacing it — ink on light and paper on dark, because a black alpha on a dark surface darkens what is already dark and reads as nothing at all.
 - `--color-bg-hover-inverse` — Hover for an interactive element on a surface that runs against the mode — a dark chip in light. The mirror of color.bg.hover, which tints with the mode and so shows nothing on a ground the mode did not paint. Use color.bg.hover where the mode paints the ground.
+- `--color-bg-hover-on-brand-strong` — Hover for an interactive element standing on color.bg.brand-strong, e.g. a navigation item or a plain icon button on a dark hero. White at four in both modes, because the band does not change. For a surface that flips with the mode use color.bg.hover-inverse.
 - `--color-bg-info` — Informational surface, e.g. info banners, tips. Pair with color.fg.on-solid for text.
 - `--color-bg-info-subtle` — Lightweight info fill, e.g. info badges, inline notices. Pair with color.fg.info for text.
 - `--color-bg-overlay` — Scrim behind modal dialogs and drawers. Blocks interaction with content beneath.
@@ -31,14 +34,26 @@ one value at every width.
 - `--color-bg-readonly` — A field whose value is fixed but still worth reading. Lighter than the disabled ground and at full contrast, which is the distinction: readonly is legible and settled, disabled recedes because it is not actionable.
 - `--color-bg-selected` — The active or current item in a set of choices, e.g. selected nav item, current tab, highlighted row. Not for recessive areas — use color.bg.subtle.
 - `--color-bg-strong` — Inverted neutral fill for an action that has to outrank everything around it — near-black in light and pure white in dark, the highest contrast the page can carry. Not a section ground: a band takes bg.subtle, bg.brand-strong or bg.brand. Pair with color.fg.on-strong.
-- `--color-bg-subtle` — A recessive fill within a section, e.g. alternating content bands, highlighted feature areas. Not for active items — use color.bg.selected.
+- `--color-bg-strong-on-brand` — The solid fill of a control on color.bg.brand, e.g. the primary action on the coral band. Near-black in both modes, because the band does not change — unlike color.bg.strong, which turns white in dark.
+- `--color-bg-subtle` — A recessive fill inside a control or a small area, e.g. a secondary button, a neutral badge. For a band across the page use color.bg.band-subtle; for selected items, color.bg.selected.
+- `--color-bg-subtle-on-brand-strong` — A recessive fill on a painted band — color.bg.brand-strong or the coral color.bg.brand — e.g. a secondary button there. White at six in both modes; hover and press layer color.bg.hover-on-brand-strong and color.bg.active-on-brand-strong over it.
 - `--color-bg-success` — Confirmation surface, e.g. sign-up complete, payment confirmed. Pair with color.fg.on-solid for text.
 - `--color-bg-success-subtle` — Lightweight success fill, e.g. success banners, success badges. Pair with color.fg.success for text.
 - `--color-bg-surface` — A card on the page: one step from the ground, so it reads as recessed against the page and raised on a subtle band. For a card that floats above the page, color.bg.surface-raised.
+- `--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-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.
 - `--color-bg-surface-raised` — A surface that lifts off the one behind it, e.g. a dropdown, a popover, a card on a color.bg.subtle band. A card on the page itself takes color.bg.surface, which reads as recessed against it instead.
 - `--color-bg-surface-raised-inverse` — A raised surface on a ground that runs against the mode — a navigation bar's pill on a dark hero. An alpha rather than a grey step: a hero is often a photograph or a brand colour, which a solid surface would clash with.
+- `--color-bg-surface-raised-on-brand-strong` — A raised surface on color.bg.brand-strong, e.g. the navigation bar's pill on a dark hero. White at twenty-four in both modes, because the band does not change. For one that flips with the mode use color.bg.surface-raised-inverse.
+- `--color-bg-surface-translucent` — The base of a see-through surface with a blur behind it, e.g. the navigation bar's pill. Nearly opaque in its own ink — white in light, black in dark — so what scrolls behind cannot set its colour. color.bg.surface-translucent-tint goes over it.
+- `--color-bg-surface-translucent-on-brand-strong` — The base of a see-through surface on color.bg.brand-strong, e.g. the navigation bar's pill on a dark hero. Black at eighty-eight in both modes, so a light photograph behind cannot wash it out.
+- `--color-bg-surface-translucent-tint` — The lift laid over color.bg.surface-translucent, e.g. the navigation bar's pill. None in light, where the base is already the surface; white at sixteen in dark, which is what makes the pill read as a surface over the page.
+- `--color-bg-surface-translucent-tint-on-brand-strong` — The lift laid over color.bg.surface-translucent-on-brand-strong, e.g. the navigation bar's pill on a dark hero. White at twelve in both modes, because the band does not change.
 - `--color-bg-track` — The channel a thing travels or fills along — a grab handle on a sheet, a rail. An alpha rather than a ramp step, so it darkens whatever is behind it and stays a groove on a raised panel, where a fixed grey would stop matching the moment the surface changed.
 - `--color-bg-track-active` — Pressed state for the same mark. One step further than the hover, in the same direction, so a press always reads as more than a hover.
 - `--color-bg-track-hover` — Hover state for a mark drawn in color.bg.track, which is the only thing in this colour that hovers — a track itself never does. One step more ink, so a pointer over the mark reads as more, never less. An alpha like the track, so it keeps tinting what is behind it.
@@ -49,6 +64,7 @@ one value at every width.
 - `--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.
 - `--color-border-focus-inverse` — The focus ring on a ground that runs against the mode. color.border.focus is near-black, which is invisible on a dark bar — and a focus ring that cannot be seen is the one affordance a keyboard reader has nothing to fall back on.
+- `--color-border-focus-on-brand-strong` — The focus ring on color.bg.brand-strong, e.g. a navigation bar's controls on a dark hero, a footer's links. White in both modes, because the band does not change. For a surface that flips with the mode use color.border.focus-inverse.
 - `--color-border-info` — Informational accent border, e.g. info banner edge, highlighted section.
 - `--color-border-strong` — Emphasised border for active or prominent elements, e.g. active input, selected card edge.
 - `--color-border-subtle` — A quiet separator, e.g. dividers, table rules. Alpha-based — works on any surface.
@@ -63,9 +79,12 @@ one value at every width.
 - `--color-fg-info` — Informational text on neutral surfaces, e.g. links, tips, contextual help.
 - `--color-fg-muted` — Supporting copy, e.g. subheadings, feature descriptions, form labels. Not for content the user must read to act.
 - `--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-solid` — Text on solid coloured surfaces, e.g. brand, danger, success, warning buttons. Not for text on neutral surfaces — use color.fg.default.
+- `--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.
+- `--color-fg-on-surface-card-light` — Text on color.bg.surface-card-light, e.g. a surface-light card's title and copy. gray.950 in both modes, because the card does not change. On the page's own ground use color.fg.default.
 - `--color-fg-on-warning` — Text on a warning surface. Always dark because the warning background is bright in both modes.
 - `--color-fg-required` — The mark that says a field must be filled. The same red as fg.danger and a role of its own, because required is not a verdict — a field carrying an asterisk has not failed anything yet.
 - `--color-fg-success` — Positive text on neutral surfaces, e.g. profit values, confirmation messages.
@@ -74,7 +93,7 @@ one value at every width.
 
 ## space
 
-- `--space-actions-gap` **adapts** — Between two actions side by side. Narrower than any gap around the pair, so they read as one set offering a choice rather than two separate offers.
+- `--space-actions-gap` — The step between two calls to action standing side by side. Eight: they are one decision offered two ways, not two decisions, and the reference design sets them this close on every band. Sixteen read as two separate offers.
 - `--space-control-lg` — Side padding inside a large pill control. Half of size.control.lg, on the same reasoning as the default step. It coincides with space.inset.lg today and is still its own role: one follows a control's height, the other a section's rhythm, and they are free to move apart.
 - `--space-control-md` — Side padding inside a default-size pill control. Half of size.control.md, so the corner radius and the padding are one measure and a label starts where the curve stops. The inset scale has no step here — its steps answer to sections, not to a control's geometry.
 - `--space-control-sm` — Side padding inside a small pill control. Half of size.control.sm, on the same reasoning as the default step — the corner radius and the padding are one measure, so a label starts where the curve stops.
@@ -88,7 +107,7 @@ one value at every width.
 - `--space-gap-xs` — Tightest gap between related elements, e.g. icon and label, inline text pairs.
 - `--space-grid-gutter` **adapts** — The space between two cards, across and down. One value on both axes, so a grid reads as an even field rather than as rows with a seam between them.
 - `--space-heading-content` **adapts** — Between a heading group and the content it introduces, stacked or side by side. Measured from the last part the group actually shows, so a section opens the same way whether or not every part is present.
-- `--space-heading-description-actions` **adapts** — Between a description and the actions under it. The widest step inside the group: the gap is what says the reading has finished and something is being asked.
+- `--space-heading-description-actions` — The step from a description down to what a reader can do about it. Twenty-four, which is the reference design's step on every opening band, and what the mobile override already said.
 - `--space-heading-eyebrow-title` **adapts** — Between an eyebrow and the title under it. The tightest step in the group, because an eyebrow reads as the title's first line rather than as a line of its own.
 - `--space-heading-title-description` — Between a display title and the description under it. Smaller than it looks: a title's leading and descender depth sit inside the gap, and both scale with the type, so a smaller title takes the compact step instead.
 - `--space-heading-title-description-compact` — The same step under a title that is not a display size — a card's, a panel's. Half the measure because the leading above it is half as deep, and what the eye reads is this plus that leading.
@@ -108,6 +127,9 @@ one value at every width.
 
 ## size
 
+- `--size-avatar` — A person's picture beside their words — the author of a testimonial. Forty-eight, round: large enough to recognise a face, small enough to stay a signature under the quote rather than a portrait above it.
+- `--size-backdrop-blur` — How far a see-through surface blurs what is behind it, e.g. the navigation bar over the page it scrolls across. Enough that the words behind it stop reading as words, so the bar's own stay legible.
+- `--size-band-compact` — The least height an opening band takes when it is not a screen tall — a company, legal or support page, where a full viewport would be a wall before the first sentence. Deep enough that the band reads as a band rather than a gap the title fell into.
 - `--size-bar-height` — The height of a collapsed navigation bar, which both bars here take. Declared rather than left to what a page hands the bar: an action beside the mark would otherwise set it.
 - `--size-breakpoint-lg` — Where a bar has room for its destinations. A value to read, not a condition to write: `var()` is not allowed in a query, so the seven stylesheets that bend here still carry 64rem themselves.
 - `--size-breakpoint-md` — Where the phone's type layer stops — the mobile overrides resolve below it, so 767 is the last width that reads as a phone. A value to read, not a condition to write: `var()` is not allowed in a media query.
@@ -116,17 +138,25 @@ one value at every width.
 - `--size-control-lg` — Height of a large control, for a hero or a conversion band. Twice space.control.lg, on the same reasoning as the default step.
 - `--size-control-md` — Height of a default-size control, the same measure product gives its own default. Twice space.control.md, so on a pill the corner radius and the side padding are one measure and a label starts where the curve stops.
 - `--size-control-sm` — Height of a small control — a picker in a navigation bar, a field in a filter row. Half of it is space.control.sm and a quarter is radius.control.sm, the ratio every step of this ramp holds. Desktop only: below what a finger reliably hits.
+- `--size-dot-current` — How wide the current mark in a row of dots stretches, against size.dot.diameter for the rest — a pill three dots long, so where the reader is reads by shape.
 - `--size-dot-diameter` — The mark standing in for one page of a short sequence, or for a status beside a name. Eight: small enough that a row of ten reads as a row rather than as ten controls, and large enough to find at arm's length.
 - `--size-grid-track-lg` — For a cell holding a picture as well as words, or a pricing plan with a list under it. Three fit the page's measure and four do not, which is what makes this the floor for a grid meant to read as three across.
 - `--size-grid-track-md` — The default track floor, for a feature card: a heading and a line or two beneath it. Four of these fit the page's measure, so a grid asking for three has room to spare and drops to two on a tablet rather than at the first sign of pressure.
 - `--size-grid-track-sm` — The narrowest a grid track goes before the grid drops a column. For a cell holding a logo, an icon and a word, or one short claim — six of them clear the page's measure with the page gutter still on both sides.
 - `--size-heading-group-max` — How wide an eyebrow, a title and a description may run as a block. Independent or centred groups take this; one that has to sit on the grid takes eight columns instead, which is a span rather than a measure.
+- `--size-logo-columns-height` — How much of a LogoColumns wall shows at once, from the fold. Tall enough that a column reads as running on past both edges; half of it on a phone.
+- `--size-logo-rows-tile` — The width of a tile on a LogoRows, from the fold; three quarters of it on a phone. Wide enough for a wordmark, narrow enough that a row shows several at once.
 - `--size-measure-description` — How wide a supporting description runs. Wider than a title because it is read rather than taken in, and narrower than long-form because it sits under something.
+- `--size-measure-heading` — The width a centred heading block is held to. Narrower than the page measure, because a title centred across the full 1280 is read from a different edge on every line.
+- `--size-measure-hero-description` — How wide the description under an opening band's title runs, e.g. in LandingHero, ProductHero, PageHeader. Wider than size.measure.description because it is set larger and read once, at the top.
+- `--size-measure-hero-heading` — The width the text column of a band that opens a page is held to, e.g. PageHeader's title and actions. Wider than size.measure.heading because a page's name is set at h1 and 846 breaks it early.
 - `--size-measure-long-form` — How wide running text runs. Past this the eye loses the line it was on when it returns to the left edge, which is the whole reason a measure exists.
 - `--size-measure-title` — How wide a title runs before it wraps. A starting point — eighteen to twenty-four after a look. `ch` is the width of the font's zero, so it is a measure rather than a letter count, and typed string because a Figma variable carries a number.
 - `--size-menu-panel-max` — The widest a section's menu panel gets. Narrower than the page's own measure on purpose: a panel is scanned across with a pointer already on it, and one as wide as the page leaves its last column a long way from the name that opened it.
 - `--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-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-rule-grid-pitch` — How often the rule grid repeats on a band that paints one. A pitch rather than a gap: it is how far apart a decorative line recurs, not the space between two things a reader is comparing.
 - `--size-sheet-handle-height` — The thickness of that handle. At the smallest step the scale has, because a grab bar is a hint that the sheet moves rather than a part of what it holds.
 - `--size-sheet-handle-width` — The width of the grab handle at the top of a BottomSheet. Wide enough to take hold of, narrow enough to read as a grip rather than as a rule across the sheet.
 - `--size-sheet-max` — The widest a BottomSheet gets before it stops growing and centres. A sheet is a small-screen pattern, and one running the width of a desktop is a dialog that arrived from the wrong edge.
@@ -139,6 +169,7 @@ one value at every width.
 - `--size-spinner-sm` — Spinner diameter at size sm. Sixteen, which is the size of the body copy it sits beside — an indicator in a line of text reads as part of the line rather than as something dropped into it.
 - `--size-switcher-panel-width` — The width of a switcher's floating panel. Stated because the panel is out of flow and would otherwise shrink to the trigger it hangs from, wrapping every choice and running the set down the page.
 - `--size-target-min` — The smallest a thing a pointer has to hit may be. Bind it as a minimum on any control whose size would otherwise come from its contents — a pressable card is as big as its words, and one holding a single short line is smaller than a fingertip.
+- `--size-testimonial-art` — The decorative pictures in a TestimonialSlider's corners, as squares. Large enough to read as pictures, small enough to leave the card the quote's.
 - `--size-tooltip-max` — The widest a tooltip gets before its text wraps. Short enough that the eye finds the start of the next line without hunting for it, which is the whole job of a measure — and a tooltip that needs more than two lines is a tooltip carrying something that belongs on the page.
 
 ## radius
@@ -189,12 +220,18 @@ one value at every width.
   - `--font-body-sm-line-height`
   - `--font-body-sm-size`
   - `--font-body-sm-weight`
-- `font.eyebrow` — Uppercase category labels above a headline — section tags, plan badges, feature categories. Carries the size, weight and wide tracking that setting needs; the capitals are the component's, through text-transform, which leaves the accessible name in the case it was written.
-  - `--font-eyebrow-family`
-  - `--font-eyebrow-letter-spacing`
-  - `--font-eyebrow-line-height`
-  - `--font-eyebrow-size`
-  - `--font-eyebrow-weight`
+- `font.eyebrow.lg` — The line that leads into a display claim on an opening band, sized against the heading under it rather than against body text. Sentence case, unlike the small step: capitals are what make a twelve-pixel label a label, and at this size they shout.
+  - `--font-eyebrow-lg-family`
+  - `--font-eyebrow-lg-letter-spacing`
+  - `--font-eyebrow-lg-line-height`
+  - `--font-eyebrow-lg-size` **adapts**
+  - `--font-eyebrow-lg-weight`
+- `font.eyebrow.sm` — Uppercase category labels above a headline — section tags, plan badges, feature categories. Carries the size, weight and wide tracking that setting needs; the capitals are the component's, through text-transform, which leaves the accessible name in the case it was written.
+  - `--font-eyebrow-sm-family`
+  - `--font-eyebrow-sm-letter-spacing`
+  - `--font-eyebrow-sm-line-height`
+  - `--font-eyebrow-sm-size`
+  - `--font-eyebrow-sm-weight`
 - `font.field-label.lg` — The words naming a field in a large form, the step that pairs with a large control. Sized with the field it sits above, weighted like every other step of this role.
   - `--font-field-label-lg-family`
   - `--font-field-label-lg-letter-spacing`
@@ -310,7 +347,9 @@ one value at every width.
 
 ## motion
 
+- `--motion-distance-drift` — How far decoration travels against the scroll while its section passes through the view, one way or the other. Far enough to be seen moving as the reader scrolls past, so it reads as depth.
 - `--motion-duration-dramatic` — Editorial hero entrances for visual impact, e.g. hero headline revealing, landing page title appearing. Not for scroll reveals — use motion.duration.reveal.
+- `--motion-duration-dwell` — How long a rotating message holds before the next one moves in, e.g. a CTA banner's slides. Long enough to read a headline and a line under it; the reference site's 2000 moved before a reader reached the button.
 - `--motion-duration-fast` — Direct user actions that should feel instant, e.g. hover, press, toggle.
 - `--motion-duration-instant` — A change the reader has already moved past — a tooltip leaving once the pointer is elsewhere. Not a short duration but no duration: animating a dismissal keeps a thing on screen after the reason for it has gone.
 - `--motion-duration-media-hover` — How long art takes to settle inside a frame that holds still. Longer than duration.normal, which suits a card that lifts and is over; a picture that zooms is still on screen when it stops and the eye follows it the whole way.
@@ -320,6 +359,7 @@ one value at every width.
 - `--motion-duration-shift` — A surface rearranging itself between two resting states on the reader's scroll — a navigation bar gathering, and ungathering on the way back. Longer than a UI element entering, because nobody asked for it.
 - `--motion-duration-slow` — Large UI transitions, e.g. accordions expanding, page transitions, interactive demos.
 - `--motion-duration-spinner` — One full rotation of a spinner. Fast enough to read as working, slow enough that the stroke does not blur into a solid ring.
+- `--motion-duration-stagger` — The step between one part of a section arriving and the next. A gap rather than a length: five parts at this step trail the first by less than half a second, so a block still arrives as one thing rather than assembling itself while a reader waits.
 - `--motion-easing-enter` — UI elements arriving on screen — decelerates into place, e.g. dropdown opening, tooltip appearing.
 - `--motion-easing-exit` — UI elements leaving the screen — accelerates away, e.g. menu closing, notification dismissing.
 - `--motion-easing-media-hover` — Art moving inside a frame that holds still. Symmetric, unlike easing.standard: a hover runs forward on enter and backward on leave, so a one-way curve that settles hard reads as a snap going one way and a drift the other.
@@ -327,15 +367,19 @@ one value at every width.
 - `--motion-easing-shift` — Symmetric, for a change that runs both ways: a bar gathering on scroll and ungathering on the way back should read the same in each direction, which easing.standard cannot do.
 - `--motion-easing-spinner` — Constant-speed rotation for a spinner. Linear because a loop is the one case with no arrival to ease into — any acceleration lands a seam at the point the animation restarts, and the eye finds it on the second turn.
 - `--motion-easing-standard` — Default easing for anything moving within the viewport. Use this unless the element is specifically entering, exiting, or revealing.
+- `--motion-scale-band-exit` — How far an opening band draws back as it scrolls out. Its own role rather than motion.scale.enter, which is named for something arriving.
 - `--motion-scale-enter` — What a component scales from when something reveals it — a tooltip appearing. Needs a transform origin on the edge nearest its anchor, or it grows out of its own middle. The counterpart to scale.hover, which is a response rather than an entrance.
 - `--motion-scale-hover` — How much a control grows under the cursor on hover. Deliberately small — a control that grows past the pointer fires its own mouse-out.
 - `--motion-scale-media-hover` — How much art grows inside a frame that holds still — an editorial card's picture under the cursor. Twice motion.scale.hover, which stays smaller because a control can outrun its own pointer and a framed picture cannot.
 - `--motion-translate-enter` — Where a surface waits before something reveals it: level on the inline axis, its own full height down the block one. A share of the element rather than of the page, so a sheet travels exactly its own height whatever that turns out to be.
 - `--motion-translate-hover` — How far a pressable surface rises under the cursor. A fixed distance rather than a share of the element, so a tall card and a short one lift by the same amount and a row of them stays level. Small enough that nothing it sits beside looks disturbed.
+- `--motion-translate-reveal` — How far a section waits below where it lands, before the scroll brings it up. A fixed distance rather than a share of the block, so a hero a screen tall and a split half that arrive by the same movement. Pairs with motion.easing.reveal.
 
 ## opacity
 
 - `--opacity-disabled` — How far a control recedes when it is unavailable. Applied to the control as a whole rather than re-colouring its parts, so what is inside keeps its relationships and the whole thing reads as one unavailable object.
+- `--opacity-dot-current` — The position in a row of dots that the reader is on — the ground's own ink at full strength, stretched into a pill so the current one is told apart by shape as well as by weight.
+- `--opacity-dot-rest` — The positions in a row of dots that the reader is not on, e.g. a slider's other slides. Drawn in the ground's own ink at forty-eight, so the row reads on any band without a colour of its own.
 - `--opacity-hidden` — What a component fades from when something reveals it. Not a dimming treatment — something unavailable or quiet says so in its own colour role, where the contrast checker can see it. The first entry in a group this package had left empty.
 - `--opacity-muted` — A mark at rest, before a pointer reaches it. For artwork that carries its own colours and so cannot be quietened by an ink role — a brand logo, a partner mark — where every other quiet thing in this system says so in colour.
 - `--opacity-track` — How far a track recedes behind the thing travelling over it. Both are drawn in one colour, so this alpha is the only thing separating them — which is why it is a ratio and not a colour role.

package/AGENTS.md

@@ -32,9 +32,14 @@ and Red Hat Mono but cannot carry the files. An app that already self-hosts the
 (next/font, Fontsource) skips `fonts.css` and sets `--font-family-sans` /
 `--font-family-mono` instead; the README covers that path.
 
-One theme. The stylesheet has no `[data-theme="dark"]` block, so setting that attribute —
-anywhere, including on `<html>` for the rest of your app — leaves these components light.
-Nothing to configure and nothing to guard against.
+Dark is `data-theme="dark"` on any ancestor, usually `<html>`. Both themes live in that one
+stylesheet — there is no second import and no provider. The two attributes are independent:
+the theme can sit above the scope, on the same element as it, or below it.
+
+```html
+<html data-theme="dark">
+  <body><div data-dds-context="marketing"> <!-- dark, from here down --></div></body>
+```
 
 ## Server Components
 
@@ -48,6 +53,8 @@ a component you give `onChange` or `onClick` to goes in a file of your own that
 
 ## Rules that span components
 
+- **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 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**
@@ -101,6 +108,7 @@ screen is built in is not something to reach for while building a control.
 - **NavbarSwitcherOption** — A NavbarSwitcher needs its choices
 - **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
 - **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
@@ -131,6 +139,23 @@ screen is built in is not something to reach for while building a control.
 - **Scroller** — A set is longer than the space and its order is worth keeping
 - **Stack** — Two or more things are read down the page in order and the space between them is the same the whole way down
 
+### Blocks — the sections a page is built from, and the rhythm between them
+
+- **CtaBanner** — A short, high-contrast promotion with one clear action
+- **CtaBannerSlider** — Rotating between two or three genuinely different promotions without a hero's weight
+- **FaqAccordion** — The questions a reader asks before acting
+- **FeatureBullets** — A page has to list what a product or a plan includes, and the list is the argument
+- **FeatureCards** — Three or four things a product does, each a heading and a sentence, read side by side and compared at a glance
+- **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
+- **LandingHero** — A main landing page needs its opening band
+- **LogoColumns** — Showing the partners, integrations or payment methods behind a claim
+- **LogoRows** — Showing the partners, integrations or payment methods behind a claim under it, where the words lead and the logos follow
+- **PageHeader** — A company, legal or support page needs its opening band
+- **ProductHero** — A product or a market page needs its opening band
+- **TestimonialRow** — Five to ten short, rated reviews collected by a review service, where seeing several at once is the point and the overall score is worth stating
+- **TestimonialSlider** — Two to five real quotes from partners or customers, each a few sentences, read one at a time
+
 ## Components that need mounting
 
 These do not work from the import alone. Each has a Behaviour section in its own document

package/README.md

@@ -6,10 +6,12 @@ pages, pricing, sign-up.
 **Working with an AI agent?** Point it at [`AGENTS.md`](./AGENTS.md) in this package. It is
 the short version of everything below and says which of the `.llm/` documents to open.
 
-> **This package has no components yet.** Its tokens are real and its stylesheet is
-> complete; the component surface is still being authored. Until it lands, installing this
-> gets you the marketing token layer and an empty barrel. Product apps want
-> [`@deriv-com/dds-product`](https://www.npmjs.com/package/@deriv-com/dds-product).
+It has two kinds of component: **core** components — Button, Navbar, Card, Link, the form
+controls and the rest — and **blocks**, the bands a page is built from: `LandingHero`,
+`ProductHero` and `PageHeader` to open a page, and `FeatureSplit`, `FeatureBullets` and
+`FeatureScroll` for the sections under it. `AGENTS.md` lists every one of them with a line
+on when to reach for it. Product apps want
+[`@deriv-com/dds-product`](https://www.npmjs.com/package/@deriv-com/dds-product).
 
 ## Install
 
@@ -26,19 +28,37 @@ npm install react react-dom @deriv-com/quill-icons-web
 
 ## Use
 
-Import the stylesheet once, at the root of your app:
+Import the stylesheet once, at the root of your app. It defines every token this package's
+components bind to — without it they render unstyled.
 
 ```tsx
 import '@deriv-com/dds-marketing/marketing.css'
 ```
 
-That is the whole of the setup, and today it is the whole of the package: the token layer
-is complete and the barrel is empty, so there is nothing yet to import by name. When
-components land, each will bring its own stylesheet with it and nothing else will need
-importing.
+Then put `data-dds-context="marketing"` on whatever wraps the components — the app root, or
+the section, if marketing and product live on one page. Component rules are published only
+inside that scope, because both packages emit classes like `.dds-button` and one would
+otherwise paint the other. Without it the components render unstyled too.
 
-Product apps want [`@deriv-com/dds-product`](https://www.npmjs.com/package/@deriv-com/dds-product),
-which has the components.
+Then import components by name:
+
+```tsx
+import { Button, LandingHero } from '@deriv-com/dds-marketing'
+
+export function Home() {
+  return (
+    <div data-dds-context="marketing">
+      <LandingHero
+        title="Trade smarter with Deriv"
+        description="Access 250+ markets with tight spreads and powerful tools."
+        actions={<Button href="/signup">Get started free</Button>}
+      />
+    </div>
+  )
+}
+```
+
+Each component brings its own stylesheet with it, so nothing else needs importing.
 
 ## Fonts
 
@@ -74,20 +94,20 @@ Every type role reads its family from these two variables, so this redirects the
 system at once. Load weights 400–700 for Inter (a variable font covers this in one file);
 a missing weight does not fall back visibly — the browser synthesises a faux bold instead.
 
-## One theme, and a viewport axis
-
-`marketing.css` ships light only. It contains no `[data-theme="dark"]` block, so setting
-that attribute — anywhere, including on `<html>` for the rest of your app — leaves these
-components light. There is nothing to configure and nothing to guard against.
+## Light and dark, and a viewport axis
 
-A dark palette is authored in the token source and held to the same role names as light,
-so turning it on later is a decision rather than a rewrite. The package states what it
-publishes in its own manifest:
+`marketing.css` defines both themes. Dark is selected by `data-theme="dark"` on any
+ancestor — usually `<html>`:
 
-```json
-"dds": { "modes": ["light"] }
+```html
+<html data-theme="dark">
+  <body>
+    <div data-dds-context="marketing">  <!-- dark, from here down -->
 ```
 
+The theme attribute and the context attribute are independent, and the theme may sit above
+the scope, on the same element, or below it. There is no provider and no second import.
+
 Marketing does carry a mobile viewport axis: seven roles take different values below
 768px, applied automatically and overridable with `data-dds-viewport="mobile"` or
 `"desktop"` when a page renders a device frame inside a wider window.

package/dist/components/banner-data.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The messages a CtaBannerSlider rotates between.
+ *
+ * Exported from the package for the reason `scroll-data.ts` is: a block whose content is a list is
+ * one whose consumer builds a value before passing it, and building it without the type means
+ * writing the shape out twice.
+ *
+ * A record rather than a component per slide, by decision on 2026-10-01. A slide was CtaBannerSlide,
+ * a child that took its actions as elements; it existed only so a slide could carry a Button, and it
+ * was a second component to learn for what is one block. As data, the set can come from a CMS, and
+ * the slider draws the buttons itself — the primary as Button variant="inverse", the second as the
+ * white-tinted secondary, both at tone="brand" — so no slide can put a coral button on the coral
+ * ground. What it costs is the slot: an action is a label and a href, not a Button the page composed.
+ */
+/** A way onward from a slide: the words on the button and where it goes. */
+export interface CtaBannerAction {
+    /** What the button says, as a verb — 'Open account', 'Try TradersView'. */
+    label: string;
+    /** Where it goes. A slide's action is always a link; a banner that runs code on press is not a banner. */
+    href: string;
+}
+/** One message in a CtaBannerSlider: the headline, the line under it, and what it asks for. */
+export interface CtaBannerSlide {
+    /**
+     * The message, in a few words. Short enough to take in as the slide arrives; drawn as a heading
+     * at font.h1, so a reader moving by heading finds the message in view.
+     */
+    title: string;
+    /** A line saying why the action is worth taking. A sentence, not a paragraph. */
+    description?: string;
+    /** The action the message asks for, drawn as Button variant="inverse" tone="brand" — near-black in both themes. */
+    primaryAction?: CtaBannerAction;
+    /**
+     * A second, lesser action, drawn as the white-tinted secondary, Button tone="brand". Drawn only beside a
+     * primary: a slide with one action makes it the primary, the rule Navbar holds its pair to.
+     */
+    secondaryAction?: CtaBannerAction;
+}

package/dist/components/banner-data.js

@@ -0,0 +1,15 @@
+/**
+ * The messages a CtaBannerSlider rotates between.
+ *
+ * Exported from the package for the reason `scroll-data.ts` is: a block whose content is a list is
+ * one whose consumer builds a value before passing it, and building it without the type means
+ * writing the shape out twice.
+ *
+ * A record rather than a component per slide, by decision on 2026-10-01. A slide was CtaBannerSlide,
+ * a child that took its actions as elements; it existed only so a slide could carry a Button, and it
+ * was a second component to learn for what is one block. As data, the set can come from a CMS, and
+ * the slider draws the buttons itself — the primary as Button variant="inverse", the second as the
+ * white-tinted secondary, both at tone="brand" — so no slide can put a coral button on the coral
+ * ground. What it costs is the slot: an action is a label and a href, not a Button the page composed.
+ */
+export {};

package/dist/components/blocks/block-reveal.css

@@ -0,0 +1,90 @@
+/*
+ * The arrival every block shares, defined once.
+ *
+ * A section's parts wait a short way below where they land and come up in reading order as a
+ * reader reaches the block. It is the only motion these blocks have in common, and a copy per
+ * block is how six sections come to disagree about what arriving looks like — one tuned, five not,
+ * and nothing to say which is the house answer. So the movement is stated here and each block's
+ * own stylesheet says which of its parts make it.
+ *
+ * Imported by each block's component, which is what puts it in the bundle once however many
+ * blocks a page uses.
+ *
+ * `data-revealed` goes on the box that is watched — see `use-reveal.ts`, which explains why
+ * neither trigger CSS can offer on its own is enough. `data-reveal-at` marks each part inside it
+ * that arrives, and the same number is set as `--dds-reveal-at` for the arithmetic: an attribute
+ * is what CSS can select on, and a custom property is what it can multiply. Two spellings of one
+ * index, each doing the job the other cannot.
+ *
+ * The waiting state is `[data-revealed="false"]` rather than the absence of a value, so a block
+ * rendered before any script has run — or where none ever will — is visible rather than hidden.
+ * Content behind a script is the one failure this could have that is worse than no motion.
+ *
+ * Every value is a token, and three of them are the set this system already had for the job:
+ * `motion.duration.reveal` is described as "content appearing on scroll, section reveals, feature
+ * items fading in", `motion.easing.reveal` is its curve, and `motion.translate.reveal` is the
+ * distance. `opacity.hidden` is what a part waits at and `motion.duration.stagger` is the step
+ * between one part and the next.
+ *
+ * The duration was `motion.duration.dramatic` for a while, which is the role for an editorial hero
+ * entrance — right while the opening bands were on a timer and wrong once every block arrived on a
+ * reader reaching it. Two roles were named for these two triggers and the work had drifted onto
+ * the wrong one.
+ */
+/*
+ * Waiting is instant; only arriving is animated.
+ *
+ * A transition is decided by the state a thing is moving *to*, so declaring it on both states
+ * animates the way in and the way out alike — and the way out is not a thing anybody should see.
+ * A block is marked as waiting once, in a layout effect, before the browser has painted; if that
+ * ever lands a frame late the block has already been drawn, and an animated hide turns one dropped
+ * frame into three-quarters of a second of the section fading away in front of a reader. That is
+ * exactly what it looked like.
+ *
+ * `transition: none` here rather than nothing, because the arrived rule below is what carries the
+ * timings and a part moving back to waiting must not inherit them.
+ *
+ * Both spellings on every rule: a part is usually inside the box that is watched, and sometimes it
+ * is that box. FeatureScroll's heading is the case — the section watches the heading itself, and
+ * wrapping it in something whose only job was to be a container would put a box in the markup to
+ * satisfy a stylesheet.
+ */
+:where([data-dds-context="marketing"]) [data-revealed='false'] [data-reveal-at],
+:where([data-dds-context="marketing"]) [data-revealed='false'][data-reveal-at] {
+  opacity: var(--opacity-hidden);
+  transition: none;
+  translate: var(--motion-translate-reveal);
+}
+
+/*
+ * Each part a step behind the one before it.
+ *
+ * On the way in only. The delay is declared on the arrived state, which is the state a part is
+ * transitioning *to* — so a block that is somehow put back to waiting drops without a queue.
+ *
+ * A block arrives as one thing that happens to be made of parts, which is what the step size is
+ * for: at a tenth of a second, five parts trail the first by less than half a second, well inside
+ * the movement's own duration. A longer step would be the section assembling itself while a reader
+ * waits for the sentence they came to read.
+ */
+:where([data-dds-context="marketing"]) [data-revealed='true'] [data-reveal-at],
+:where([data-dds-context="marketing"]) [data-revealed='true'][data-reveal-at] {
+  transition-delay: calc(var(--dds-reveal-at, 0) * var(--motion-duration-stagger));
+  transition-duration: var(--motion-duration-reveal);
+  transition-property: opacity, translate;
+  transition-timing-function: var(--motion-easing-reveal);
+}
+
+/*
+ * A reader who asked for less movement gets none of it.
+ *
+ * The hook declines to hide anything under this preference, so the parts are never in the waiting
+ * state to begin with. This is the second half of the same answer: if a part is somehow marked as
+ * waiting, it still arrives without travelling and without queueing behind its neighbours.
+ */
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) [data-revealed] [data-reveal-at],
+  :where([data-dds-context="marketing"]) [data-revealed][data-reveal-at] {
+    transition: none;
+  }
+}