@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/digest/aspectratio.md

@@ -0,0 +1,47 @@
+<!-- GENERATED from aspectratio.contract.json. Do not edit. -->
+
+# AspectRatio
+
+A box that holds one shape whatever is put in it, so a page reserves the room a picture will take before the picture arrives. …
+
+`import { AspectRatio } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- A picture whose proportions have to match the ones beside it — a row of cards, a grid of markets, a set of logos. …
+- Room that must be reserved before the thing filling it arrives — art loaded late, an embed, anything fetched. …
+- An embed that brings its own proportion and no height — a video, a map, a third-party frame. …
+
+## Something else, when
+
+- The picture is the media region of a card → **CardBody**
+- The thing inside has a size of its own and should keep it → **nothing in this system does this**
+- The shape changes with the viewport → **nothing in this system does this**
+
+## Never
+
+- Spacing. It reserves a shape, not room around one: a box used to push things apart is a margin written somewhere nobody will look for it
+- Text. Prose has no proportion of its own — it is as tall as it needs to be at the width it is given, and a box that crops it is a box that hides a sentence
+- Anything that must be read in full. It crops, and crops the same way every time regardless of what matters in the picture: a chart with a legend at its foot loses the legend, and nothing reports it
+- Making an image smaller. The box decides a shape and not a size — how much room it takes is the layout's, and a ratio set to make something fit is a width written in the wrong units
+- A box whose height is set and whose width is not. The ratio turns a width into a height, and this one takes all of the width it is given — so a height set on top of that is a second answer to the same question, and the box is drawn off ratio with nothing reporting it. …
+- A parent that sizes to its contents — an inline-flex row, a fit-content box, a float. The width comes from the container, and a container measuring itself by what is inside it has none to give: the box contributes no intrinsic width, resolves to nothing, and collapses. …
+
+## Props
+
+- **ratio** `enum` · default "widescreen" — The shape the box holds, at every width. It is the component's one decision and the reason it exists, so there is no case for leaving it unstated
+  - `portrait` — Taller than wide, for a picture read on a phone where the width is the constraint — a card whose image carries the card, a person, a product standing up. …
+  - `square` — Equal sides, for a set that repeats — a grid of logos, a row of market tiles, an avatar’s frame. …
+  - `landscape` — Wider than tall and barely so — the shape a photograph or a screenshot arrives in before anything crops it. …
+  - `widescreen` — The default, and the shape most moving media already is: an embedded video, a screen recording, a still from one. …
+  - `ultrawide` — Far wider than it is tall, for a hero or a section break where the picture is scenery rather than subject. …
+  - never: Fitting a particular image. The ratio is a decision about the layout — what shape this slot is — and the picture is what has to answer it. Choosing the value that crops one photograph least is how a row ends up with four slots at four shapes, which is the thing the box was put there to stop
+
+## Inside it
+
+- At least 1, at most 1 — fewer is not this component and more is a different one.
+- 2 components are refused inside it; the list and the reasons are in the long document.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/aspectratio.md`.

package/.llm/digest/badge.md

@@ -0,0 +1,45 @@
+<!-- GENERATED from badge.contract.json. Do not edit. -->
+
+# Badge
+
+A short word marking something as new, chosen or reduced. …
+
+`import { Badge } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- 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
+
+## Something else, when
+
+- What it says is a state the reader's account is in → **nothing in this system does this**
+- The words are the point rather than the mark → **CardBody**
+
+## Never
+
+- A status. There is no success, warning or danger ground here on purpose: those roles report what happened to a reader who did something, and a landing page's reader has not done anything yet
+- Metadata that should be plain text. A date, a category, a count — a pill around each one turns a card into a row of labels and the badge into decoration
+- More than one per thing. Two badges on one card are two claims about which is the important one, and a reader believes neither
+- A control. It does nothing when pressed and takes no focus — something a reader acts on is CardButton, which is a target rather than a mark on one
+
+## Props
+
+- **variant** `enum` · default "accent"
+  - `accent` — The default, and the one a marketing page nearly always wants. …
+  - `neutral` — The badge is naming a kind rather than making a claim — a category on an article, a market type on a card. It marks without asking, which is what lets a page use several without the set becoming loud
+  - never: Ranking two badges against each other. The variants are two different jobs rather than two volumes of one: neutral names a kind and accent makes a claim, so a set mixing them is not a set with a most-important member
+- **label** `string` · required — Always — it is the whole component. One or two words: 'New', 'Most popular', 'Save 20%'. …
+  - never: A sentence. What does not fit on one line is not a badge, and `white-space: nowrap` will let it run out of its own card rather than wrap — which is the component saying so
+- **icon** `node` · optional — A glyph that says what the badge is about faster than its word does — a globe on a badge reading 'For platforms', a spark on one reading 'New'. Pass the glyph; the badge draws it at its own step. Alongside the label and never instead of it. …
+  - never: Carrying the meaning. A badge is one or two words and a mark beside them; a badge that is only a mark says nothing to a screen reader and nothing to a reader who does not already know the shape. A solid or light glyph. …
+
+## Inside it
+
+- 5 components are refused inside it; the list and the reasons are in the long document.
+- Renders 2 parts: root, icon.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/badge.md`.

package/.llm/digest/bottomsheet.md

@@ -0,0 +1,69 @@
+<!-- GENERATED from bottomsheet.contract.json. Do not edit. -->
+
+# BottomSheet
+
+A panel that rises from the bottom edge to hold a single focused task on small screens. …
+
+`import { BottomSheet } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- A task needs the screen's full width and the reader's undivided attention — a set of filters, a confirmation, an option picker
+- The choice is the whole of what the reader is doing, and the page behind it is context rather than something to work in
+
+## Something else, when
+
+- The message is a passing notification the reader does not have to answer → **nothing in this system does this**
+- The viewport is wide enough for a centred modal → **nothing in this system does this**
+- The reader is choosing one answer from a set, inside a form → **nothing in this system does this**
+- A short description of the control the pointer is on → **Tooltip**
+
+## Never
+
+- Desktop viewports. The sheet stops growing at size.sheet.max and centres, which keeps it readable on a tablet — but nothing in this component refuses a wide screen, there being no breakpoint in a contract and no media query in the generated stylesheet. …
+- Anything the reader must be able to see the page behind while doing. The scrim dims the page and swallows every press on it, which is the point: a sheet is a task, not a panel
+- A second sheet on top of the first. Composition forbids the nesting, and the reason is the way out: two scrims stack, the second sheet's Escape shuts only itself, and a reader who has lost track of how deep they are has no way to read it off the screen
+- Content the sheet is expected to hide from a screen reader when shut. The sheet stays mounted so it has something to animate from, and what removes it from the reading order while closed is `visibility: hidden` in the generated stylesheet — which means it is removed by CSS and not by the markup. …
+- Holding the open state itself. `open` is the consumer's, always: the sheet reports that it wants to close through onOpenChange and changes nothing on its own, so a page that never answers that callback has built a sheet with no way out
+- Deciding what the task looks like. The sheet draws a handle, a header and a scrim, and hands the rest over as one slot — there is no footer prop and no description of what belongs at the bottom, because a component that fixed the shape of a confirmation would be wrong for a filter and wrong again for a picker. …
+- Holding a reader in. A press outside the sheet and Escape always close it, and neither flag can turn that off — a surface that answers neither is a trap, and a keyboard reader has no third way. A task that genuinely must be finished asks for that in its content, and takes the answer it is given
+
+## Props
+
+- **open** `boolean` · default false — The sheet is showing. The consumer owns this outright — the sheet never sets it, and asks to be closed through onOpenChange instead. Flipping it is the whole animation. …
+  - never: Keeping a sheet on screen the reader has asked to leave. Refusing to answer onOpenChange does not make the sheet modal, it makes it stuck: Escape, the scrim and the close button all report and none of them acts
+- **height** `enum` · default "hug"
+  - `hug` — The sheet is as tall as what is in it, up to the screen. The default, and right for anything bounded — a handful of choices, a confirmation, a summary. …
+  - `tall` — The sheet takes the screen, less a strip of page at the top. …
+  - `full` — The sheet is the screen: no strip of page and square corners, with the header's row of controls meeting the top of it. …
+  - never: A middle height — half the screen for a list, say. …
+- **title** `string` · required — Always. It is the sheet's accessible name as well as its heading, so a sheet without one is announced as a dialog and nothing else. …
+  - never: A sentence of explanation. That is the description, which sits under this and is announced after it — a title that runs to a sentence is read out in full every time the sheet opens, and is cut with an ellipsis here rather than wrapping. …
+- **showTitle** `boolean` · default true — The default, and almost always right. Turn it off where the content immediately under the header already names the task and a second visible name would say it twice — a picker whose first row is the heading, a sheet that is one photograph. …
+  - never: A sheet whose purpose is merely obvious to whoever built the screen. What is obvious beside the thing it opens from is not obvious to a reader hearing the page one control at a time, and turning this off hides the name from everyone who can see and nobody who cannot. …
+- **description** `string` · optional — The title needs qualifying — what the task applies to, or what it still needs before it can be done. "Date and both airports required", or the account a transfer is coming from. It sits directly under the title and is announced with it
+  - never: A sentence, and anything longer than one. It has the sheet's full width, the controls being above the panel rather than either side of it — but it is cut rather than wrapped, so a sentence does not arrive shorter, it arrives with its end missing. …
+- **showClose** `boolean` · default false — The way out has to be visible — a sheet over a task the reader may not realise they can leave, or one whose content reaches the top of the screen so there is little scrim left to press. …
+  - never: Deciding whether the sheet can be left. It cannot stop that and does not try, which is what the name is for — it used to be `dismissible`, which read as the permission rather than the button: a press outside the sheet and Escape always close it, whatever this says. …
+- **back** `node` · optional — The sheet is a step rather than the whole task — one of a sequence, or a panel reached from another panel — and the reader needs the step before it. One control, icon-only, at the leading edge above the sheet, opposite the way out. …
+  - never: The way out. That is showClose, at the other end, and the two must not be confused by putting a dismiss glyph here — a reader who takes one for the other loses the task. Back undoes a step; close abandons the sheet. …
+- **action** `node` · optional — The screen needs one more control above the sheet — a confirm for a form the sheet is collecting, help for a task that needs explaining. …
+  - never: A size other than md. It no longer takes the title off the centre line — out of the row, nothing it does moves the words below it — but it shares a line with the close button, and a larger control beside a size.control.md one is two controls that were meant to match and do not. …
+- **showHandle** `boolean` · default true — On by default. It draws the handle at the top of the sheet — the bar that says the surface can be moved, which is the cheapest way to say so. It does not decide whether the pull works. …
+  - never: Turning the gesture off. It draws the handle and nothing more — a pull is answered on a sheet with a close button and on one with neither, the same way a press outside it is. The name says that now; it used to be `dragToDismiss`, which claimed a power over the gesture it never had. …
+- **onOpenChange** `callback` · required — Always. The sheet does not close itself, so this is the only way out — write the first argument straight back to `open`. …
+  - never: Doing the task. This fires when the sheet is being left, including when it is being left unanswered — commit from the actions in the footer, where the reader pressed something that says what it does
+
+## The type refuses
+
+- showHandle=true with showClose=true — A sheet says how to leave it once. …
+- height="full" with showClose=false — A full sheet has taken away every other visible way out: the scrim is entirely covered, and there is no strip of page above the surface to say a page is still there. …
+
+## Inside it
+
+- 1 component is refused inside it; the list and the reasons are in the long document.
+- Renders 12 parts: root, scrim, frame, surface, handle, header, leading, heading, title, trailing, description, body.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/bottomsheet.md`.

package/.llm/digest/breadcrumb.md

@@ -0,0 +1,38 @@
+<!-- GENERATED from breadcrumb.contract.json. Do not edit. -->
+
+# Breadcrumb
+
+The trail of ancestors above the current page on a marketing site, showing the visitor where they are in the site hierarchy. …
+
+`import { Breadcrumb } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- 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
+
+## Something else, when
+
+- The visitor is moving through the stages of a sign-up or onboarding flow rather than standing in a hierarchy → **nothing in this system does this**
+- There is exactly one place to go back to, and it is the previous page rather than a parent section → **nothing in this system does this**
+
+## Never
+
+- The only route to a destination. A trail is a secondary affordance — it may be below the fold, it is the first thing a narrow viewport wraps, and a visitor who arrived by deep link may never read it. Anything reachable only from here is unreachable
+- Levels the hierarchy does not have. Padding a trail to look substantial describes a structure the visitor will not find when they climb it
+- Progress through a sign-up, checkout or onboarding flow, which is a task and not a place
+- Holding anything but its own items. The trail is a list of levels; a control sitting inside it is a control the visitor must tab through to reach the page
+
+## Props
+
+- **label** `string` · default "Breadcrumb" — Always, and the default is almost always right. It names the landmark rather than the page — a screen reader user listing the landmarks on a page hears this, and "Breadcrumb" is the word they are listening for
+  - never: The current page's own name, which the last item already carries. A landmark named after the page it sits on is announced twice and identifies nothing
+
+## Inside it
+
+- Takes only BreadcrumbItem.
+- Renders 3 parts: root, list, separator.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/breadcrumb.md`.

package/.llm/digest/breadcrumbitem.md

@@ -0,0 +1,43 @@
+<!-- GENERATED from breadcrumbitem.contract.json. Do not edit. -->
+
+# BreadcrumbItem
+
+One level in a Breadcrumb on a marketing site. It renders either a link back to that level or, for the level the visitor is already on, plain text marked as the current page. …
+
+`import { BreadcrumbItem } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- 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
+
+## Something else, when
+
+- The destination is somewhere the visitor goes to act rather than a level they climb back to → **nothing in this system does this**
+
+## Never
+
+- A level on its own, outside a Breadcrumb. The separators, the ordering and the landmark all belong to the trail, so a lone item is a link with none of the meaning that made it a level
+- The page title. The current item names the page in the trail, in the words the parent level would use for it — a heading is free to be longer, and copying one into the trail makes the row wrap for nothing
+- A level the visitor cannot actually reach. An item with no href is text, and text the visitor tries to click is a promise the trail did not keep
+
+## Props
+
+- **label** `string` · required — Always — it is the level's name, and the item renders nothing without it. The word the parent level would use for this place: "Forex", not "Forex markets and instruments"
+  - never: A description of the level, or the page's full title. The trail is a row of names, and a name that explains itself is the thing that makes it wrap
+- **href** `string` · optional — The level is one the visitor can return to — which is every level above the current page
+  - never: The current page. Linking the page to itself gives the visitor a link that does nothing and adds a tab stop that leads nowhere
+- **current** `boolean` · default false — This is the level the visitor is on, which is the last item in the trail. It renders as text rather than a link and is announced as the current page
+  - never: Emphasis on a level that is not the current page. It is a statement about where the visitor is, not a way to make one level louder — and setting it alongside href asks for a link the item will not render
+
+## The type refuses
+
+- current=true with href="*" — The two together ask for a link from the page to itself — a tab stop that goes nowhere. …
+
+## Inside it
+
+- Renders 3 parts: root, link, current.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/breadcrumbitem.md`.

package/.llm/digest/button.md

@@ -0,0 +1,48 @@
+<!-- GENERATED from button.contract.json. Do not edit. -->
+
+# Button
+
+Drives a visitor toward a conversion goal by navigating them to the next step in a funnel — a signup page, a pricing page, a demo booking. …
+
+`import { Button } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- The call to action on a marketing page — the one step you want a visitor to take next
+- Moving a visitor along a funnel: hero to signup, pricing to checkout, feature page to demo booking
+- A destination prominent enough that it has to read as a control rather than as words in a sentence
+
+## Something else, when
+
+- The action happens on the current page — submitting a form, toggling a setting, opening a dialog, removing something → **nothing in this system does this**
+- The words belong inside a sentence or a paragraph of body copy → **nothing in this system does this**
+- The control is a glyph alone, with no words → **ButtonIcon**
+
+## Props
+
+- **variant** `enum` · default "primary" — Deciding how much of the section a destination claims. Primary is the default and the one to spend deliberately
+  - `primary` — The step the page was built to produce. …
+  - `secondary` — A real destination that is not the one being pushed — compare plans, read the docs, talk to sales. …
+  - `inverse` — A section that paints its own ground — a brand-coloured hero, a photo band, a dark takeover. …
+  - never: Ranking every link on a page against every other. Three tiers is the whole vocabulary here on purpose — a set of unjustified tiers is what the previous Button was deleted for. …
+- **size** `enum` · default "lg" — Matching the control to the density of the band it sits in, which on a marketing page is set by the section rather than by the button
+  - `sm` — A dense band where the button is one control among several — a filter row, a utility bar, an action beside body copy. …
+  - `md` — The default, and everything that is not a hero — navigation bars, pricing rows, feature sections, footer bands. …
+  - `lg` — A hero, or a full-width conversion band that is the only control in view. …
+- **tone** `enum` · default "default"
+  - `default` — The page's own ground, which sets the ink this component was drawn against — every button on a white page
+  - `inherit` — A section that painted its own ground and set its own ink: a dark hero, a brand band, a photo. …
+- **href** `string` · required — Always. The destination is the component — an anchor without an href is not a link, is not reachable by keyboard, and is announced as plain text, so there is no default that could stand in for one. …
+  - never: A placeholder while the destination is undecided — a # or an empty string is a control that looks live, takes focus and goes nowhere. Nor javascript: or a handler dressed as a URL: an action that runs in place is product's Button, and this component's own guidance says so
+- **showIcon** `boolean` · default false — Where the destination continues a sequence rather than being simply somewhere else to go — the hero CTA that starts a signup, the button at the foot of a step. …
+  - never: Every button in a section. The mark says "this continues" and is worth something only while it points at the one control that does; on four at once it is decoration and the reader stops reading it
+
+## Inside it
+
+- Takes only text.
+- 1 component is refused inside it; the list and the reasons are in the long document.
+- Renders 3 parts: root, label, icon.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/button.md`.

package/.llm/digest/buttonicon.md

@@ -0,0 +1,61 @@
+<!-- GENERATED from buttonicon.contract.json. Do not edit. -->
+
+# ButtonIcon
+
+One press carried by a glyph alone, in the space a label would need. …
+
+`import { ButtonIcon } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- One press with no room for words — a promotional bar's dismiss, a hero's play control, a carousel step, a footer's social links. …
+- A row of glyph-alone destinations where words would only repeat — social accounts in a footer, app stores in a download band, a region switch in a header
+- A control the page owns rather than a destination — dismissing a promotional bar, playing a hero video, advancing a carousel, opening a mobile nav. …
+- The glyph is one a visitor reads without being taught — a play triangle, a dismiss cross, a chevron, a social mark in its monochrome cut. …
+- Room is genuinely short and the words would be the same words several times over. One of these on its own beside prose is usually a Button that lost its label
+
+## Something else, when
+
+- The control has words, or needs them to be understood → **Button**
+- The whole surface is the target — a card standing for a feature, a market or a plan → **CardButton**
+- The mark is an ornament rather than a control → **Icon**
+- The mark reports a state the visitor sets and reads back — sound on or off, a light and dark switch → **nothing in this system does this**
+
+## Never
+
+- A glyph whose meaning arrives only from a tooltip. Hover does not exist on a touch screen and a marketing page is read on a phone as often as not, so that explanation reaches only some of the people who need it
+- The call to action the page exists to produce. That step is named rather than drawn, which is Button — a visitor deciding whether to convert should not have to decode a shape first
+- A placeholder href while the destination is undecided. Given one this becomes a real anchor, so a # or an empty string is a control that looks live, offers to open in a new tab and goes nowhere
+- Several glyphs in one control, or a glyph beside a count. One control, one action, one shape; anything else is a Button whose label happens to be short
+
+## Props
+
+- **variant** `enum` · default "primary" — Deciding how much of the section one press claims. The three tiers are Button's three, deliberately — a glyph-alone control and a labelled CTA in the same band have to rank against each other, and they cannot do that in two vocabularies
+  - `primary` — The one glyph-alone press a section is built around — a play control over a hero, the single action a band exists for. …
+  - `secondary` — The ordinary case for these, because they usually arrive several at a time — a footer's social row, a carousel's two directions, a bar's dismiss. …
+  - `inverse` — A section that paints its own ground — a brand-coloured band, a photo, a dark takeover. …
+  - `plain` — The control sits on a surface that has already said what it is — the exit on a sheet, a step in a set of marks — and a ring around it would be the loudest thing there. …
+  - never: Ranking a row of these against each other. A footer's five social links are peers; one of them drawn heavier says the other four are lesser, which is not a thing anybody meant to say. …
+- **size** `enum` · default "md" — Matching the control to the density of the band it sits in, which on a marketing page is set by the section rather than by the control
+  - `sm` — A dense row of controls — a filter bar, a utility strip, a compact carousel. A square of size.control.sm holding a mark at icon.control.sm. …
+  - `md` — The default, and nearly everywhere — footers, navigation bars, promotional bars, carousels. …
+  - `lg` — One prominent press, usually the only control in view — a play control over a hero, a single action in a conversion band. A square of size.control.lg holding a mark at icon.control.lg. …
+  - never: Making one of a set stand out. Two of these side by side at different steps read as a control and its afterthought, and a carousel whose next is larger than its previous has said the path runs one way
+- **tone** `enum` · default "default"
+  - `default` — The control is on a light ground, which is every surface this package paints by default
+  - `inverse` — The control is on a ground that runs against the mode — a mark in a navigation bar standing on a dark hero. The ink and the tints move together; nothing else does
+- **icon** `node` · required — Always — the glyph is the whole control, so it is required rather than a slot that may be empty. …
+  - never: A glyph whose meaning the visitor has to be taught, and never a second glyph — one control, one action, one shape. …
+- **label** `string` · required — Always. It is the entire accessible name, because nothing on screen carries one — the words that would have been the label if there had been room for one. …
+  - never: Describing the picture rather than what the press does — "cross" instead of "Close", "triangle" instead of "Play the tour". And not the gesture either: a footer of links announced as "click here" names nothing, which is the requirement Button's own guidance already sets for its words
+- **href** `string` · optional — The press goes somewhere with a URL of its own — a social account, an app store, another page. …
+  - never: A press the page handles itself — a dismiss, a carousel step, opening a video in place. An anchor with an href nothing can navigate to is a promise the browser will try to keep
+
+## Inside it
+
+- 7 components are refused inside it; the list and the reasons are in the long document.
+- Renders 2 parts: root, icon.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/buttonicon.md`.

package/.llm/digest/card.md

@@ -0,0 +1,50 @@
+<!-- GENERATED from card.contract.json. Do not edit. -->
+
+# Card
+
+A surface that holds content belonging together. …
+
+`import { Card } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- Content that is read as one thing — a feature and the sentence explaining it, a plan and what it costs, a step and what it asks for
+- A picture that reaches the card's edges, with or without copy inset beneath it — a screenshot, a photograph, a band of art. …
+- A row or a column of such groups, where the fill is what separates one from the next
+- A measure a landing page should not be choosing for itself: the corner a card takes and the ground it sits on
+- An editorial card — an article, a post, a story — where the picture and the headline do the separating and a fill would be a second, weaker edge. …
+
+## Something else, when
+
+- The whole surface is the thing the reader presses → **CardButton**
+
+## Never
+
+- A promotional tile as a component of its own. A tile is this surface holding a heading, some words, a mark and a Button — each of which already exists and already knows what it looks like. There is nothing left for a second component to decide
+- A band running the width of the page. That is the page changing ground under a whole section, which is a section's own fill — color.bg.subtle or color.bg.brand-strong — rather than a container sitting on it. A card that stretched edge to edge would be a page with rounded corners
+- Padding. A card that padded its own contents could not hold a picture reaching its edges, which is the shape a marketing card most often takes. …
+- Nesting inside a control or a mark. A card is a thing you put components into, never one you put inside something
+
+## Props
+
+- **variant** `enum` · default "surface"
+  - `surface` — The default, and right for a card on the page. …
+  - `surface-raised` — The card sits on a color.bg.subtle band rather than on the page. …
+  - `plain` — An editorial card — an article, a post, a story — where the picture and the headline are what separate one card from the next. …
+  - `accent` — One card in a set is the promotional one and the page has already earned the colour. The coral is the loudest ground here, so a row of them is a row of nothing louder than the rest
+  - `accent-strong` — A card carrying more weight than its neighbours, where the coral would be too loud and the page ground too quiet. …
+- **tone** `enum` · default "default" — Which way round the ground is. A card sits on the page by default; `inverse` is for one sitting on a band that paints its own dark ground — a footer, a dark hero, a brand takeover. …
+  - `default` — The page is light, which is nearly every page. The fills are opaque and the ink is dark
+  - `inverse` — The card sits on a band that paints its own dark ground. …
+  - never: Making a card darker on a light page. This does not mean "dark" — it means "the thing behind me is dark". On a white page an inverse card is a barely-there wash nobody can see the edge of
+- **compact** `boolean` · default false — The card is small enough that a generous corner is a fifth of its width. `radius.surface` is twenty-four, which is the corner of a feature card in a grid; on a rail beside a footer's columns it reads as bulbous. …
+  - never: A card that is merely less important. The corner follows the card's size, not its rank — a full-width card with a tight corner reads as a panel that has lost its edges rather than as a quiet one
+
+## Inside it
+
+- At least 1, at most 1 — fewer is not this component and more is a different one.
+- 1 component is refused inside it; the list and the reasons are in the long document.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/card.md`.

package/.llm/digest/cardbody.md

@@ -0,0 +1,68 @@
+<!-- GENERATED from cardbody.contract.json. Do not edit. -->
+
+# CardBody
+
+Everything a card holds: the words inset from its edges and the picture that reaches them, in one region. The surface around it keeps a fill and a corner and nothing else. …
+
+`import { CardBody } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- Words, a picture, or both inside a Card — a feature and the sentence explaining it, a screenshot under the copy that describes it
+- A photograph, render or screenshot that should reach the card's edges while the copy above it stays inset
+- A picture that should absorb whatever height the copy leaves, so a row of cards ends flush no matter how much each one says
+- A mark above the words — the glyph a feature card leads with, sized and inset with the copy rather than reaching the card's edges
+- Copy that sits over the picture rather than beside it — a photograph as the card's ground, with a title and a sentence washed over it
+- A line above the title filing the card under something — the date an article ran, how long it takes to read, the category it belongs to. …
+
+## Something else, when
+
+- The whole card is one picture, with no words at all → **Card**
+
+## Never
+
+- A surface of its own. It has no fill and no corner: outside a Card it is a stack with padding on part of it, which is a layout rather than a component
+- Copy over a picture with nothing to darken it. `overMedia` paints a ground and a wash under the words and is the only supported way to lay them over art — setting `src` alone puts the picture in the column, under the copy rather than behind it, which is a different card
+- Text baked into the picture. It cannot be selected, translated, or reflowed at the width a phone gives the card — words go in title and description, which are text at a size the type ramp chose
+- Controlling the gap between unrelated blocks. It stacks its copy at one measure, and a page needing two different gaps is composing the stack itself
+
+## Props
+
+- **overMedia** `boolean` · default false — The picture is the card's ground and the copy is read on top of it. …
+  - never: Making a card look richer. It forces the dark ground and the light ink on every word in the body, so a title that was near-black on the page turns white — and over a pale photograph with no wash strong enough to hold it, that is the least legible card on the page rather than the most striking
+- **flush** `boolean` · default false — The card has no fill for the copy to be held off — Card's `plain` variant, where the picture is the card's edge rather than the ground being it. …
+  - never: A filled card. The inset is what keeps the words off the ground's edge, and on surface, accent or accent-strong removing it puts a headline hard against the colour — which is the one way a card looks broken rather than merely tight. …
+- **zoomOnHover** `boolean` · default false — The card is pressable and its picture is what answers the pointer — an editorial card inside a CardButton, on any ground. …
+  - never: A card that is not pressable. Motion under the cursor is how a surface says it responds to a press, and on a plain Card — a div with no role — it says that to a mouse user about something that does nothing, while telling a keyboard user nothing at all, since there is no hover without a pointer and no focus without a control. …
+- **compact** `boolean` · default false — The card is small enough that the standard inset and the standard type are most of it. …
+  - never: Fitting more words into a card that is too small for them. The inset is not what is wrong with a card whose copy will not fit — taking sixteen pixels off each side buys one word a line and leaves the same card overfull It does not undo `flush`. …
+- **tone** `enum` · default "default" — Which way round the ground under it is, and it pairs with Card's prop of the same name for the reason `compact` does: the box and its contents are separate components, and only the page knows it has put one inside the other. …
+  - `default` — The card is on the page, which is nearly every card
+  - `inverse` — The card sits on a band that paints its own dark ground, and carries `tone="inverse"` itself. …
+  - never: Setting it on one of the pair and not the other. A card whose ground is inverse and whose body is not has one line in an ink chosen for a page it is not on
+- **eyebrow** `string` · optional — The card is filed under something a reader scans before the headline — the date an article ran, how long it takes to read, the category it sits in. …
+  - never: A sentence, or a second headline. It is set at twelve pixels with wide tracking, a measure chosen for three or four words and a wall at the length of a clause — what the card is about is the title's job. Nor a status or a count. …
+- **title** `string` · optional — The card names what it is about. A noun phrase rather than a sentence — 'Balance protection', not 'We protect your balance' — because it is read as a label on the block beneath it. …
+  - never: The sentence explaining the card. That is description, which sits under this at a gap close enough that the two read as one block. A title that runs to a sentence leaves the copy with nothing to add
+- **description** `string` · optional — What the title means, usually a sentence or two. It takes the default body step, because a card's copy is copy rather than a caption. …
+  - never: A control. This body holds two regions and neither is a place to act from — a card with a call to action puts it in the Card beneath this, where it is not wearing the body's copy styling
+- **mark** `node` · optional — The card leads with a glyph — a badge, a shield, a small piece of art that makes the feature recognisable before the title is read. …
+  - never: A picture that should reach the card's edges. This is inset with the copy and sized to sit above a heading; a photograph put through it is a stamp in the corner of a wide margin. That is src, which renders the media region below or above this whole block rather than inside it
+- **src** `string` · optional — The card shows a picture — a photograph, a product render, a screenshot of the thing being described. Absent is the ordinary case: most cards are words
+  - never: A data URI holding a photograph. A card's picture is the heaviest thing on a marketing page and inlining it costs the page its cache; a path belongs here, and the formats and sizes behind it are the page's build to decide
+- **alt** `string` · optional — Whenever src is, and empty when the picture says nothing the copy has not already said. …
+  - never: Repeating the card's title. The reader heard it from the heading a moment earlier, and hearing it twice is how a decorative image makes a card worse than one with no image at all. If the sentence you would write is the title, the right value is the empty string. …
+- **aspect** `number` · optional — The picture must hold a known shape rather than absorb the card's spare height — a logo that distorts the moment it is cropped, or a chart whose proportions are the point. …
+  - never: A row of cards that should end flush. Setting this stops the picture absorbing the height the copy leaves, so a card whose title runs to two lines grows taller than its neighbours and the row goes ragged. Absent is right for almost every card in a set
+- **mediaPosition** `enum` · default "below"
+  - `below` — The copy introduces the picture — a feature named and explained, then shown. The ordinary case, and what a reader scanning a column of cards is reading for
+  - `above` — The picture is what the reader recognises the card by and the words caption it — a photograph leading an article, a screenshot the copy then describes. …
+
+## Inside it
+
+- 2 components are refused inside it; the list and the reasons are in the long document.
+- Renders 9 parts: root, scrim, content, mark, eyebrow, title, description, media-frame, media.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/cardbody.md`.

package/.llm/digest/cardbutton.md

@@ -0,0 +1,49 @@
+<!-- GENERATED from cardbutton.contract.json. Do not edit. -->
+
+# CardButton
+
+A card that responds to a press. …
+
+`import { CardButton } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- 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. …
+- Pressing it opens something the page owns rather than leaving the page — a dialog, a video, a step in a sign-up
+
+## Something else, when
+
+- The card holds a control of its own as well → **Card**
+- Nothing happens when it is pressed → **Card**
+
+## Never
+
+- A card containing a button, a link or a field. Every one of them is unreachable inside a button or an anchor, and the rule about it is the one rule in this system that cannot live on any single component
+- An href to somewhere that does not exist. Given one this becomes a real anchor, so the destination has to be a place a reader could bookmark — an action dressed as a destination sends them nowhere and offers to open it in a tab
+- A whole section of the page. A card stands for something else and points at it; a surface wrapping an entire band with an href on it is a page linking to itself
+- Making a card feel lively. The lift under the pointer is what a control looks like, and putting it on something that does nothing teaches a reader that movement means nothing
+
+## Props
+
+- **variant** `enum` · default "surface"
+  - `surface` — The default, and right for a pressable card on the page. The same recessed step off the white page that Card takes, so a row mixing pressable and plain cards reads as one row
+  - `surface-raised` — The card sits on a color.bg.subtle band rather than on the page, where the recessed fill all but disappears and this one lifts off the band instead
+  - `accent` — One card in a set is the promotional one and the page has already earned the colour
+  - `accent-strong` — A card carrying more weight than its neighbours. The darkest of the four, and the one that takes white at 20.55:1 — the most legible ground a marketing card has
+  - `plain` — An editorial card that goes somewhere — an article, a post, a release note. …
+- **href** `string` · optional — The press goes somewhere with a URL of its own. It makes this an anchor rather than a button, which is what gives a reader cmd-click, a visible destination and a copyable link — none of which mean anything for a press that opens a dialog. …
+  - never: A press the page handles itself. An anchor with an href nothing can navigate to is a promise the browser will try to keep
+
+## The type refuses
+
+- variant="plain" with state="hover" — The editorial card does not move under the cursor, and this is the declaration of that rather than an omission. …
+
+## Inside it
+
+- At least 1, at most 1 — fewer is not this component and more is a different one.
+- 4 components are refused inside it; the list and the reasons are in the long document.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/cardbutton.md`.

package/.llm/digest/checkbox.md

@@ -0,0 +1,63 @@
+<!-- GENERATED from checkbox.contract.json. Do not edit. -->
+
+# Checkbox
+
+Records a single on-or-off choice that is submitted with the form around it rather than applied the moment it is ticked
+
+`import { Checkbox } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- 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
+
+## Something else, when
+
+- Choosing exactly one option from a short set, where picking one unpicks the others → **SegmentedControl**
+- Performing an action rather than recording a choice → **Button**
+
+## Never
+
+- A setting that takes effect the moment it is ticked. A checkbox is a value the form around it submits, and one that applied immediately would misreport itself — the reader looks for Save, finds nothing waiting, and cannot tell whether the change took. Marketing has no immediate-apply toggle to send them to
+- Destructive or irreversible changes — a checkbox is a value in a form, and a tick is not a confirmation step
+- A choice the user cannot see the label of. The label is required and always rendered: a bare box states nothing about what ticking it agrees to
+
+## Props
+
+- **tone** `enum` · default "standard"
+  - `standard` — The default, and almost always right — the ticked box fills with the neutral that outranks everything around it, so the choice is legible before any colour is read and it is the fill every other chosen control in this package takes, which is what lets a form of them read as one set of answers …
+  - `accent` — The checkbox is the brand moment of the view — a single consent the design is deliberately drawing the eye to — and the surrounding design already carries brand red
+- **checked** `enum` · default "unchecked"
+  - `unchecked` — The default — the choice has not been made, or has been made against
+  - `checked` — The user has made this choice, or it arrives pre-made and they may change it
+  - `indeterminate` — A box that summarises others, where some but not all of them are ticked — a Select all above a partly selected list
+  - never: A pending or loading state. Indeterminate means partly chosen, not not-yet-known, and a user who ticks it expects the group to follow
+- **status** `enum` · default "none"
+  - `none` — The default — the choice has not been judged, or it passed and there is nothing to say
+  - `error` — The box had to be ticked and was not, or what ticking it asks for is not accepted
+  - `warning` — The choice is accepted but has a consequence the user should see before submitting
+  - `success` — The choice was checked against something and passed, and confirming that is worth the room
+  - never: A box in a set where something above it already asks the question and reports the error. The message answers for the whole set, and a box repeating it states the same failure twice. This prop is for the box that stands alone, which is the case a group cannot cover: a single consent has nothing above it to carry the error. …
+- **label** `string` · required — Always — it states what ticking the box agrees to, and the box shows nothing on its own. A phrase the user can read as a claim they are agreeing with: "Send me trade confirmations", not "Confirmations". …
+  - never: The consequence or the rule, which belongs beside the form rather than inside the choice — a label that explains has stopped naming the thing being agreed to, and there is a description for what it was trying to say. …
+- **showLabel** `boolean` · default true — Drawing the words, which is nearly always. A checkbox on its own is a question, and a question with no words is not one
+  - never: Deciding whether the box has a label. It always has one and it is always announced — this only says whether the label is drawn. Off is clipped, not removed, so a screen reader still reads it
+- **description** `string` · optional — Ticking the box commits the user to something the label cannot carry without becoming a sentence — what it costs, how often it happens, what it applies to. …
+  - never: Guidance about the form as a whole, or the rule behind the choice, which belongs beside the form rather than under one of its controls. A note repeated under every box is describing the set, and putting it on one of them says it is true of that one only
+- **statusMessage** `string` · optional — Whenever the status is an error or a warning — the words are what the user acts on, and the colour alone is not available to everyone
+  - never: Restating the label. The message says what happened and what to do, not what the choice was
+
+## The type refuses
+
+- status="error" with statusMessage=null — An error with no explanation leaves the user stuck
+- status="warning" with statusMessage=null — A warning with no explanation is a choice the user cannot act on
+
+## Inside it
+
+- 2 components are refused inside it; the list and the reasons are in the long document.
+- Renders 9 parts: root, control, box, field, indicator, text, label, description-text, message.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/checkbox.md`.