@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/digest/searchinput.md

@@ -0,0 +1,56 @@
+<!-- GENERATED from searchinput.contract.json. Do not edit. -->
+
+# SearchInput
+
+A query a visitor types to find something the page did not put in front of them — a help centre, a blog or docs index, a directory of markets. …
+
+`import { SearchInput } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- A help centre, a knowledge base, or documentation — more pages than a menu can carry
+- A blog or resource index a reader arrives at knowing roughly what they want
+- A directory the page already holds and can filter as the reader types — markets, offices, partners
+
+## Something else, when
+
+- The field is part of a form the reader will submit → **nothing in this system does this**
+- The set is small enough to show at once → **nothing in this system does this**
+- The reader is choosing from known options rather than describing what they want → **nothing in this system does this**
+
+## Never
+
+- Navigation a menu should carry. A search is where a reader goes when the menu failed them, not a substitute for writing one
+- A page with nothing to search. An empty index behind a search box is a dead end the reader reached by doing what the page asked
+
+## Props
+
+- **size** `enum` · default "md"
+  - `sm` — A search that is one control among several — a filter bar above a list, or a navigation row. Desktop layouts only: at thirty-two it is below what a finger reliably hits
+  - `md` — The default — a search in a help centre's header, or above an index the page already holds
+  - `lg` — A search that is the reason the section exists: a knowledge base landing page whose one job is to take a query
+- **label** `string` · required — Always — a field announced as a searchbox still needs a name, and "Search" alone does not say what is being searched. "Search transactions", not "Search". …
+  - never: The placeholder’s job. A placeholder may show an example of a query; the label says what the field searches, and it is the only one of the two a screen reader is given
+- **showLabel** `boolean` · default false — Drawing the label, for a page-level search with a line to spend on it — a help centre, a directory. The exception rather than the rule: a toolbar and a table header show a magnifier and a placeholder. …
+  - never: Deciding whether the field 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
+- **placeholder** `string` · optional — Making the field’s purpose legible while the label is clipped, which is the default and so the usual case: "Card, bank or wallet" on a payment method search. …
+  - never: The label, which it is not: it disappears as the user types and is never an accessible name. Nor repeating a drawn label, which is the same sentence twice
+- **helperText** `string` · optional — Saying what the query matches when it is not obvious — "Searches names and symbols" on a field that looks like it searches only names. Stays on screen, unlike the placeholder
+  - never: How many results there are, or that there are none. That belongs to the list this field filters, which is the only thing that knows
+- **value** `string` · optional — The page owns the query and passes it in — the controlled form, and the usual one here, because a query is normally held wherever the filtering happens
+- **defaultValue** `string` · optional — A query the field starts on — a filter restored from a URL or a saved view. Absent means an empty field
+- **onChange** `callback` · optional — Filtering as the user types. …
+  - never: Work that should wait for a pause. This fires on every keystroke; debouncing is the page's, because how long to wait depends on what the query costs. …
+- **onSearch** `callback` · optional — Committing the query — Enter, and a query worth a round trip. A search that costs a request wants asking for, where one that filters a list already on screen can follow every keystroke through onChange
+  - never: Both jobs at once. A field wired to onSearch alone does nothing until Enter, which is right for a request and wrong for a filter — and one wired to both is asking the page to decide twice. Wiring neither is the other way to get it wrong: nothing is reported at all, and the field looks broken rather than quiet
+- **clearLabel** `string` · required — Naming the clear button, which is always offered here rather than asked for. The glyph is a cross and says nothing on its own, so this is the button’s only name — "Clear search", in the consumer’s own words
+  - never: The label of the field. That names what is being searched; this names what pressing the button does to the query
+
+## Inside it
+
+- 2 components are refused inside it; the list and the reasons are in the long document.
+- Renders 7 parts: root, label, control, search-icon, field, clear, helper.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/searchinput.md`.

package/.llm/digest/segmentedcontrol.md

@@ -0,0 +1,59 @@
+<!-- GENERATED from segmentedcontrol.contract.json. Do not edit. -->
+
+# SegmentedControl
+
+A row of joined segments from which exactly one is chosen, drawn from a short set of alternatives that exclude each other. …
+
+`import { SegmentedControl } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- 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 …
+- What the reader picks becomes a value something next to it consumes — a period against which prices are quoted, a unit, a plan — which puts the control beside whatever it alters rather than at the head of the page …
+- The alternatives are short enough to read across in a glance. A row is scanned, not worked through
+
+## Something else, when
+
+- The choice swaps a whole slice of the page rather than setting a value → **TabList**
+- The alternatives are separate topics rather than values of one question → **Accordion**
+- There are more than about four, or the labels need more than a word or two → **SelectChip**
+- The choice is on or off → **Button**
+- The reader may pick several of the options at once, or none → **FilterChip**
+
+## Never
+
+- Navigation. Nothing here carries an href and nothing here goes anywhere — a row whose segments led away would be a menu drawn as a comparison, and announced to a screen reader as a set of radio buttons
+- A sequence. Segments are alternatives and are pressed in any order; steps happen in one, and a row says otherwise to everyone who reads it
+- One segment. A set of one is a label wearing a pill, and 'chosen' marks it against nothing
+- A filter that can take several answers at once. Exactly one segment is current here, and the role says so — a set the reader can multi-select is a row of FilterChips
+
+## Props
+
+- **layout** `enum` · default "hug" — Decide it from what the row sits in rather than from how it looks on its own: a control that shares a line hugs, and one that heads a block fills
+  - `hug` — Every segment takes the width of its own words and the row takes the total. …
+  - `fill` — The segments split the container into equal shares and the row stretches across it. …
+  - never: Making a row wider to fill a gap in a layout. fill divides whatever it is given, so a row in a container far wider than its words draws segments with an acre of ground in each
+- **size** `enum` · default "md" — Match it to the controls the row sits beside — the height is bound to the same ramp a Button of that name takes, so the two line up
+  - `sm` — A control seated in something already dense — a filter row, a picker in a navigation bar. Desktop only: below what a finger reliably hits
+  - `md` — The default. Sized to a medium control, so the row lines up with the fields and buttons next to it
+  - `lg` — A choice in a hero or a conversion band, where the control is the point of the section rather than an adjustment within it
+  - never: Emphasis. A larger row is a bigger target, not a louder one; a choice that needs weight gets it from the copy around it
+- **disabled** `boolean` · default false — The question cannot be answered yet — a period switch above prices that have not loaded, a plan picker before an account is chosen. The whole groove dims as one object and the row stops answering the pointer and the arrow keys
+  - never: Barring one option. That is the segment's own disabled, which leaves the rest answering — a row closed to say one word is unavailable dims the answer the reader already has
+- **label** `string` · required — Always — a radiogroup with no name is announced as a set of choices with nothing said about what they are choices of. Name the question rather than the act: 'Billing period', not 'Choose a billing period'
+  - never: A heading. This is the group's accessible name and it is not drawn — a control that needs a visible heading gets one on the page above it, where a sighted reader can see it too
+- **value** `string` · optional — The page is holding which segment is in force, which is the ordinary case here — the choice drives a price, a figure or a card rendered beside the control, so the page already has the answer. …
+  - never: Half of a controlled row. A value passed with no onChange to move it is a control that cannot respond to being pressed, which reads as broken rather than as fixed — and it is the shape a page falls into by adding the value first
+- **onChange** `callback` · optional — Whenever value is — together they are how a page holds the choice. It is called with the chosen segment's value after that segment's own onSelect, so a segment that reports its own presses keeps doing so inside a row
+  - never: Side effects a choice should not have. This says which value is in force; a row that also navigated, submitted or fetched on it would be doing the thing its intent says it does not
+
+## Inside it
+
+- Takes only SegmentedControlItem.
+- At least 2, no ceiling — fewer is not this component and more is a different one.
+- 16 components are refused inside it; the list and the reasons are in the long document.
+- Renders 2 parts: root, indicator.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/segmentedcontrol.md`.

package/.llm/digest/segmentedcontrolitem.md

@@ -0,0 +1,59 @@
+<!-- GENERATED from segmentedcontrolitem.contract.json. Do not edit. -->
+
+# SegmentedControlItem
+
+One option in a segmented control, and nothing on its own — a segment says it is the chosen one of a set, and a set of one has nothing to be chosen from. …
+
+`import { SegmentedControlItem } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- One option in a SegmentedControl — the thing a reader presses to change which of a few mutually exclusive values is in force
+- A choice worth showing beside its alternatives rather than hiding in a list, so the reader compares and picks in one glance
+
+## Something else, when
+
+- The option names a slice of the page the reader moves to rather than a value they set → **Tab**
+- The choice is on or off rather than one of several → **Button**
+- The option leads somewhere → **Link**
+
+## Never
+
+- A standalone control. Outside a SegmentedControl nothing injects `selected`, so the segment answers for itself and is a pill that never changes — and `role="radio"` outside a radiogroup is a promise about a set that is not there
+- A submit. This is `type="button"` deliberately: a segment inside a signup form that posted it would be a navigation nobody asked for
+- A long phrase. A row is read across at a glance, and a segment carrying a sentence is a row the reader has to work through one word at a time
+
+## Props
+
+- **selected** `boolean` · default false — Never from the call site in ordinary use — SegmentedControl injects it, because exactly one segment may be current and a segment cannot see its siblings. …
+  - never: Marking more than one. A row with two segments selected is a radiogroup announcing two answers to one question, and the group overwrites whatever it was given on every render regardless
+- **disabled** `boolean` · default false — This one option is unavailable while the rest still answer — a plan the reader's account cannot take, a period an offer does not run for. It stays findable and simply refuses the press
+  - never: Closing the whole row. SegmentedControl has its own disabled for that, which dims as one object and marks no segment — a row barred segment by segment would put disabled on the segment holding the value, and that pair is refused
+- **size** `enum` · default "md" — Never from the call site — SegmentedControl injects it. A row at mixed heights is not a row, so the height is the group's decision and is overwritten on every render
+  - `sm` — A control seated in something already dense — a filter row, a picker in a navigation bar. Desktop only: below what a finger reliably hits
+  - `md` — The default. Sized to a medium control, so the row lines up with the fields and buttons next to it
+  - `lg` — A choice in a hero or a conversion band, where the control is the point of the section rather than an adjustment within it
+  - never: Making one segment stand out. Every segment in a row is the same size; a choice that needs emphasis has it in the copy around the control
+- **value** `string` · required — Always. It names this segment for a group that is told which value is in force from outside, and it is what reaches the consumer's onChange when the segment is pressed
+  - never: The words the reader sees. That is label — a value is an identifier the page matches on, and one doubling as copy breaks the moment the copy is reworded
+- **label** `string` · required — Always — it is the segment's accessible name as well as its words, and a radio with no name is announced as a control with nothing in it. …
+  - never: A sentence, or a value with its unit spelled out. 'Yearly' rather than 'Billed once a year' — the explanation belongs beside the control, where a reader who is not choosing still sees it
+- **icon** `node` · optional — The glyph tells the modes apart faster than the words do — a card and a bank beside two payment methods. Import it from @deriv-com/quill-icons-web and pass the element
+  - never: Decoration. A row of segments is scanned, and a mark that says nothing the label does not is one more thing to look past on every one of them
+- **onSelect** `callback` · optional — This segment reports its own presses — logging which plan a visitor looked at, say. It is called with this segment's value, and SegmentedControl chains its own handler after it rather than replacing it
+  - never: Holding which segment is current. That is the group's onChange, which fires once for the row; a page wiring up one handler per segment has written the group's job out by hand
+
+## The type refuses
+
+- selected=true with disabled=true — The segment holding the value in force cannot also be the one the reader may not pick. …
+- disabled=true with state="hover" — A barred segment does not answer the pointer, so there is no tint for it to take. …
+- selected=true with state="hover" — The chosen segment does not answer the pointer with a tint, because it is already the answer — a hover treatment there says 'you could pick this' about the thing the reader has picked. …
+
+## Inside it
+
+- 9 components are refused inside it; the list and the reasons are in the long document.
+- Renders 4 parts: root, icon, label, sizer.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/segmentedcontrolitem.md`.

package/.llm/digest/select.md

@@ -0,0 +1,92 @@
+<!-- GENERATED from select.contract.json. Do not edit. -->
+
+# Select
+
+A control for choosing one answer from a set the reader scans. …
+
+`import { Select } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- A form asks for one answer out of a set the visitor recognises — a country, a language, the reason they are getting in touch
+- An index or a table is worth narrowing, and the choice reshapes the page rather than being submitted — the sort on a list of articles, the market a pricing table shows …
+- The set is long enough that showing it in full would crowd the page, which is what separates this from a row of chips or a segmented control
+
+## Something else, when
+
+- The set is a handful and worth comparing side by side → **SegmentedControl**
+- The choices are destinations rather than answers → **DropdownMenu**
+- The reader can pick more than one → **nothing in this system does this**
+- The answer is not on the list, and typing one should stand → **nothing in this system does this**
+
+## Never
+
+- Navigation. A set of destinations drawn as a form field is a menu the visitor will answer rather than follow, and the press that should have loaded a page instead sets a value nothing reads
+- Two answers at once. The box holds one, and a second choice replaces the first silently — a reader who meant to add has removed, and nothing told them
+- A set of two. A box that opens to reveal yes and no is three interactions where a Switch or a pair of radio buttons is one, and the reader cannot see what they are choosing between until they have already committed to finding out
+- Hiding how long a list is. A closed box says nothing about whether it holds six answers or six hundred, which is fine when the reader knows the domain and a trap when they do not — a hundred unlabelled options is a set that needs searching, and saying so is what `searchable` is
+
+## Props
+
+- **size** `enum` · default "md" — Choosing the type, the inset and the height of the box — the same three things it chooses on a TextInput, and a form mixing the two at different steps reads as two forms. The rows in the open list follow it as far as they can. …
+  - `sm` — A filter row above an index, or a narrowing that sits in a bar rather than in a form. Desktop only: below what a finger reliably hits, which is why a filter row that has to work on a phone takes md
+  - `md` — The default, and what a marketing form wants. It matches TextInput at the same step, so a contact form's country field and its email field are the same height
+  - `lg` — A hero, a conversion band, or a form that is the whole point of the page. The step that pairs with a large Button, so the field and the thing that submits it agree
+  - never: Signalling importance. A larger box is a larger target and nothing else — a page that sizes one field up to say it matters has made every other field look optional
+- **status** `enum` · default "none" — The outcome of a check on the answer, and whether one is running. On a marketing page this nearly always arrives after the visitor presses send, because a landing page has nothing to check against until then
+  - `none` — Nothing has been checked, or the answer passed and saying so would be noise. The ordinary state, and the one a page sits in until a form is submitted
+  - `pending` — The answer is being checked and the outcome is not known. The control stays usable and the border does not move: a wait is not a verdict. …
+  - `error` — The answer cannot be accepted and the visitor has to choose again. The one status a marketing form reaches for often, and it arrives on submit
+  - `warning` — The answer is accepted but likely wrong — a country that changes what else the form asks, a region the offer is not available in
+  - `success` — The answer was checked against something and passed, and confirming it is worth the space. Rare here: a form that ticks every field a visitor fills is a form congratulating them for typing
+  - never: Decoration, or a permanent state. A control that always looks like a warning is telling the reader nothing, and a marketing page that paints a field red before the visitor has done anything has accused them of a mistake they have not made
+- **fixed** `boolean` · default false — The answer is settled and still worth reading — a region a page was entered through, a plan a link arrived with. …
+  - never: A control nothing can be answered from, which is disabled and recedes. The difference is whether the answer is worth reading: this keeps it legible and disabled makes it too faint to read, so using one for the other loses exactly the thing the reader came for. And decoration on a marketing page. …
+- **label** `string` · required — Always — a control with no label is unusable by a screen reader, and on a marketing page it is also the only thing telling a visitor what is being asked before they commit to opening it. …
+  - never: The instruction, which belongs in the placeholder, or the rule, which belongs in helperText. A label that explains has stopped naming
+- **labelTooltip** `string` · optional — A short explanation the label has no room for — why the answer is asked for, what it changes further down the form. Revealed on hover and on focus, so it costs no height
+  - never: Anything the visitor needs before they open the list, which is helperText and belongs on screen. A marketing page's reader is not committed enough to go hunting for an explanation behind a glyph
+- **placeholder** `string` · required — Always. What the box says with nothing chosen — an instruction rather than an example, there being nothing to spell: "Select a country". …
+  - never: A fake answer. A placeholder that reads like an option makes the control look already answered, and a required set with a plausible-looking default is the commonest way a form collects a value nobody chose
+- **helperText** `string` · optional — What the visitor needs to know before they choose — what the answer affects, or where to look if none of the options seem right. …
+  - never: Validation results, which belong in statusMessage and appear only once something has been checked
+- **value** `string` · optional — The chosen answer, when the consumer owns it — the controlled form. The value and not the words, so a page holds "sg" while the box shows "Singapore" and the words can be reworded or translated without changing what any form submits. …
+- **defaultValue** `string` · optional — The answer the control starts on — a region guessed from where the visitor arrived, or a sort an index defaults to. Leave it out and the placeholder shows, which is what a set with no safe default wants
+- **onChange** `callback` · required — Always, and it is required for that reason. It hands back the value of the answer taken, each time one is taken — the value rather than an event, there being no keystroke here to read one off. …
+  - never: Nothing — there is no case for leaving it out. A control whose whole output arrives through one callback is not usable without it, and leaving it optional only moves the discovery to runtime. If the answer should not be changeable, that is `fixed`
+- **open** `boolean` · optional — Whether the list is showing, when the consumer owns that too. Left out, the control opens and shuts itself, which is what almost every page wants
+- **defaultOpen** `boolean` · optional — Open on first render. For a documentation page or a specimen that has to show the list without anybody pressing anything — not for a page a visitor lands on, where a list that opens by itself covers whatever is under it
+- **onOpenChange** `callback` · optional — Told when the list opens and shuts, for a page that has to react — closing something else, or holding a scroll position
+- **searchable** `boolean` · default false — The set is long enough that finding an answer by eye is work — countries, languages, the markets an index covers. …
+  - never: A set short enough to read at a glance. A search field over six answers is one more thing to get past before reaching what was already in front of the reader — and a letter pressed at this control already jumps to the row beginning with it, without a field to type it into
+- **emptyLabel** `string` · optional — What the surface says when the query matched nothing — "No countries match" rather than a surface that empties. …
+  - never: A set that arrived with nothing in it. That is a page with nothing to offer, and saying nothing matches blames a query the visitor never typed
+- **required** `boolean` · default false — The form cannot be submitted without an answer, and the visitor should know before they reach the end. …
+  - never: Validation. It marks and announces the control as required and nothing more — whether the answer is acceptable is still said through status and statusMessage
+- **requiredMark** `enum` · default "text" — Choosing how a required control says so. Decide which state is the exception first — mark the required ones or the optional ones, whichever are fewer
+  - `text` — Short forms, public ones, and anywhere the label row has room. …
+  - `asterisk` — Long or dense forms where the word repeats down the page and one legend can say it once instead. Only where that legend is visible from the fields it governs
+  - never: Varying within one form. A page marking some labels with a word and others with a glyph reads as two conventions and teaches neither
+- **optional** `boolean` · default false — Most of the form is required, so the few that are not are worth marking instead. The common shape on a marketing page, where a form asks for two things it needs and one it would like
+  - never: Marking every optional control on a form where most are optional — a marker on almost every label is noise
+- **statusMessage** `string` · optional — Saying what the status means: what is wrong and how to fix it, what to look at, or what was confirmed
+  - never: Restating the status. "Error" beside a red control says nothing the colour has not, and the colour is the part a colour-blind reader may not get
+
+## The type refuses
+
+- required=true with optional=true — A control is one or the other, and marking it both says nothing
+- status="error" with statusMessage=null — An error with no explanation leaves the visitor stuck, and a visitor stuck on a marketing form leaves the page rather than the field
+- status="warning" with statusMessage=null — A warning with no explanation is a control the reader cannot act on
+- status="pending" with statusMessage=null — A wait with nothing said is a control that has stopped responding. …
+- fixed=true with state="hover" — A box that does not open has nothing to offer a pointer, so there is no ring for it to take. …
+- searchable=true with emptyLabel=null — A list that can be narrowed to nothing has to say when it has been, or the surface empties with nothing to explain it
+
+## Inside it
+
+- Takes only Option.
+- 5 components are refused inside it; the list and the reasons are in the long document.
+- Renders 18 parts: root, label-row, label, label-tooltip, required-mark, optional-mark, control, field, answer, value, trailing-icon, popup, search, listbox, empty, helper, message, message-icon.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/select.md`.

package/.llm/digest/selectchip.md

@@ -0,0 +1,68 @@
+<!-- GENERATED from selectchip.contract.json. Do not edit. -->
+
+# SelectChip
+
+A chip that opens a list of answers and keeps the one chosen, so a filter row shows the current narrowing rather than the name of a filter. …
+
+`import { SelectChip } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- A row narrows an index by one value out of a set, and has to keep showing which value that is
+- The set is short enough to scan rather than search — a region, a language, a sort order
+- The row has no space for a form field: nothing above the control, nothing beneath it, only the answer
+
+## Something else, when
+
+- Pressing an item does something rather than answering something → **DropdownMenu**
+- The chip answers on its own, or the set is short enough for every answer to sit in the row as a chip of its own → **FilterChip**
+- Each answer is a page with its own address → **Link**
+
+## Never
+
+- Running commands. Nothing here is performed — the list holds answers, and a reader who reopens it finds the one they gave still marked
+- A form field. There is no label row, no helper and no status, so a control that must be explained or validated has nowhere to say it
+- More than one answer at once. One chip carries one value; a set of narrowings that stack is a row of FilterChips
+
+## Props
+
+- **disabled** `boolean` · default false — The narrowing cannot be made just now — the set is empty, or the index it governs has not loaded. It dims and leaves the tab order
+  - never: The reader could act on it if they knew what to change. This says the choice is closed and nothing about why, so a reason belongs in the prose around the row
+- **size** `enum` · default "sm" — How dense the row is, matched to whatever it sits beside. The chip takes the size and the list it opens follows, so a reader never meets rows from one size under a chip from another
+  - `sm` — The default, and the same measure a FilterChip takes at its own default, so a row holding both sits level
+  - `md` — A touch-first layout, or a filter row in a hero band where the chips carry more weight
+  - never: Marking one chip in a row as more important. They are a set of equals and a row of mismatched heights reads as a mistake before it reads as emphasis
+- **alignment** `enum` · default "start" — Which edge the list is pinned to. The other edge is let go, so the list is as wide as its longest answer with the chip's width as a floor
+  - `start` — The list's leading edge lines up with the chip's. The default, because a reader reads from that edge and the answers begin where the chip's own words began
+  - `end` — Its trailing edge lines up instead, for a chip near the end of a row where a list opening the other way would run off the screen
+  - never: Nudging the list into place a few pixels. It names an edge to line up, not an offset
+- **label** `string` · required — Always, and required on that account — it names what is being chosen, and it is what the chip shows until something has been. Short enough to read at a glance in a row of other chips
+  - never: Describing what pressing it does. The chip names the narrowing, and what happens is that a list opens
+- **value** `string` · optional — The page owns the answer — it arrives from a URL, is shared with something else on screen, or has to survive the chip unmounting. Passed, this is the answer, and onChange is the only way it moves
+  - never: Seeding a first answer and then leaving it alone. That is defaultValue, and passing this instead gives a chip that cannot be changed
+- **defaultValue** `string` · optional — An answer the chip arrives carrying, which the reader is then free to change. The uncontrolled half of the pair, and what almost every use wants
+  - never: Keeping the answer in step with something else on the page. Once set it is the chip's own; a page that has to steer it wants value
+- **onChange** `callback` · required — Always, and it is required for that reason. It hands back the value of the answer taken, each time one is taken. …
+  - never: Nothing — there is no case for leaving it out
+- **open** `boolean` · optional — The page owns whether the list is showing — closing it when something else opens, or holding it open across a re-render. Left out, the chip opens and shuts itself, which is what almost every use wants
+  - never: Opening the list once on arrival. That is defaultOpen; passing this pins it open until the page says otherwise
+- **defaultOpen** `boolean` · optional — The list is showing when the chip arrives, and the chip owns it from there
+  - never: A list that should stay open. Anything the reader can shut and the page must reopen wants open
+- **onOpenChange** `callback` · optional — Something outside the chip has to know the list opened or shut — closing another one beside it, or reporting the interaction
+  - never: Reading the answer. That is onChange, and shutting is not answering
+- **leadingIcon** `node` · optional — A glyph makes the kind of narrowing faster to recognise than its name alone. It sits before the words and never replaces them. …
+  - never: Decoration, or a second copy of what the word says. A row where every chip carries a mark that adds nothing reads more slowly than plain words would
+
+## The type refuses
+
+- disabled=true with open=true — A chip that cannot be used has no list to show. …
+
+## Inside it
+
+- Takes only Option.
+- 6 components are refused inside it; the list and the reasons are in the long document.
+- Renders 6 parts: root, trigger, trigger-icon, trigger-label, chevron, listbox.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/selectchip.md`.

package/.llm/digest/spinner.md

@@ -0,0 +1,52 @@
+<!-- GENERATED from spinner.contract.json. Do not edit. -->
+
+# Spinner
+
+A turning ring that says a wait is real and the page has not stalled. …
+
+`import { Spinner } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- The reader has just submitted something — a signup, a contact request — and the page owes them a sign that it is working
+- A section is holding space for content that arrives separately: an embed, a demo, a band of live figures
+- Something the reader asked for is on its way and nobody can say how long it will take
+
+## Something else, when
+
+- The wait is the page's own first load → **nothing in this system does this**
+- How much is done is known, or could be → **nothing in this system does this**
+
+## Never
+
+- A wait short enough that the ring is a flash. A spinner that appears and goes inside a few hundred milliseconds reads as a glitch in the page rather than as work being done, and the reader is left with the flicker rather than the result
+- More than one in a view. Three rings turning in three cards is a page that looks broken rather than busy — one spinner for the thing being waited on, at the level the reader is looking
+- Decoration. A ring turning in a hero because the section looked static is motion with nothing behind it, and it teaches a reader that a spinner on this site does not mean a wait
+- Standing in for content whose shape is already known. A ring in the middle of a section says nothing about what is coming and holds no room for it, so the layout jumps when it arrives — space the content will fill is better held by the space itself
+
+## Props
+
+- **size** `enum` · default "md"
+  - `sm` — In a line of body copy, or inside a control the reader has just pressed. Sixteen, the size of the words beside it, so it sits on the line rather than in front of it
+  - `md` — The default. A form that has been submitted, a card waiting on the figure it is going to show
+  - `lg` — A section holding space for something that arrives separately — an embed, a demo, a band of live figures. …
+- **variant** `enum` · default "accent"
+  - `accent` — The default, and what a page nearly always wants. The wait is the one thing happening, and the brand colour is what says the page is doing it rather than failing to
+  - `neutral` — The wait is incidental to what the reader came for — a figure refreshing inside a card that is otherwise readable. …
+  - `inherit` — Inside something that has already set a colour: a filled button, a dark band, a coloured panel. `currentColor` reaches the ring and the label together. …
+  - never: Marking one wait as more important than another. Two spinners in a view is the thing to fix; recolouring one of them is not
+- **label** `string` · optional — Naming what is loading, for a spinner that stands on its own — a section, a form, a button whose own words have been replaced by it. …
+  - never: A second voice for something the page has already said. A ring beside a line reading “Sending your details” is not a separate thing loading, and naming it makes a screen reader announce the wait twice. Omitting it is what that case is for — an empty string is not, because an unnamed live region is still a live region and it still fires
+- **showLabel** `boolean` · default false — The words should be drawn as well as announced — beneath the ring, for a section or a form where the reader can see the wait but not what it is for
+
+## The type refuses
+
+- showLabel=true with label=null — A label shown on screen with no text in it is a gap held open under the ring, and a centred block that is no longer centred on anything
+
+## Inside it
+
+- Renders 4 parts: root, circle, track, label.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/spinner.md`.

package/.llm/digest/stack.md

@@ -0,0 +1,56 @@
+<!-- GENERATED from stack.contract.json. Do not edit. -->
+
+# Stack
+
+A column, and one measure between its rows. It draws nothing — no ground, no edge, no padding — and owns one decision: how far apart the things stacked in it sit. …
+
+`import { Stack } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- Two or more things are read down the page in order and the space between them is the same the whole way down — an eyebrow, a headline and a line of copy; the points of a feature list; the rows of a plan …
+- The spacing is a fact about the group rather than about any member of it. …
+- The measure should tighten on a phone without anyone writing a breakpoint. …
+
+## Something else, when
+
+- The things sit beside one another rather than one above the next → **Row**
+- The things must line up across as well as down → **Grid**
+- The set has to stay on one line and the reader moves along it → **Scroller**
+
+## Never
+
+- Padding. It sets space between its children and none at all around them, so a stack reached for to inset a section leaves the band that should have carried the padding with none — and the inset now lives on an element that has no ground to sit on
+- A single child. A column of one has nothing to space: the gap is inert, and what is left is an element that renders, costs a node, and explains nothing to the next person to read it
+- Reaching a width. It is as wide as whatever holds it and declares no size of its own. A page's measure is a decision about the page, and a stack used to constrain one is a width hidden inside a spacing decision, in the one place nobody will search for it
+- Putting one thing in a particular place. The gap is a relationship between rows, not a distance from an edge — a measure picked because it lands something where it looks right is a position written in the wrong units, and it is wrong at the next width and on the next screen
+- Separating sections that a ground already separates. A band with a fill of its own has an edge, and an edge is the separation; a large gap on top of it is the page saying the same thing twice and the reader reading a hole
+
+## Props
+
+- **gap** `enum` · default "md" — Always. The measure between rows is the component's one decision and the reason it exists, so there is no case for leaving it unstated
+  - `none` — No gap at all, for rows meant to read as one object rather than as a list of controls. The only step here that is a decision rather than a measure
+  - `xs` — The tightest gap between related elements — an eyebrow and the headline under it, a figure and the caption beneath
+  - `sm` — The default step for sibling controls, and what the token names for a form label and the input under it
+  - `md` — The default, and what the token names for stacked items: form fields, feature list items, pricing features. Reach for this unless the column has a reason to be tighter or looser
+  - `lg` — Between content groups — feature cards, footer columns, one pricing plan and the next
+  - `xl` — Between the parts of a card, or between a heading and the block it introduces. Drops one step below 768px, a phone having a third of the width to spend
+  - `2xl` — Between one section of a page and the next. Drops one step below 768px, a phone having a third of the width to spend
+  - `3xl` — The largest gap, for separating whole movements of a long page. Drops one step below 768px, a phone having a third of the width to spend
+  - never: Reaching a distance. The gap is a relationship between two rows rather than a measure from anything — a step picked because it puts something where it looks right is a position written in the wrong units, and it is wrong at the next width
+- **align** `enum` · default "stretch" — How wide the rows are, and where they sit across the column. The default is the common case and the one that keeps a stacked set looking like a set
+  - `start` — Rows keep their own width and sit against the leading edge — a column of links, or a call to action as wide as its own label
+  - `center` — Rows keep their own width and are centred — a hero's copy, a closing block, anything read as one object on a ground wider than it
+  - `end` — Rows keep their own width and sit against the trailing edge, which on a page is rare and usually means the column is in a panel rather than in the flow
+  - `stretch` — The default. Every row takes the column's full width, which is what stacked cards, fields and bands want, and what makes their edges agree down the page
+  - never: Centring the words inside a row. This moves the row and not its contents — a paragraph centred by setting the column to `center` is also a paragraph shrunk to the width of its longest line, which is a different thing and rarely the wanted one. Centred text is `text-align` on the text
+- **justify** `enum` · default "start" — Where the rows sit down a column that has more height than they need. On a page that is usually a card in a row of cards, stretched to its tallest neighbour
+  - `start` — The default. Rows sit at the top, and a column with no height of its own is exactly as tall as they are
+  - `center` — Rows sit together in the middle of a column that is taller than they are — a card in a row of cards whose copy is shorter than its neighbours'
+  - `end` — Rows sit at the foot of a column taller than they are
+  - `between` — The first row at the top, the last at the foot, and whatever room is spare shared between them — the shape a pricing card takes, where the price is at the top and the button has to sit on the same line as every other card's …
+  - never: Making a column taller. This shares out height the column already has; where the column is sized by its own contents there is no room to share, and every value here draws exactly the same thing — which is the failure this prop has, silent and easy to spend an afternoon on
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/stack.md`.

package/.llm/digest/statusdot.md

@@ -0,0 +1,46 @@
+<!-- GENERATED from statusdot.contract.json. Do not edit. -->
+
+# StatusDot
+
+A small coloured circle that marks one thing in a list of otherwise equal things — either because it is worth noticing, or because it is in a state the others are not. …
+
+`import { StatusDot } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- Marking something the page is pointing at — a plan that is new, a feature worth finding in a list of them. …
+- Showing presence or availability alongside a name
+- Indicating system health or severity in a compact space, where a word for each would cost more room than the difference is worth
+
+## Something else, when
+
+- The status needs a text label inside a colored pill → **Badge**
+
+## Never
+
+- Conveying status without an adjacent text label — color alone is not accessible
+- A bullet, or a mark that means nothing at all — use plain CSS or a list element. The accent variant is not the exception it looks like: it says the page is pointing at this one rather than the others, which is a meaning. A dot on every row in a list means nothing by saying it everywhere
+- Carrying the meaning in tooltip alone — a description that has to be pointed at is absent on touch and to anyone reading the page rather than exploring it. The adjacent text label is what says what the state is; the tooltip only says more about it
+
+## Props
+
+- **variant** `enum` · default "accent"
+  - `accent` — A mark in the brand colour, for something worth noticing that is not a state — a feature that is new, an item the page is pointing at. …
+  - `success` — Available, online, healthy, or passing
+  - `warning` — Away, degraded, or approaching a limit
+  - `error` — Busy, offline, failed, or critical
+  - `info` — In progress, syncing, or informational
+  - never: And never as a neutral or unknown state. This variant says the brand is pointing at something; it does not say a condition is unknown, and there is no longer a dot that does — the four that remain each name a condition, and a mark that reports nothing at all is text or a Badge rather than a dot
+- **pulse** `boolean` · default false — The status is live or actively changing — draws attention to an ongoing state
+- **label** `string` · optional — The rare dot that stands alone. Ordinarily leave this out: the contract asks for a visible text label beside every dot, and that text is what says what the state is — so a dot naming itself as well is heard twice, "Status, Online". …
+  - never: Repeating the words already beside it, which is what makes a screen reader say the state twice. Nor for the explanation, which is tooltip. There is deliberately no default: a generic name would satisfy this without anybody choosing it, and it did — every unconfigured dot announced the word "Status" beside text that already said the state
+- **tooltip** `string` · optional — The state has a meaning the colour and the adjacent label together still do not explain — why a service is degraded, what "away" counts as. A few words, revealed on hover and on keyboard focus
+  - never: A sentence the reader must have, or anything longer than a phrase. Setting this puts the dot in the tab order, because a description no keyboard can reach is one this system does not ship — so a tooltip on every dot in a list of twenty is twenty new tab stops, and worth spending only where the explanation is
+
+## The type refuses
+
+- tooltip="*" with label=null — A tooltip puts the dot in the tab order, so that it can be reached by something other than a pointer. …
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/statusdot.md`.

package/.llm/digest/subdomainnavbar.md

@@ -0,0 +1,54 @@
+<!-- GENERATED from subdomainnavbar.contract.json. Do not edit. -->
+
+# SubdomainNavbar
+
+The bar across the top of a subdomain — a documentation site, a playground, a product surface that lives beside the marketing site rather than inside it. …
+
+`import { SubdomainNavbar } from '@deriv-com/dds-marketing'`
+
+## Reach for it when
+
+- A subdomain needs its top-level navigation — the mark, the places that subdomain has, and whatever sits at the far end
+- The bar should sit still. …
+- The destinations belong at the far end with what a reader reaches for, rather than centred over the page: the mark holds one edge, everything a reader does holds the other, and the middle is left empty on purpose …
+
+## Something else, when
+
+- The page is the marketing site itself → **Navbar**
+- The items are versions of one thing rather than places the subdomain has → **TabList**
+
+## Never
+
+- A second bar further down the page. There is one landmark of this kind per page, and a reader who meets two has been told twice where they are and once too often which is authoritative
+- A toolbar. Controls that act on what is below them belong in the page, not in a landmark that announces itself as the way around the site
+- The marketing site's own bar. The two are different components because they behave differently, and using this one there loses the thing that bar is for
+
+## Props
+
+- **tone** `enum` · default "default"
+  - `default` — The subdomain's chrome is light, which is the page's decision rather than this bar's
+  - `inverse` — The subdomain's chrome is dark, which is the usual case for a tool and is why nearly every page using this bar will pass it. …
+- **label** `string` · required — Always — it names the navigation landmark, and a page with an unnamed one tells a screen-reader user there is navigation here without saying which navigation. …
+  - never: A visible heading. Nothing draws this. A bar needs no title, and a page that wants one has a heading of its own below the bar
+- **menuLabel** `string` · required — Always — the trigger is an icon-only button and this is the only name it has, at the width where it is the only way through the site. …
+  - never: A tooltip or visible text. The trigger draws a glyph and nothing else; this is the name a screen reader reads
+- **closeLabel** `string` · required — Always — it names the panel's close button, which is the only visible way out of a surface covering the whole page. 'Close' is enough; the panel it closes is the only thing open
+  - never: The trigger's name. They are two controls in two places — the trigger is in the bar underneath the panel, and a reader cannot reach it while the panel is open
+- **brand** `node` · optional — Effectively always on a real site — the mark, and usually an anchor to the home page wrapped around it. It is drawn twice: in the bar, and again in the panel's header, where it is the only thing left saying whose site this is
+  - never: A heading for the page. This is the site's mark, not the page's title, and a reader who meets the page's `<h1>` in the bar has been told the name of somewhere they already are
+- **utilities** `node` · optional — The bar's trailing end has something in it — a language switcher, a theme switcher, what the subdomain wants pressed, or some combination. …
+  - never: Destinations. Anything that goes to a section of the site belongs in the children, where the navigation landmark announces it as one. The trailing end is for what a reader reaches for, not for the places the bar ran out of room for
+- **menuOpen** `boolean` · optional — The page is holding whether the panel is open, because something else depends on it — a route change that should close it, a surface of its own that must not open at the same time. …
+  - never: Half of a controlled bar. A menuOpen passed without an onMenuOpenChange to move it is a panel that cannot be closed from its own close button — a trap around the whole page rather than a bar with a bug
+- **onMenuOpenChange** `callback` · optional — Whenever menuOpen is — together they are how a page holds the panel. It is called with the state being moved to, by the trigger, by the close button and by Escape, so a page listening to it hears every way the panel can change
+  - never: Navigation. This says whether the panel is showing; a page that also routed on it would close the panel by leaving, and a reader pressing a destination inside it would fire both
+
+## Inside it
+
+- Takes only NavbarItem, NavbarMenu.
+- 11 components are refused inside it; the list and the reasons are in the long document.
+- Renders 7 parts: root, inner, brand, nav, utilities, trigger, panel-host.
+
+---
+
+The reasoning behind each of these, the parts this renders, its states and snippets that compile: `.llm/components/subdomainnavbar.md`.