@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/navbarmenugroup.md

@@ -0,0 +1,184 @@
+<!-- GENERATED from navbar-menu-group.contract.json. Do not edit. -->
+
+# NavbarMenuGroup
+
+A named handful of destinations inside a section's panel: a word over a short list, so a reader scanning a panel of twenty links is reading four sets of five rather than twenty of anything.
+
+The word is the whole point and it is not a heading. A panel opens inside a navigation landmark on a page that already has its own outline, and a heading element here would insert a level into that outline for something the reader never sees in the document — so what this draws is a label, and what it gives assistive technology is a named group. The two say the same thing by different means, which is the arrangement a panel like this has to reach for.
+
+It holds destinations and nothing else. A group with a control in it is a set of places with an action hidden among them, which is the one thing a reader scanning for somewhere to go will not be looking for.
+
+## Use when
+
+- A section's panel holds more destinations than a reader takes in at once, and they fall into sets — markets, tools, payments
+- Two lists in a panel would be told apart by nothing if the words above them were taken away
+
+## Do not use
+
+- The panel holds few enough destinations that naming sets would be naming one thing each → `NavbarItem`
+- The set is a section of the site rather than a set within one → `NavbarMenu`
+- A single destination dressed as a set. The label would be doing the item's job and the item would be saying nothing the label had not
+- Controls. Everything in a group goes somewhere — a switch or a button among a column of links is an action a reader scanning for a place will not expect to find
+- A heading in the page's outline. Nothing here is an h-element: the panel is navigation furniture, and a level inserted for it would be a step in the document's structure that the document never shows
+- Anywhere outside a menu's panel. There is no bar arrangement this fits — the row holds names, and a name with a list under it is what the panel is for
+
+## Anatomy
+
+NavbarMenuGroup renders 3 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-navbarmenugroup`. The set: a label and the destinations under it, as one column. `role="group"` named by the label, which is what gives a reader who cannot see the word the same grouping a reader who can gets for free.
+  
+  It does not take the panel's whole width. A panel lays its groups out in columns and this is one of them, so what decides its measure is the panel rather than anything here.
+  
+  It is not split across a column break, and it carries the space beneath it rather than taking it from a gap. Both follow from the panel laying its sets out in columns rather than a grid: a column break through the middle of a set would leave a label at the foot of one column and its destinations at the head of the next, and multi-column has no row gap to separate one set from the next in the same column — the distance has to belong to the set.
+- `label` — `<div>`, class `dds-navbarmenugroup__label`. The word over the list. Quieter than what it names — `color.fg.muted` against the items' inherited ink — because it is a signpost rather than a destination, and a label as loud as the links beside it reads as one more place to go.
+  
+  A `<div>` and not a heading. It is the group's accessible name through `aria-labelledby`, so nothing is lost by it having no level; what would be lost by giving it one is the page's own outline, which would gain a step for a word that only exists while a panel is open.
+  
+  It carries no inset of its own, which is what puts it on the same left edge as the destinations under it. It had one while those were NavbarItems, whose own padding it was matching; a `list` Link has none, so the same inset became an indent on the heading alone.
+- `list` — `<div>`, class `dds-navbarmenugroup__list`. The destinations, stacked. A column with a tighter step between its rows than sits between the label and the list, which is in turn tighter than the panel puts between its groups. Three steps narrowing inwards is what makes a set read as a set: the space inside has to be smaller than the space around it, or two columns become one list of alternating words.
+  
+  The rows take `space.gap.sm` and the label takes `space.gap.md` above them, which is the pair moving rather than one of them. The rows were a step tighter and the label sat where the rows now are — opening the rows alone would have put the same distance between a label and its first destination as between two destinations, and the heading would have read as one more row.
+  
+  What goes in it is Links in their `list` variant, not NavbarItems. Link's own guidance names this exact case — a set of related pages under a heading — and the variant exists because a column of coral is a column nobody reads. NavbarItem is the other thing: a pill, a target floor and a mark for the section the reader is in, all of which are furniture for a row scanned across rather than a column read down, and none of which a panel's rows have any use for.
+  
+  The destinations sit `space.gap.md` apart, which is the same step that separates them from the word naming the set. That reads as even rather than flat: each row is a line of `font.body.sm` on a leading of one and a half, so the box is half as tall again as its words and the gap is the smaller half of what a reader actually sees between one name and the next. At the step below it the rows crowded — a column of seven markets read as a block of text rather than as seven things to choose from.
+
+Apply these classes from the generated `navbarMenuGroupParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `Link`
+- Never contains: `Navbar`, `NavbarMenu`, `NavbarMenuGroup`, `NavbarPanel`, `NavbarItem`, `Button`, `Card` — in children or in any prop that takes a node
+- Holds at least 2
+
+## Props
+
+### label — `string` **Required.**
+
+Use when: Always — it is the word over the list and the group's accessible name. Name what the set is rather than what to do with it: 'Markets', not 'Browse markets'
+Never for: A sentence. This is a signpost over five links, and a label that needs a verb is a label describing something that should have been a destination of its own
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## 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: `group`
+- `Tab` — Reaches each destination in turn. A group is a name around a set rather than a widget, so nothing here takes focus of its own and no key is added to the ones a reader already has.
+- accessible name from label, carried by aria-labelledby rather than a repeated string, so the word a reader sees and the name a reader hears cannot come apart
+- The label is not a heading element. The panel is navigation furniture inside a page that has its own outline, and a level inserted here would be a step in that outline for a word which exists only while a panel is open.
+- The group takes no focus of its own. Focus belongs to the destinations inside it, which are anchors and are reached with the key the reader already has.
+
+## 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
+
+❌ NavbarMenuGroup for: The panel holds few enough destinations that naming sets would be naming one thing each
+   A group of one is a heading with a link under it, and a panel of those is a list with words interleaved. Put the items straight into the menu
+   → use `NavbarItem` instead.
+
+❌ NavbarMenuGroup for: The set is a section of the site rather than a set within one
+   A menu is a name in the bar that opens; this is a name inside what opened. Nesting one of these in place of the other gives a reader a panel that opens a panel
+   → use `NavbarMenu` instead.
+
+## Example
+
+```tsx
+import { NavbarMenuGroup, Link } from '@deriv-com/dds-marketing'
+
+<NavbarMenuGroup label="Markets">
+  <Link href="/forex" variant="list">Forex</Link>
+  <Link href="/stocks" variant="list">Stocks</Link>
+  <Link href="/commodities" variant="list">Commodities</Link>
+</NavbarMenuGroup>
+```
+
+## In use
+
+### A word over a short list
+
+The label is quieter than what it names — a signpost rather than a destination. It is the group's accessible name too, so nothing is lost by its not being a heading.
+
+```tsx
+import { Link, NavbarMenuGroup } from '@deriv-com/dds-marketing'
+
+// A set of markets
+<NavbarMenuGroup label="Markets">
+  <Link href="/forex" variant="list">Forex</Link>
+  <Link href="/stocks" variant="list">Stocks</Link>
+  <Link href="/commodities" variant="list">Commodities</Link>
+</NavbarMenuGroup>
+
+// A shorter set beside it
+<NavbarMenuGroup label="Trade">
+  <Link href="/cfds" variant="list">CFDs</Link>
+  <Link href="/options" variant="list">Options</Link>
+</NavbarMenuGroup>
+```

package/.llm/components/navbarpanel.md

@@ -0,0 +1,255 @@
+<!-- GENERATED from navbar-panel.contract.json. Do not edit. -->
+
+# NavbarPanel
+
+The whole of a site's navigation at a width the bar cannot hold it: the mark and a way out across the top, the destinations down the middle, whatever the site wants across the foot.
+
+It is a surface that covers the page, and three things follow from that which nothing about its appearance suggests — focus is held inside it, Escape closes it, and the document beneath holds still. Those are why it is a component rather than a stretch of markup a page writes, and they live in a hook beside it that a site building its own covering surface can reach for.
+
+Navbar draws it. A page composes a bar, and the bar is the thing that knows at which width its ends stopped fitting — so a page rendering this itself would be wiring an open state to a threshold it cannot see. It is contracted separately because it is a separate thing to judge, not because it is a separate thing to assemble.
+
+## Use when
+
+- Navbar is collapsing and its destinations have to go somewhere. This is where, and the bar puts them here without being asked
+- The same navigation has to be read down a phone rather than across a page
+
+## Do not use
+
+- The surface is a sheet rising from the foot of the page rather than the site's navigation → `BottomSheet`
+- What is wanted is a list that opens beside the control that opened it → `DropdownMenu`
+- A dialog. This is navigation drawn differently, not a question the reader has to answer — it takes no decision, returns no value, and closing it cancels nothing
+- A page of its own. The destinations here go somewhere; a surface a reader stays on and reads is a page, and this one is covering it
+- A wide screen. Everything in it is already drawn across the bar at that width, and a reader who opens it there is being shown the navigation twice
+- Anything a page opens itself. Navbar renders this, holds whether it is open, and is the thing that knows when the bar stopped fitting
+
+## Anatomy
+
+NavbarPanel renders 8 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-navbarpanel`. The surface, covering the page. `position: fixed` with `inset: 0`, which covers rather than pushes down — a panel that displaced the document would scroll the reader's position out from under them at the moment they were trying to leave, and put it back somewhere else when they closed it.
+  
+  It paints an opaque ground rather than a scrim over a visible page. A translucent navigation panel is a list of destinations read against whatever the page happened to have behind it, which is the one thing every word here has to stay legible against.
+  
+  A column: the header holds its height, the body takes what is left and scrolls, the foot holds its own. That rather than a stack that scrolls as one, because a site with enough sections overruns a phone and a panel whose header scrolled away would take the exit with it.
+  
+  The two block edges take different steps, which is the one place this surface is not symmetric. The top is set so the mark lands where the bar was already drawing it: this step plus the header's own is the bar's single step, and the panel opens over the bar — a mark that shifted as it appeared would read as the logo jumping rather than as a panel arriving. The two sides say it differently because the bar's ground has to cover its air and the panel's does not, which is why this is stated as an invariant about where the mark lands rather than as one number copied into two files. The foot answers to something else — the actions across it are the last thing a reader meets, and they need room under them rather than the measure the top happens to need.
+  
+  The column's own gap is the small step, not a large one, because it is never the whole distance between two regions — each already insets itself, so the body's own `space.inset.sm` and the foot's `space.inset.md` are added to it. Set at the large step the header sat a clear forty pixels off the first destination, which reads as a missing row rather than as a separation.
+  
+  It is paper at every tone, including under a bar that is not. An inverse bar is inverse because the section beneath it painted itself dark and the bar is standing on that section — but this covers the page rather than standing on it, so there is no dark ground here to answer to, only the one this surface chooses. It had a tone briefly and it was wrong for the same reason the scrolled bar's was: a treatment that belongs to a ground, carried somewhere the ground is not.
+  
+  What the page passes still comes out right without being passed twice. The foot holds the bar's own utilities, and a secondary action taking Button's `tone="inherit"` reads the ink of whatever surface it lands on — white against the bar, near-black here.
+- `header` — `<div>`, class `dds-navbarpanel__header`. The top: the mark at one end, the way out at the other. The mark is repeated here rather than the panel being drawn beneath the bar, because a panel covering the page has covered the bar too — and a reader who has lost the mark has lost the one thing telling them whose site they are still on.
+  
+  Its height is the bar's row, and stated the same way: `size.control.md`, a control's height, under the same `space.inset.xs` the bar's row takes above it. Both reserve a control because both hold one — the bar keeps an action beside the trigger, this keeps the way out — and a row sized by whatever happens to be in it would put the mark at one height here and another there. Two tokens rather than one measure that happens to equal their sum, so retuning either moves both halves together.
+  
+  Its height is what the bar's row leaves inside itself: the bar reserves `size.bar.height` and spends `space.inset.xs` of it on air at each edge, so what is left for the mark to centre in is `size.control.md` — which is what this reserves. The two are one measure arrived at from opposite ends, and they have to meet exactly: the panel opens over the bar, and a mark that shifted as it appeared would read as the logo jumping rather than as a panel arriving.
+- `mark` — `<div>`, class `dds-navbarpanel__mark`. The site's mark, as the bar carries it. It follows what the bar was given rather than being asked for again: a panel showing a different mark from the bar it opened out of would be a different site.
+  
+  It is the same height the bar draws the mark at, and says so rather than inheriting it. The two are different elements in different components — the panel covers the bar rather than containing it — so a size set in one reaches the other through nothing at all. Left unsaid, the mark was whatever measure the page happened to hand over, and grew the moment the panel opened over a bar that had just drawn it smaller. Rendered only when `brand` is set.
+- `close` — `<button>`, class `dds-navbarpanel__close`. The way out, and the only one a reader can see. A control of its own rather than the bar's trigger moved: the trigger is in the bar, the bar is underneath this, and a reader reaching past a covering surface to press the thing it covers is not an exit anybody finds.
+  
+  `size.target.min` in both directions, with more at stake than anywhere else in this family — Escape works too and cannot be seen, so this is the whole of the visible answer to how a reader gets their page back.
+  
+  No hover fill, matching the trigger that opened this. The two are one control as the reader meets them — pressed in the same place, one after the other — and a fill appearing under the pointer on only the second would read as the panel answering differently from the bar. The focus ring stays: it answers to a reader with no pointer to hover with, and this is the way out of a surface covering the page.
+  
+  It takes the panel's ink rather than the browser's. A `<button>` does not inherit `color`, and an inverse panel paints a dark ground — so the way out of a surface covering the page would be drawn in near-black on it.
+  
+  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.
+- `body` — `<div>`, class `dds-navbarpanel__body`. The scrolling region, and everything a reader goes to or sets.
+  
+  It is the only thing here that scrolls. The exit at the top and whatever the site wants at the foot hold their places, because those are the two things a reader should never have to scroll to find.
+  
+  It holds two children rather than being the landmark itself, which it was. A switcher is not a destination — announcing a language picker inside a navigation landmark tells a reader it is somewhere to go — so the destinations keep the `<nav>` and what a reader sets sits beside it, under it, outside it.
+  
+  It is the positioning context for a switcher that opens a page of its own. That page covers the destinations and the switchers and stops at the header, which is what keeps the mark and the way out on screen while a reader is two levels in.
+- `destinations` — `<nav>`, class `dds-navbarpanel__destinations`. The destinations, down the panel rather than across the bar — the same ones the bar holds, because a page writes its navigation once and what changes with the width is how it is drawn.
+  
+  It is the `<nav>` here, and the bar's is not rendered at this width, so there is one navigation landmark on the page rather than two claiming the same set. It carries its own name for the same reason.
+- `preferences` — `<div>`, class `dds-navbarpanel__preferences`. What a reader sets, under the destinations and outside the landmark.
+  
+  Under them because that is the order of the questions: where am I going, and then how would I like it — a switcher above the places the site has would be the first thing offered to somebody who opened a menu to leave the page.
+  
+  Outside the landmark for the reason the bar keeps them out of its own: a language is not a place. And out of the foot, which is where they were: the foot is for the one thing the site wants pressed, and a preference sitting in it competes with that for the last word.
+  
+  It is not set apart. The switchers follow the destinations at the same step the destinations keep between themselves, so the panel reads as one list of rows rather than two blocks with a division between them. They were separated by an inset of their own, and the gap said something the design does not mean: that a reader had finished one thing and was starting another. What makes a switcher different from a destination is the mark on it and what happens when it is pressed, not a band of empty space. Rendered only when `preferences` is set.
+- `footer` — `<div>`, class `dds-navbarpanel__footer`. What the site wants, across the foot at full width — the conversion, and the language or theme controls that sat at the far end of the bar. Pinned rather than last in the scroll: none of it should be something a reader reaches the bottom of a list of sections to find.
+  
+  Stacked rather than side by side. A phone has room for one control across its width, and two of them beside each other are two half-width controls — the shape that makes the quieter of a pair look squeezed in rather than deliberately quieter. Rendered only when `footer` is set.
+
+Apply these classes from the generated `navbarPanelParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `NavbarItem`, `NavbarMenu`
+- Never contains: `Navbar`, `NavbarPanel`, `BottomSheet`, `Table`, `Card` — in children or in any prop that takes a node
+
+## Props
+
+### label — `string` **Required.**
+
+Use when: Always — it names the navigation landmark inside the panel, and this is the only one on the page while the panel is open. Name the set rather than the act: 'Main', not 'Main navigation', because the role already supplies the word
+Never for: A heading for the panel. Nothing draws this. The mark at the top says whose site it is and the destinations say what it holds
+
+### closeLabel — `string` **Required.**
+
+Use when: Always — it names the close button, which draws a glyph and no text and is the only visible way out of a surface covering the whole page. 'Close' is enough; what it closes is the only thing open
+Never for: The bar's trigger name. They are two controls in two places, and a reader cannot reach the trigger while this is covering it
+
+### onClose — `callback` **Required.**
+
+Use when: Always. It is called by the close button and by Escape, so whatever holds the panel open hears both ways it can be dismissed
+Never for: Navigation. A reader pressing a destination inside the panel is leaving by a different door, and a handler that also routed would fire twice for one press
+
+### brand — `node`
+
+Use when: Whatever the bar carries as its mark, passed straight through. Absent only where the bar has none either
+Never for: A different mark from the bar's. The panel opened out of the bar and covers it; two marks is two sites
+
+### preferences — `node`
+
+Accepts: NavbarSwitcher, ButtonIcon
+Use when: The bar has switchers, which it hands over when it collapses. They are drawn under the destinations and above the foot
+Never for: The action the site wants pressed. That is the foot's, and a preference drawn beside it would compete with the last thing the panel says
+
+### footer — `node`
+
+Accepts: Button, ButtonIcon
+Use when: The bar's utility end has something worth keeping at this width — the conversion, and the language or theme controls. They are drawn across the foot here rather than in a row, because there is width for one control and no room for three
+Never for: Destinations. Anything that goes to a section of the site belongs in the children, inside the landmark that announces it as one
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Behaviour
+
+A surface covering the page owes the reader three things no contract can state: focus held inside it while it is open, Escape closing it, and the document beneath not scrolling. They begin and end at the same moment, which is why they are one hook rather than three — separating them is how one of them gets forgotten. Exported, so a site building its own covering surface reaches for this rather than writing a fourth version with a different set of mistakes in it.
+
+- `useNavbarPanel`
+
+All from `@deriv-com/dds-marketing`, the same import as the component.
+
+## 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.
+
+- `Tab` — Cycles inside the panel and does not leave it. A reader tabbing past the last control comes back to the first rather than into a page they cannot see — which is what a surface covering the page owes anybody who cannot see that it is covering it.
+- `Escape` — Closes the panel and returns focus to whatever opened it. The way out that does not have to be seen, which is why the close button must not be the only one.
+- accessible name from label on the navigation landmark inside the panel, which is the only one on the page while this is open
+- accessible name from closeLabel on the close button, which draws a glyph and no text
+- Focus is held inside the panel while it is open, and returns to what opened it when it closes. A surface covering the whole page that lets focus walk out behind it has put the reader somewhere they can neither see nor get back from.
+- The document beneath does not scroll while the panel is open. A covering surface that let the page move under it returns the reader somewhere else when they close it.
+- The ground is opaque. A translucent navigation panel is a list of destinations read against whatever the page had behind it, and nothing here can know what that was.
+- The bar's own navigation landmark is not rendered at the widths this is. Two landmarks naming the same set of destinations tells a reader the site has two navigations, and the one they cannot see is the one they will be offered first.
+
+## 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
+
+❌ NavbarPanel for: The surface is a sheet rising from the foot of the page rather than the site's navigation
+   A sheet claims part of a small screen and says how much by how far it rises; this claims all of it and holds a fixed arrangement — a mark, a scrolling middle, and a foot. A sheet is also opened by the page about anything at all, where this is opened by a bar about one thing
+   → use `BottomSheet` instead.
+
+❌ NavbarPanel for: What is wanted is a list that opens beside the control that opened it
+   → use `DropdownMenu` instead.
+
+## Example
+
+```tsx
+import { NavbarPanel, NavbarItem, Button } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+<NavbarPanel onClose={() => { /* your handler */ }} label="Main" closeLabel="Close" brand={<DerivCoralWordmark />} footer={<Button size="md" href="/signup">Open account</Button>}>
+  <NavbarItem href="/trading">Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+  <NavbarItem href="/about">About</NavbarItem>
+</NavbarPanel>
+```
+
+## In use
+
+### The whole of the navigation
+
+Mark and exit across the top, destinations down the middle, what the site wants across the foot. Only the middle scrolls — the other two are what a reader should never hunt for.
+
+```tsx
+import { Button, NavbarItem, NavbarPanel } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// With a conversion at the foot
+<NavbarPanel onClose={() => { /* your handler */ }} label="Main" closeLabel="Close" brand={<DerivCoralWordmark />} footer={<Button size="md" href="/signup">Open account</Button>}>
+  <NavbarItem href="/trading" current>Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+  <NavbarItem href="/about">About</NavbarItem>
+</NavbarPanel>
+
+// Navigation only
+<NavbarPanel onClose={() => { /* your handler */ }} label="Main" closeLabel="Close" brand={<DerivCoralWordmark />}>
+  <NavbarItem href="/trading">Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+</NavbarPanel>
+```