@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/navbarswitcher.md

@@ -0,0 +1,343 @@
+<!-- GENERATED from navbar-switcher.contract.json. Do not edit. -->
+
+# NavbarSwitcher
+
+Something a reader sets rather than somewhere they go: the language the page is read in, the region its prices are in, the theme it is drawn in. It sits in a navigation bar beside the destinations and takes two quite different forms depending on where it is drawn.
+
+In the bar it is a trigger and a menu hanging off it. In the collapsed panel it is a row that opens a page of its own, with a way back — because a menu inside a surface that already covers the screen is a surface inside a surface, and because a phone has room to show sixteen languages properly only if it stops showing everything else.
+
+The container decides which, exactly as it decides for NavbarMenu. A page writes the switcher and its choices once.
+
+## Use when
+
+- A bar needs a language or region switcher, which is the case this was drawn for
+- A set of choices changes how the page is drawn or worded rather than taking a reader anywhere
+- The set is long enough that a phone should give it the whole panel rather than a dropdown inside one
+
+## Do not use
+
+- The control opens a set of commands rather than a set of choices → `DropdownMenu`
+- The control flips between two states → `ButtonIcon`
+- The items are places the site has → `NavbarMenu`
+- Navigation. Nothing in here has an href, and a reader who was taken somewhere by a switcher has been told the set was one thing and given another
+- A form field. A select inside a form is a Select: it has a name, it posts a value, and it is read as part of the form rather than as part of the chrome
+
+## Anatomy
+
+NavbarSwitcher renders 7 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-navbarswitcher`. The switcher. `position: relative` so the floating form has something to hang from, which is also the reason it is a box at all rather than the trigger standing on its own.
+- `trigger` — `<button>`, class `dds-navbarswitcher__trigger`. What a reader presses. In the bar it is a mark and the current choice, drawn plain so it sits among the destinations without competing with them. In the panel it is a row the width of the surface, with the choice at one end and a mark at the other saying it opens something.
+  
+  It carries `aria-expanded` in both, and `aria-haspopup` in neither: what opens is a set of choices rather than a menu of commands, and the roles that promise arrow-key navigation over a menu are promises this does not keep.
+  
+  It takes the ink around it. A bar tells a switcher what ground it is on by painting one, and this reads it rather than being told twice.
+  
+  The choice is the trigger's own text rather than a part of its own. A box around it would carry no rule — the type, the ink and the spacing all belong to the trigger — and a part the stylesheet never mentions is a part that exists only in the contract.
+  
+  It reserves the same height as the destinations it sits among.
+  
+  It pads its words by the same step the destinations do, for the same reason: it stands in their row.
+- `icon` — `<span>`, class `dds-navbarswitcher__icon`. The mark that says which question this answers — a globe for a language, without which the trigger is two letters nobody can place.
+  
+  It is drawn at the step that sits with the words rather than above them. The trigger is set in `font.label.sm` and `icon.size.xs` is the nearest step to it — a mark a step larger reads as the thing being said and the letters beside it as a note on it, when the sentence is the other way round: the choice is what a reader came for and the globe only says which question it answers. It is also the measure the chevron at the other end takes, so the two marks bracketing the row agree. Rendered only when `icon` is set.
+- `chevron` — `<span>`, class `dds-navbarswitcher__chevron`. The mark that says this opens. Absent by default, because in a bar this sits among destinations that each carry one and a third would be repetition rather than signal — and present in the panel whatever the page said, because a row in a list gives a reader nothing else to go on. It points along the reading direction there rather than down: what opens is a page beside this one, not a drawer beneath it. Rendered only when `chevron` is set.
+- `surface` — `<div>`, class `dds-navbarswitcher__surface`. The choices. Floating, it is a panel hanging off the trigger. In the panel it covers the destinations and the switchers below them and stops at the header, so the mark and the way out stay on screen while a reader is two levels in.
+  
+  It is not a menu and takes no menu role. What it holds is a set of states, and `role="menu"` would promise arrow-key navigation over commands — a promise whose first consequence is that a screen reader stops announcing the choices as buttons.
+  
+  In the panel it takes its own air rather than the panel's. It covers the body, which is inside the panel's inline inset already — so what it needs is the step between its own edge and the names in it, and enough above them for the way back to sit clear of the row it replaced.
+  
+  It names its own ink, and that is the one thing here it must not inherit. The trigger takes the colour around it — that is how a switcher reads on a bar of any ground — and this panel is paper whatever the bar is standing on. Inheriting, a switcher on a dark bar drew white words on a white panel: the whole set was there, laid out correctly, and the only one a reader could see was the current choice, which names its own colour.
+  
+  And it states its width, because a box out of flow is sized against the thing it hangs from. Shrink-to-fit against a trigger two letters wide gave a panel two letters wide, with every choice wrapped and the set running down the page — which is what it was doing when both of these were found together.
+  
+  Floating, it is the same shape as the panel a section opens: `radius.container` and an inset of `space.inset.md`. The two hang off the same bar and a reader meets them one after the other, so a corner or an inset that differed would read as two systems rather than one — and neither difference would be saying anything, which is the test for whether a difference belongs. Rendered only when `open` is set.
+- `back` — `<button>`, class `dds-navbarswitcher__back`. The way back to the panel, drawn only where there is one. A reader who has drilled into a set of sixteen languages needs to leave without choosing, and the close button at the top of the panel closes the whole thing rather than this — so a page with no way back but out is a page that punishes curiosity.
+  
+  It points against the reading direction, which is the one convention this can rely on being read correctly in every language the set offers.
+  
+  It resets its padding, which a `<button>` needs and `appearance: none` does not do. The user-agent sheet gives a button an asymmetric pad — six pixels across, one down — so a control declared as a square target drew as a rectangle a third wider than it was tall, and the shape only became visible when something filled it under a pointer. The measure comes from the minimums above; nothing else should be adding to them.
+  
+  No hover fill. It is drawn only in the panel, which is the arrangement a bar reaches at a phone's width — there is rarely a pointer there to answer, and the shape it drew when there was one was the only thing in the panel with a ground of its own. The bar's own trigger and the panel's close gave theirs up for the same reason.
+  
+  The focus ring stays. It answers to a reader with no pointer at all, and this is the way out of a set that has replaced everything else on the screen.
+- `list` — `<div>`, class `dds-navbarswitcher__list`. The choices themselves. One column floating, where the panel is as wide as its longest word and no wider; two in the panel, where the surface is a whole screen and sixteen languages down one column is a scroll for something a reader can take in at a glance.
+  
+  Multi-column rather than a grid, for the reason NavbarMenu's sets are: a grid aligns its rows, so a short name beside a long one is stretched to the taller and the next pair starts below both.
+  
+  The space between two names down a column is the rows' own height, not a gap. Multi-column has no row gap to put one in — `row-gap` is accepted and ignored there — so an option reserves `size.control.md` and the rhythm follows from that, which is also the measure that makes each one a target rather than a line of text.
+
+Apply these classes from the generated `navbarSwitcherParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `NavbarSwitcherOption`
+- Never contains: `NavbarSwitcher`, `NavbarItem`, `NavbarMenu`, `Button`, `Link`, `DropdownMenu`, `MenuItem` — in children or in any prop that takes a node
+
+## Props
+
+### presentation — `floating` | `panel` (default `floating`)
+
+- `floating` — The switcher is in the bar, which is everywhere a page puts one. The choices hang off the trigger and float over what is beneath
+- `panel` — NavbarPanel is rendering it, and it sets this itself — a page should not. Inside the collapsed panel the choices take the whole surface and offer a way back, because a dropdown inside something already covering the screen is a surface inside a surface
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The bar has a light ground under it
+- `inverse` — The bar sits on a dark ground and the ink runs light. Only the tints move — the words take the ink around them either way
+
+### label — `string` **Required.**
+
+Use when: Always — the choice in force, short enough for a bar. "EN", not "English": a bar is read at a glance and a switcher showing the longest name in the set is a switcher that changes width when somebody picks one
+
+### menuLabel — `string` **Required.**
+
+Use when: Always — what the set is, for a reader who meets the trigger without seeing the mark beside it. "Language", "Region". The trigger shows the answer; this says what the question was
+
+### backLabel — `string` **Required.**
+
+Use when: Always. It names the way out of the page the panel form opens, and a glyph pointing left is not a name. Unused in the floating form, which has no page to leave
+
+### icon — `node`
+
+Accepts: Icon
+Use when: A mark saying which question this answers. Nearly always on a bar, where the label is two letters and the glyph is what makes them mean a language
+
+### chevron — `boolean` (default `false`)
+
+Use when: The floating trigger should say it opens. Off by default because a switcher usually sits among destinations that each carry one. The panel form draws one whatever this says — a row in a list has nothing else to go on
+Never for: The panel form, which is not asking
+
+### open — `boolean`
+
+Use when: A container holds which of several things is open. Standing alone the switcher holds its own
+
+### onOpenChange — `callback`
+
+Use when: Whenever open is — together they are how a container holds it
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- Announced as: `button`
+- `Tab` — Reaches the trigger, then the choices once they are showing, then on out. No roving tabindex and no arrow keys: what opens is a set of buttons rather than a menu of commands, so a reader keeps the key they already have
+- `Escape` — Closes the set and returns focus to the trigger. In the panel form it is the same as pressing back
+- `Enter` — Opens and closes, which a button does without anything being added
+- accessible name from menuLabel on the trigger, because the label a reader sees is the answer rather than the question — "EN" alone names nothing
+- The trigger reports whether the set is showing with aria-expanded. A control that reveals something and does not say whether it is revealed leaves a reader pressing it to find out
+- The set takes no menu role. What it holds is choices, and role="menu" promises arrow-key navigation over commands — a promise whose first consequence is that a screen reader stops announcing them as buttons
+- The way back is named by backLabel. A glyph pointing against the reading direction is not a name, and it is the only way out of the panel form that does not close the whole panel
+
+## Rules
+
+- **On a phone a section's actions stack and each fills the width, including when there is only one** — On a phone a page's actions stack, and each one fills the width. Not most of it, and not the width its label happens to need — the whole column.
+
+Two side by side is what this replaces. On the narrowest screen each gets half a column minus the gap, which is rarely enough for a real label: the words wrap inside the pills, the two buttons come out different heights, and the pair reads as a broken row rather than as a choice. Stacked, each has the whole width and neither has to shorten its words to fit.
+
+A single action fills too, and that is the part worth saying, because it is the one that looks unnecessary. A lone button has the room to sit at its natural width and still should not: a full-width control is the phone's convention for the thing the screen is asking you to do, and a pill hugging its label reads as one option among others that are not there. It also makes the target predictable — the whole width, wherever the thumb lands — which a centred pill does not.
+
+Filling is the row's job rather than the button's. A button has no width of its own and is not given one; the row it sits in becomes a column and stretches its children, so nothing about the control changes and the same button is full width here and its own size on a desktop.
+
+This is the phone's breakpoint, size.breakpoint.md, and not the wider one that decides whether a heading is centred. Those are different questions and they break at different widths: a heading stops being centred when the measure is the screen, while a button stops being full width much sooner than that — stretched across a tablet it is a long way from its own label, and a label centred in a metre of pill is harder to hit than one in a pill the size of the words.
+
+What this is not about is every row of controls. A set of filter chips, a pagination strip, a toolbar, a link sitting after a sentence — none of these is the page asking for something, and stacking them to full width would turn a strip the eye skims into a list it has to read. The test is whether the row is the call to action the section was written for.
+  Guidance only — cannot be checked automatically.
+- **Never nest one interactive element inside another** — Nested interactive elements produce ambiguous hit targets and an unreachable inner control for keyboard and screen-reader users. This is why the rule cannot live on any single component — it constrains Button, Link, Input and Switch simultaneously.
+  Guidance only — cannot be checked automatically.
+- **A section that paints a ground sets the ink to go with it** — A page sits on color.bg.page, and a section that separates itself from it takes one of three grounds. color.bg.subtle is the light one and needs nothing further — the page's own ink still reads on it. The other two are dark and do not: color.bg.brand-strong takes color.fg.on-brand-strong, and color.bg.brand takes color.fg.on-solid. Both are white, and both are written as the role rather than the white they resolve to. Set one of those backgrounds without its ink and the text inherits whatever the page was already using, which is near-black on a dark band — legible to nobody, and invisible to every check here, because each pair passes contrast on its own and nothing can tell whether a section used both.
+
+color.bg.brand carries a second limit that is not about forgetting. Its ink measures 3.39:1, which clears the 3:1 a heading needs and misses the 4.5:1 running copy needs. A coral band may carry a headline and a call to action; a paragraph on one is text the reader has to work through at a ratio the waiver on that role does not cover — the waiver says so itself. A section with copy in it takes color.bg.brand-strong, which is near-black and carries white at full contrast.
+
+color.bg.strong is not a section ground. It is the inverted fill for an action that has to outrank what surrounds it, and the components that paint it — Button and ButtonIcon in their inverse form — already set both halves in one rule, which is the pattern a hand-painted section has to copy.
+  Guidance only — cannot be checked automatically.
+- **Every gap inside a section names the relationship it expresses, and the same relationship keeps its measure when it turns on its side** — A section's spacing is named by the relationship it expresses, not chosen by size. Every gap in a section has a role token, and reaching for a step off the generic scale because it happens to be the right number is how two sections written by two people stop lining up: the numbers agree today and drift the first time one of them is tuned.
+
+The heading group is three steps, not one gap. An eyebrow sits nearer its title than the title sits to its description, and the actions sit further from the description than either — space.heading.eyebrow-title, space.heading.title-description, space.heading.description-actions, in that order. A single `gap` on the group cannot say this; it sets all three the same and the block reads as evenly spaced lines rather than as a mark, a name and a paragraph. The eyebrow has to identify itself for this to work, because a group that opens with a title must not give its description the eyebrow's tighter step.
+
+The step between a title and its description follows the size of the title, which is why there are two of it. What a reader sees is not the gap but the gap plus the leading above it, and leading scales with the type: under a display title the leading is most of the space, under a card's title it is half as deep. One value for both makes a card look loose at the size that made a section look right. So space.heading.title-description is the display step and space.heading.title-description-compact is the step at a card's size, and the choice is made by how big the title is rather than by what kind of block it sits in.
+
+Every one of those steps is smaller than the gap below the group, and that ordering is what holds the group together as one thing. space.heading.content is the step between a heading group and the content it introduces, and it is the widest measure inside a section: the one gap the eye reads as a change of subject rather than as a continuation.
+
+That step is the same whether the content is under the heading or beside it. A split is the same relationship turned on its side — a heading group and the content it introduces — so the space between the two halves is space.heading.content, not a gutter. When the split collapses to one column on a phone the gap becomes vertical again, which is where it started, and nothing has to change for that to be right.
+
+space.grid.gutter is between two things of the same kind. Two cards in a row are the same kind; the two halves of a split are not, which is why the gutter is the wrong measure there even when the number would have looked acceptable. The gutter runs on both axes, so a grid reads as an even field rather than as rows with a seam down them.
+
+space.inset.card is the card's, not the page's. A row of cards padded differently is a row of different cards, and the fill is the only edge they have. A page composing a row does not get to choose it.
+
+Column count is not a breakpoint decision. A row holds as many columns as fit before a column would be narrower than size.grid.column-min, and drops one when they would not. Written as a fixed count that collapses at a breakpoint, a four-up row keeps four columns at every width above the phone and sets its copy two or three words to a line through the whole of the tablet range — and on a narrow desktop, which no breakpoint sits on at all. The threshold is a property of the row rather than of a card: a card fills whatever cell it is given.
+
+What this does not cover is the space above and below a section, which is space.section.default and space.section.compact, and the page's own side margin, which is space.inset.page. Those are the section's outside; everything here is its inside.
+  Guidance only — cannot be checked automatically.
+- **A section's title is centred over stacked content, starts beside content in columns, and starts on a phone** — Two arrangements, and the title's alignment is decided by which one it is introducing rather than chosen per section.
+
+Content stacked under the title — a row of cards, an accordion, a set of steps — takes a centred title. The heading group and the block below it share one axis, so a centred title is symmetric with the thing it names, and the eye drops from the middle of the words to the middle of the set. A title starting at the left over a centred or full-width block reads as belonging to the first column rather than to all of them.
+
+Content beside the title — a split, a picture in the other half, anything laid out in columns — takes a title that starts where its content starts. The two share a left edge, and that edge is what says they are one thing read across rather than two stacked. Centring the title there breaks the only alignment the reader has to hold the halves together, and it drifts further from its content the wider the page gets.
+
+The heading group is what carries this, not the heading alone. An eyebrow, a title and a description are read as one block and align together; aligning the title without them leaves a centred heading over start-aligned copy, which reads as a mistake rather than as a choice.
+
+Centred means all of it, not just the words. A badge, a row of actions, a picture — these are flex children, and a flex child is placed by align-items rather than by text-align, so a block that only sets the text leaves everything that is not text at the start. A hero is the case that shows it: its title and copy centred while its badge and its buttons did not.
+
+A capped block centres itself as well as its words. A heading group takes size.heading-group.max, and a cap that is not centred leaves the measure at the start of the column with the words centred inside it — composed, and a long way left of the middle it appears to be in.
+
+Both arrangements go to the start on a phone. A centred block reverts below the breakpoint, and the reason is the measure: on a phone the measure is the screen, so a centred title wraps to three or four ragged lines and the eye loses the left edge it was tracking — the same symmetry that reads as composure on a desktop is what makes it hard to scan on a phone. Centring there has to be asked for twice, and a section title is not one of the things that asks: it is centred because there is room for it, and on a phone there is not. Going back to the start means all of it too, and a capped block is the one that hides a leftover: its words go to the start while its measure stays in the middle of the column, which reads as a title still centred over a badge and buttons that are not — the box in the middle and the line inside it at the edge.
+
+A hero is a section like any other: its badge, title, copy and actions are one stacked block, so it is centred on a desktop and starts on a phone with everything else.
+
+What this is not about is a page whose body is a form or a document. A title over a sign-up form or a guide is not introducing a set of content — it is the first line of the thing itself, and it keeps the alignment the body has, which for running text is the start. The distinction is whether the block below is content the title names or content the title is part of.
+  Guidance only — cannot be checked automatically.
+- **Anything a pointer has to hit is at least 24px in both directions** — A control sized by its contents is as big as its contents, and a glyph is chosen for how it reads rather than for how easily it is hit. An icon-only button with no padding is a 16px target — smaller than the pad of a finger, and smaller than the tremor of a hand using a mouse.
+
+WCAG 2.2 asks for 24 by 24 CSS pixels at AA. The exceptions are narrower than they look: inline targets inside a sentence are exempt, and so is a small target with 24px of clear space around it — but a clear button sits against the field it empties, and a field is itself a target, so the spacing exemption does not apply to the case that keeps arising.
+
+The target and the mark are separate decisions, and conflating them is what produces both faults. Growing the glyph to 24px makes it shout; leaving the button at 16px makes it hard to hit. So the glyph keeps the size that reads correctly beside its text, and the box around it declares a minimum of its own — which is what size.target.min is for.
+
+Declared rather than emergent. Padding plus contents does clear 24px in several components today, and it is the weaker statement: it is a size nobody wrote down, so it moves when the type scale or the glyph does, and nothing says it was meant to be a target at all.
+  Guidance only — cannot be checked automatically.
+
+## Anti-examples
+
+❌ NavbarSwitcher for: The control opens a set of commands rather than a set of choices
+   A menu's rows do things; a switcher's rows are states, one of which is already in force. DropdownMenu has no notion of a current row and should not grow one
+   → use `DropdownMenu` instead.
+
+❌ NavbarSwitcher for: The control flips between two states
+   A theme toggle with two states is a button, not a set. There is nothing to open and nothing to mark as current beyond the mark it is already drawing
+   → use `ButtonIcon` instead.
+
+❌ NavbarSwitcher for: The items are places the site has
+   Those belong in the navigation landmark and are links. These are neither
+   → use `NavbarMenu` instead.
+
+## Example
+
+```tsx
+import { NavbarSwitcher, NavbarSwitcherOption, Icon } from '@deriv-com/dds-marketing'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>}>
+  <NavbarSwitcherOption current onSelect={() => { /* your handler */ }}>English</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>العربية</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Français</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Español</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Português</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Русский</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Italiano</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Deutsch</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Kiswahili</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Polski</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>简体中文</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Монгол</NavbarSwitcherOption>
+</NavbarSwitcher>
+```
+
+```tsx
+import { useState } from 'react'
+import { NavbarSwitcher, NavbarSwitcherOption, Icon } from '@deriv-com/dds-marketing'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// NavbarSwitcher holds nothing: open is the consumer's, and it does not move until
+// the value handed back by onOpenChange is written to it.
+const [open, setOpen] = useState(false)
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>} open={open} onOpenChange={setOpen}>
+  <NavbarSwitcherOption current onSelect={() => { /* your handler */ }}>English</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>العربية</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Français</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Español</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Português</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Русский</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Italiano</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Deutsch</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Kiswahili</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Polski</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>简体中文</NavbarSwitcherOption>
+  <NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Монгол</NavbarSwitcherOption>
+</NavbarSwitcher>
+```
+
+## In use
+
+Most rows below hold the same set, written once here:
+
+```tsx
+import { NavbarSwitcherOption } from '@deriv-com/dds-marketing'
+
+const navbarswitcheroptions = (
+  <>
+    <NavbarSwitcherOption current>English</NavbarSwitcherOption>
+    <NavbarSwitcherOption>العربية</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Français</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Español</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Português</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Русский</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Italiano</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Deutsch</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Kiswahili</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Polski</NavbarSwitcherOption>
+    <NavbarSwitcherOption>简体中文</NavbarSwitcherOption>
+    <NavbarSwitcherOption>Монгол</NavbarSwitcherOption>
+  </>
+)
+```
+
+### Where it is drawn
+
+The container decides, not the page. In a bar the choices hang off the trigger; in a collapsed panel the same element is a row that opens a page of its own.
+
+```tsx
+import { Icon, NavbarSwitcher } from '@deriv-com/dds-marketing'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// floating — in the bar
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>} open>{navbarswitcheroptions}</NavbarSwitcher>
+
+// panel — inside the collapsed panel
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>} presentation="panel" open>{navbarswitcheroptions}</NavbarSwitcher>
+```
+
+### Shut, and open
+
+The trigger shows the choice in force rather than the name of the question — a bar is read at a glance, and the mark beside it says what the letters mean.
+
+```tsx
+import { Icon, NavbarSwitcher } from '@deriv-com/dds-marketing'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// At rest — a mark and the current choice
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>}>{navbarswitcheroptions}</NavbarSwitcher>
+
+// Open — the set, in three columns
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>} open>{navbarswitcheroptions}</NavbarSwitcher>
+```
+
+### Which ground it is on
+
+Only the tints move. The words take the ink around them either way, which is how a switcher reads on a bar of any ground.
+
+```tsx
+import { Icon, NavbarSwitcher } from '@deriv-com/dds-marketing'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// default — a light bar
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>}>{navbarswitcheroptions}</NavbarSwitcher>
+
+// inverse — a bar on a dark hero
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>} tone="inverse">{navbarswitcheroptions}</NavbarSwitcher>
+```
+
+### The mark that says it opens
+
+Off by default, because a switcher usually stands among destinations that each carry one and a third is repetition. The panel form draws one whatever this says.
+
+```tsx
+import { Icon, NavbarSwitcher } from '@deriv-com/dds-marketing'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// Without — among sections that have their own
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>}>{navbarswitcheroptions}</NavbarSwitcher>
+
+// With — standing on its own
+<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<Icon size="xs"><GlobeRegularIcon /></Icon>} chevron>{navbarswitcheroptions}</NavbarSwitcher>
+```

package/.llm/components/navbarswitcheroption.md

@@ -0,0 +1,156 @@
+<!-- GENERATED from navbar-switcher-option.contract.json. Do not edit. -->
+
+# NavbarSwitcherOption
+
+One choice inside a NavbarSwitcher: a language, a region, a theme. A button rather than a link — choosing one changes how the page is drawn or worded, which is not navigation and must not carry an href, a history entry or anything for the back button to undo.
+
+It says which one is current. That is the whole reason this is a component rather than a MenuItem: a set of choices where the one in force is not marked is a set a reader has to remember the answer to, and the mark has to be readable as well as coloured — `aria-current` carries it for a reader who cannot see the ink.
+
+## Use when
+
+- A NavbarSwitcher needs its choices
+- One of a set of options is in force and a reader should be able to see which
+
+## Do not use
+
+- The row goes somewhere → `NavbarItem`
+- The row is a command in a dropdown → `MenuItem`
+- Navigation of any kind
+- A destructive action. A set a reader scans and picks from is the wrong place for anything that cannot be undone by picking again
+
+## Anatomy
+
+NavbarSwitcherOption renders one element.
+
+- `root` — `<button>`, class `dds-navbarswitcheroption`. The choice. A `<button>`, because it acts on the page rather than leaving it.
+  
+  It takes the ink around it rather than naming one, except when it is the current choice. A switcher's page is drawn on whatever surface holds it — a panel, a menu — and a row that named a colour would be the one thing on that surface not answering to it.
+
+Apply these classes from the generated `navbarSwitcherOptionParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `text`
+- Never contains: `NavbarSwitcherOption`, `NavbarItem`, `NavbarMenu`, `Button`, `Link`, `DropdownMenu` — in children or in any prop that takes a node
+
+## Props
+
+### current — `boolean` (default `false`)
+
+Use when: This is the choice in force — the language the page is being read in. Exactly one of a set carries it
+Never for: Marking a recommended or default option. It says what is true now, not what a reader should pick
+
+### onSelect — `callback` **Required.**
+
+Use when: Always. Choosing is the whole of what this does, and a row that reported nothing would be a row that did nothing
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- Announced as: `button`
+- `Tab` — Reaches each choice in turn. There is no roving tabindex: a set of choices is a set of buttons, and a reader keeps the key they already have
+- `Enter` — Chooses, which a button does without anything being added
+- The current choice reports itself with aria-current, because colour alone does not reach a reader who cannot see it
+- A button rather than a link. Choosing a language changes how the page is drawn and goes nowhere: there is no href, no history entry and nothing for the back button to undo
+
+## Rules
+
+- **On a phone a section's actions stack and each fills the width, including when there is only one** — On a phone a page's actions stack, and each one fills the width. Not most of it, and not the width its label happens to need — the whole column.
+
+Two side by side is what this replaces. On the narrowest screen each gets half a column minus the gap, which is rarely enough for a real label: the words wrap inside the pills, the two buttons come out different heights, and the pair reads as a broken row rather than as a choice. Stacked, each has the whole width and neither has to shorten its words to fit.
+
+A single action fills too, and that is the part worth saying, because it is the one that looks unnecessary. A lone button has the room to sit at its natural width and still should not: a full-width control is the phone's convention for the thing the screen is asking you to do, and a pill hugging its label reads as one option among others that are not there. It also makes the target predictable — the whole width, wherever the thumb lands — which a centred pill does not.
+
+Filling is the row's job rather than the button's. A button has no width of its own and is not given one; the row it sits in becomes a column and stretches its children, so nothing about the control changes and the same button is full width here and its own size on a desktop.
+
+This is the phone's breakpoint, size.breakpoint.md, and not the wider one that decides whether a heading is centred. Those are different questions and they break at different widths: a heading stops being centred when the measure is the screen, while a button stops being full width much sooner than that — stretched across a tablet it is a long way from its own label, and a label centred in a metre of pill is harder to hit than one in a pill the size of the words.
+
+What this is not about is every row of controls. A set of filter chips, a pagination strip, a toolbar, a link sitting after a sentence — none of these is the page asking for something, and stacking them to full width would turn a strip the eye skims into a list it has to read. The test is whether the row is the call to action the section was written for.
+  Guidance only — cannot be checked automatically.
+- **Never nest one interactive element inside another** — Nested interactive elements produce ambiguous hit targets and an unreachable inner control for keyboard and screen-reader users. This is why the rule cannot live on any single component — it constrains Button, Link, Input and Switch simultaneously.
+  Guidance only — cannot be checked automatically.
+- **A section that paints a ground sets the ink to go with it** — A page sits on color.bg.page, and a section that separates itself from it takes one of three grounds. color.bg.subtle is the light one and needs nothing further — the page's own ink still reads on it. The other two are dark and do not: color.bg.brand-strong takes color.fg.on-brand-strong, and color.bg.brand takes color.fg.on-solid. Both are white, and both are written as the role rather than the white they resolve to. Set one of those backgrounds without its ink and the text inherits whatever the page was already using, which is near-black on a dark band — legible to nobody, and invisible to every check here, because each pair passes contrast on its own and nothing can tell whether a section used both.
+
+color.bg.brand carries a second limit that is not about forgetting. Its ink measures 3.39:1, which clears the 3:1 a heading needs and misses the 4.5:1 running copy needs. A coral band may carry a headline and a call to action; a paragraph on one is text the reader has to work through at a ratio the waiver on that role does not cover — the waiver says so itself. A section with copy in it takes color.bg.brand-strong, which is near-black and carries white at full contrast.
+
+color.bg.strong is not a section ground. It is the inverted fill for an action that has to outrank what surrounds it, and the components that paint it — Button and ButtonIcon in their inverse form — already set both halves in one rule, which is the pattern a hand-painted section has to copy.
+  Guidance only — cannot be checked automatically.
+- **Every gap inside a section names the relationship it expresses, and the same relationship keeps its measure when it turns on its side** — A section's spacing is named by the relationship it expresses, not chosen by size. Every gap in a section has a role token, and reaching for a step off the generic scale because it happens to be the right number is how two sections written by two people stop lining up: the numbers agree today and drift the first time one of them is tuned.
+
+The heading group is three steps, not one gap. An eyebrow sits nearer its title than the title sits to its description, and the actions sit further from the description than either — space.heading.eyebrow-title, space.heading.title-description, space.heading.description-actions, in that order. A single `gap` on the group cannot say this; it sets all three the same and the block reads as evenly spaced lines rather than as a mark, a name and a paragraph. The eyebrow has to identify itself for this to work, because a group that opens with a title must not give its description the eyebrow's tighter step.
+
+The step between a title and its description follows the size of the title, which is why there are two of it. What a reader sees is not the gap but the gap plus the leading above it, and leading scales with the type: under a display title the leading is most of the space, under a card's title it is half as deep. One value for both makes a card look loose at the size that made a section look right. So space.heading.title-description is the display step and space.heading.title-description-compact is the step at a card's size, and the choice is made by how big the title is rather than by what kind of block it sits in.
+
+Every one of those steps is smaller than the gap below the group, and that ordering is what holds the group together as one thing. space.heading.content is the step between a heading group and the content it introduces, and it is the widest measure inside a section: the one gap the eye reads as a change of subject rather than as a continuation.
+
+That step is the same whether the content is under the heading or beside it. A split is the same relationship turned on its side — a heading group and the content it introduces — so the space between the two halves is space.heading.content, not a gutter. When the split collapses to one column on a phone the gap becomes vertical again, which is where it started, and nothing has to change for that to be right.
+
+space.grid.gutter is between two things of the same kind. Two cards in a row are the same kind; the two halves of a split are not, which is why the gutter is the wrong measure there even when the number would have looked acceptable. The gutter runs on both axes, so a grid reads as an even field rather than as rows with a seam down them.
+
+space.inset.card is the card's, not the page's. A row of cards padded differently is a row of different cards, and the fill is the only edge they have. A page composing a row does not get to choose it.
+
+Column count is not a breakpoint decision. A row holds as many columns as fit before a column would be narrower than size.grid.column-min, and drops one when they would not. Written as a fixed count that collapses at a breakpoint, a four-up row keeps four columns at every width above the phone and sets its copy two or three words to a line through the whole of the tablet range — and on a narrow desktop, which no breakpoint sits on at all. The threshold is a property of the row rather than of a card: a card fills whatever cell it is given.
+
+What this does not cover is the space above and below a section, which is space.section.default and space.section.compact, and the page's own side margin, which is space.inset.page. Those are the section's outside; everything here is its inside.
+  Guidance only — cannot be checked automatically.
+- **A section's title is centred over stacked content, starts beside content in columns, and starts on a phone** — Two arrangements, and the title's alignment is decided by which one it is introducing rather than chosen per section.
+
+Content stacked under the title — a row of cards, an accordion, a set of steps — takes a centred title. The heading group and the block below it share one axis, so a centred title is symmetric with the thing it names, and the eye drops from the middle of the words to the middle of the set. A title starting at the left over a centred or full-width block reads as belonging to the first column rather than to all of them.
+
+Content beside the title — a split, a picture in the other half, anything laid out in columns — takes a title that starts where its content starts. The two share a left edge, and that edge is what says they are one thing read across rather than two stacked. Centring the title there breaks the only alignment the reader has to hold the halves together, and it drifts further from its content the wider the page gets.
+
+The heading group is what carries this, not the heading alone. An eyebrow, a title and a description are read as one block and align together; aligning the title without them leaves a centred heading over start-aligned copy, which reads as a mistake rather than as a choice.
+
+Centred means all of it, not just the words. A badge, a row of actions, a picture — these are flex children, and a flex child is placed by align-items rather than by text-align, so a block that only sets the text leaves everything that is not text at the start. A hero is the case that shows it: its title and copy centred while its badge and its buttons did not.
+
+A capped block centres itself as well as its words. A heading group takes size.heading-group.max, and a cap that is not centred leaves the measure at the start of the column with the words centred inside it — composed, and a long way left of the middle it appears to be in.
+
+Both arrangements go to the start on a phone. A centred block reverts below the breakpoint, and the reason is the measure: on a phone the measure is the screen, so a centred title wraps to three or four ragged lines and the eye loses the left edge it was tracking — the same symmetry that reads as composure on a desktop is what makes it hard to scan on a phone. Centring there has to be asked for twice, and a section title is not one of the things that asks: it is centred because there is room for it, and on a phone there is not. Going back to the start means all of it too, and a capped block is the one that hides a leftover: its words go to the start while its measure stays in the middle of the column, which reads as a title still centred over a badge and buttons that are not — the box in the middle and the line inside it at the edge.
+
+A hero is a section like any other: its badge, title, copy and actions are one stacked block, so it is centred on a desktop and starts on a phone with everything else.
+
+What this is not about is a page whose body is a form or a document. A title over a sign-up form or a guide is not introducing a set of content — it is the first line of the thing itself, and it keeps the alignment the body has, which for running text is the start. The distinction is whether the block below is content the title names or content the title is part of.
+  Guidance only — cannot be checked automatically.
+- **Anything a pointer has to hit is at least 24px in both directions** — A control sized by its contents is as big as its contents, and a glyph is chosen for how it reads rather than for how easily it is hit. An icon-only button with no padding is a 16px target — smaller than the pad of a finger, and smaller than the tremor of a hand using a mouse.
+
+WCAG 2.2 asks for 24 by 24 CSS pixels at AA. The exceptions are narrower than they look: inline targets inside a sentence are exempt, and so is a small target with 24px of clear space around it — but a clear button sits against the field it empties, and a field is itself a target, so the spacing exemption does not apply to the case that keeps arising.
+
+The target and the mark are separate decisions, and conflating them is what produces both faults. Growing the glyph to 24px makes it shout; leaving the button at 16px makes it hard to hit. So the glyph keeps the size that reads correctly beside its text, and the box around it declares a minimum of its own — which is what size.target.min is for.
+
+Declared rather than emergent. Padding plus contents does clear 24px in several components today, and it is the weaker statement: it is a size nobody wrote down, so it moves when the type scale or the glyph does, and nothing says it was meant to be a target at all.
+  Guidance only — cannot be checked automatically.
+
+## Anti-examples
+
+❌ NavbarSwitcherOption for: The row goes somewhere
+   A destination is a link and belongs in the navigation landmark. A choice is a control that changes the page a reader is already on
+   → use `NavbarItem` instead.
+
+❌ NavbarSwitcherOption for: The row is a command in a dropdown
+   MenuItem is DropdownMenu's row and carries no notion of one of them being current, which is the thing a switcher is for
+   → use `MenuItem` instead.
+
+## Example
+
+```tsx
+import { NavbarSwitcherOption } from '@deriv-com/dds-marketing'
+
+<NavbarSwitcherOption onSelect={() => { /* your handler */ }} current>English</NavbarSwitcherOption>
+```
+
+## In use
+
+### Which one is in force
+
+Exactly one of a set carries it. The ink says so to a reader who can see it and aria-current says so to one who cannot, which is why this is a component rather than a MenuItem.
+
+```tsx
+import { NavbarSwitcherOption } from '@deriv-com/dds-marketing'
+
+// The choice in force
+<NavbarSwitcherOption onSelect={() => { /* your handler */ }} current>English</NavbarSwitcherOption>
+
+// One of the others
+<NavbarSwitcherOption onSelect={() => { /* your handler */ }}>Français</NavbarSwitcherOption>
+```