@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/navbaritem.md

@@ -0,0 +1,238 @@
+<!-- GENERATED from navbar-item.contract.json. Do not edit. -->
+
+# NavbarItem
+
+One place the site has, in the bar across the top of it. An anchor with a target around it, a mark for the section the reader is currently in, and nothing else.
+
+It exists rather than a Link being reused because a destination in a navigation bar carries something a Link cannot: which one the reader is on. That is `aria-current`, a target big enough to hit, and a resting shape the current one fills in — none of which belongs on the component a page also uses in the middle of a sentence. A Link is prose that leads somewhere; this is furniture.
+
+It takes no colour of its own. The bar sets the ink once and everything in it inherits, so what this declares is the ground under the words — and even that has to be told which way round it is, because an item cannot see the bar it is in.
+
+## Use when
+
+- A section of the site, in a Navbar — the ordinary case and what this is for
+- A destination that leaves the site, which it marks as a change of context rather than leaving the reader to find out
+- The same destination inside the panel a narrow bar collapses into: a page writes its navigation once, and what changes with the width is how it is drawn
+
+## Do not use
+
+- The destination opens a panel of further destinations rather than going somewhere → `NavbarMenu`
+- The destination is a phrase inside a sentence, or a call to action beneath a paragraph → `Link`
+- The item is one of a set of alternatives rather than a place → `Tab`
+- A control. This navigates and nothing else — a press that filtered, submitted or opened something would be a button the browser has been told is a link
+- The site's mark. That goes in Navbar's brand slot, where nothing gives it a target or a current state
+- A conversion action. Open an account is not a place the site has, and a reader tabbing the navigation landmark should not meet it there — that is Navbar's utilities slot
+- A list of every page on the site. A bar holds the sections a reader chooses between at a glance; a sitemap is a footer
+
+## Anatomy
+
+NavbarItem renders 4 elements. A token binding names the part it applies to.
+
+- `root` — `<a>`, class `dds-navbaritem`. The destination, and the target around it. An `<a>` with an href always — including the one the reader is currently on, which is where this parts company with BreadcrumbItem. A trail marks where you have been and its last step is not a link because it goes nowhere new; a bar is a set of places you move between, and the section you are in is one you can return to the top of.
+  
+  It takes no colour of its own and inherits the bar's — which has to be said rather than assumed. `color` is an inherited property and an anchor is the exception: every browser's own stylesheet paints one link-blue, so a component that simply declined to set a colour got the UA's instead of the bar's. `color: inherit` is what makes the sentence above true. What it does declare is the ground under the words: nothing at rest, a tint under the pointer, and a filled shape for the current one.
+  
+  `size.control.md` in the block axis, declared rather than emergent. It is a control's height rather than the bare target floor because it sits inside a pill one step above it, and the two insets either side are what make up the difference. Well clear of `size.target.min` either way, which is the floor that actually has to hold. The padding either side of a short word clears it comfortably today and would not survive a tighter type step, and a target nobody wrote down is one that moves when the scale does.
+  
+  `position: relative`, for the one thing it holds that is not drawn: an external destination's warning in words, clipped out of the page. That recipe is absolutely positioned, so without a positioned ancestor it takes the document as its containing block and adds its offset to the bottom of a long landing page.
+  
+  It reserves `size.control.lg`, the same height the bar's actions take. A destination is words and a button is a filled shape, so they are never the same object — but they stand in one row, and a row whose items are two heights reads as two rows that failed to line up.
+  
+  It pads its words by `space.inset.md`. With no gap between the destinations — the row sets none, so their targets touch and a pointer crossing from one to the next is never over neither — this inset is the whole of the space a reader sees between two names, twice over. It is the spacing decision for the row, not a detail of one item.
+- `icon` — `<span>`, class `dds-navbaritem__icon`. A mark before the words, for a bar that uses them. Optional and uncommon: a marketing site's sections are named in words a reader reads, and a glyph beside every one of them costs width the destinations need.
+  
+  It paints nothing. The glyph inside takes `currentColor`, which is the ink the bar set — so it turns over with the words rather than being the one thing left behind. Rendered only when `icon` is set.
+- `label` — `<span>`, class `dds-navbaritem__label`. The name of the place. A span of its own rather than bare text in the anchor, because the trailing mark on an external destination has to sit beside the words rather than inside them — and because a part is what a stylesheet can reach.
+  
+  It does not wrap. A destination broken across two lines makes the bar taller than every page below it has made room for, and the answer when the words stop fitting is the bar collapsing rather than the words folding.
+  
+  It is set at `font.label.sm`, which is the fourteen-pixel step. That is a deliberate divergence worth naming: `font.label.md` is the role whose own description lists navigation links among what it is for, and this does not take it. A bar holds five or six destinations between a mark and a pair of controls, and at the sixteen-pixel step they crowd the row before the bar reaches the width it collapses at. The role's description is the thing to correct if fourteen is right for every bar rather than this one.
+- `external` — `<span>`, class `dds-navbaritem__external`. The mark that says this one leaves the site — the only thing here a reader can see that the href does not already tell them. A change of context nobody was warned about reads as the site losing them.
+  
+  It is decoration and is hidden from assistive technology. What it stands for is said in words by the anchor's own accessible name, which the implementation extends rather than leaving to a glyph nobody can hear. Rendered only when `external` is set.
+
+Apply these classes from the generated `navbarItemParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `text`
+- Never contains: `Navbar`, `NavbarItem`, `NavbarMenu`, `Button`, `Link`, `Card`, `DropdownMenu` — in children or in any prop that takes a node
+
+## Props
+
+### current — `boolean` (default `false`)
+
+Use when: The reader is in this section of the site. It fills the item's shape in and sets `aria-current="page"`, so the mark is not the only thing saying it. At most one item in a bar carries it — a set with two has told the reader they are in two places
+Never for: Emphasis. This is not the important destination or the one the site would rather you took; it is the one the reader is already on, and using it for anything else makes the mark mean nothing on every bar that uses it correctly
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The bar has a light ground under it, which is every bar on a marketing page today. The tints here are ink-based and read against paper
+- `inverse` — The bar sits on a dark ground — a band, or art the page put behind it — and the ink runs light. The tints mirror: paper-based rather than ink-based, so a hover is visible instead of disappearing into the dark
+
+### href — `string` **Required.**
+
+Use when: Always. This is a place, and a place has an address — an item with no href is a control drawn as a link, which is the one thing its intent says it is not
+Never for: A fragment standing in for behaviour. `href="#"` is how a link that does nothing gets written, and it navigates: the reader loses their scroll position and gains a history entry for a press meant to do something else
+
+### icon — `node`
+
+Accepts: Icon
+Use when: The bar's sections are quicker to tell apart by a mark than by reading them, which is rare on a marketing site and usual in an application
+Never for: Decoration on every item. A glyph beside each of five destinations costs the width the destinations need and tells a reader nothing they were not already reading
+
+### external — `boolean` (default `false`)
+
+Use when: The destination leaves the site. It draws the mark, opens in a new context, and the implementation extends the accessible name to say so in words — a glyph alone is a warning only sighted readers get
+Never for: A different area of the same site. A subdomain the reader experiences as one place is not a change of context, and marking it as one teaches them to ignore the mark where it matters
+
+Also accepts everything from `AnchorHTMLAttributes<HTMLAnchorElement>`.
+
+## 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: `link`
+- `Tab` — Reaches the item, which is an anchor and needs nothing added to be a tab stop. There is no roving tabindex here and no arrow keys: a bar is a set of links rather than a composite widget, and a reader keeps the key they already have.
+- accessible name from the words inside it, which is what a reader hears and what a page writes anyway. Nothing here draws a label a reader cannot see
+- the section the reader is in marked with aria-current="page", so the fill is not the only thing saying it. Not verified here: the generated assertions compare an ARIA attribute against "true", and this one carries "page"
+- The current item keeps its href and its place in the tab order. A reader who lands on it should hear which section they are in, and following it is a harmless return to the top of that section rather than a dead end.
+- An external destination says so in words as well as with the mark. The glyph is hidden from assistive technology, so the anchor's own accessible name carries it — a change of context announced only to readers who can see a glyph is one the rest are not told about.
+- The item takes no colour of its own and inherits the bar's, which is what lets a bar on a dark ground turn its whole contents over in one declaration.
+- tone is the page's to set and the item cannot check it. An item cannot see the ground it is on, so an inverse tone on a light bar is a paper tint on paper — a hover nobody can see, and a failure no check here will catch.
+
+## 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
+
+❌ NavbarItem for: The destination opens a panel of further destinations rather than going somewhere
+   This navigates on press and says so to the browser, the back button and every assistive technology. A trigger that opened something while claiming to be a link is the one shape both of them are wrong about
+   → use `NavbarMenu` instead.
+
+❌ NavbarItem for: The destination is a phrase inside a sentence, or a call to action beneath a paragraph
+   A Link is sized, coloured and underlined to sit in running text. This has a target, a resting shape and a way of saying the reader is already there, all of which read as a stray highlight in the middle of a paragraph
+   → use `Link` instead.
+
+❌ NavbarItem for: The item is one of a set of alternatives rather than a place
+   A tab changes what is showing on the page the reader is already on and carries no href at all. Drawing a comparison as navigation tells a reader the page is about to change under them, and the back button will disagree
+   → use `Tab` instead.
+
+❌ current=true + external=true
+   The section the reader is in, and a destination that leaves the site. A bar cannot be saying both: aria-current="page" claims this is the page being viewed, while external says the target is somewhere the site does not control
+
+## Example
+
+```tsx
+import { NavbarItem } from '@deriv-com/dds-marketing'
+
+<NavbarItem href="/trading">Trading</NavbarItem>
+```
+
+## In use
+
+### Where the reader is
+
+One item in a bar carries current. It fills the shape in and sets aria-current="page", so the mark is not the only thing saying it — and it keeps its href.
+
+```tsx
+import { NavbarItem } from '@deriv-com/dds-marketing'
+
+// A section the reader is not in
+<NavbarItem href="/platforms">Platforms</NavbarItem>
+
+// The section the reader is in
+<NavbarItem href="/trading" current>Trading</NavbarItem>
+```
+
+### Leaving the site
+
+A destination that opens elsewhere is a change of context. The mark says so to anyone who can see it; the accessible name says so to everyone else.
+
+```tsx
+import { NavbarItem } from '@deriv-com/dds-marketing'
+
+// Stays on the site
+<NavbarItem href="/about">About</NavbarItem>
+
+// Opens elsewhere, and says so
+<NavbarItem href="https://partners.example.com" external>Partners</NavbarItem>
+```
+
+### Which ground it is on
+
+The item takes no colour of its own. tone sets the tint under the pointer — ink-based on a light bar, paper-based on a dark one — and the page has to say which.
+
+```tsx
+import { NavbarItem } from '@deriv-com/dds-marketing'
+
+// default — a light bar
+<NavbarItem href="/trading">Trading</NavbarItem>
+
+// inverse — a bar on a dark ground
+<NavbarItem href="/trading" tone="inverse">Trading</NavbarItem>
+```

package/.llm/components/navbarmenu.md

@@ -0,0 +1,319 @@
+<!-- GENERATED from navbar-menu.contract.json. Do not edit. -->
+
+# NavbarMenu
+
+A destination in the bar that opens rather than goes: a named trigger, and a wide panel beneath it holding the section's own destinations in columns, usually with something promotional beside them.
+
+It is a button and not a link, which is the whole of why it is a component rather than a NavbarItem with extra parts. Pressing it reveals something on the page the reader is already on — no navigation, no history entry, and the back button has nothing to undo. An item that opened a panel while claiming to be a link would be wrong to the browser, to the back button and to every assistive technology at once.
+
+What goes in the panel is the page's. A section of a marketing site is a set of groups a reader scans, and the grouping, the headings and the promotional card are written by the site rather than enumerated by this system — so this declares the trigger, the surface it opens and the arrangement of that surface, and makes no claim about what is arranged.
+
+Wide rather than beside. A dropdown that opened at the trigger's own width would put five columns into the space one word occupies; this one is measured against the bar and holds what a section actually contains.
+
+## Use when
+
+- A section of the site has enough inside it that naming the section is not enough — Trading holding markets, platforms and tools, rather than one page called Trading
+- The destinations under a section are worth grouping, and the groups are worth heading
+- The section has something the site wants shown alongside its links: a promotion, a feature, a piece of art
+
+## Do not use
+
+- The destination is a single place → `NavbarItem`
+- What opens is a single column of choices rather than a section of the site → `DropdownMenu`
+- A control. Nothing here submits, filters or changes what the page is showing other than by revealing its own panel
+- A destination of its own. The trigger is a button and goes nowhere — a section that is also a page needs its own NavbarItem inside the panel, where a reader can actually reach it
+- The narrow width. There is no room for columns on a phone, and the bar collapses into NavbarPanel rather than opening this
+- Content a reader has to work through. A panel is scanned in a moment with a pointer hovering over it; a paragraph in one is a paragraph nobody finishes
+
+## Anatomy
+
+NavbarMenu renders 6 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-navbarmenu`. The trigger and its panel, and the box the second is positioned against. It holds no ground and no measure of its own — it is a position in the bar's row, and everything visible belongs to one of the two parts inside it.
+  
+  It is deliberately not positioned. An absolutely positioned panel resolves against the nearest positioned ancestor, and this root was it — so the panel hung from the trigger, which is one word wide, and centring on that centred on the word rather than on the row of them. Giving it up hands the job to Navbar's pill, which is the box a reader actually sees.
+  
+  The cost is a dependency rather than a free win: a menu used outside a Navbar has no pill to resolve against and will find whatever positioned ancestor the page happens to have. That is the trade for a panel that lines up with the set it belongs to, and it is worth naming because nothing will report it — the panel simply appears somewhere else.
+- `trigger` — `<button>`, class `dds-navbarmenu__trigger`. The name of the section, and the control that reveals it. A `<button>` with `aria-expanded`, which is the honest shape: it goes nowhere, and a reader who cannot see the panel is told whether it is open rather than left to press it and find out.
+  
+  It takes the same resting shape a NavbarItem does — the same target floor, the same pill, the same tints — because the two sit in one row and a reader scanning it should not be able to tell which of them the site happened to implement differently. What it adds is the chevron, and a filled shape while the panel is open.
+  
+  It takes no colour of its own. The bar sets the ink and this inherits it, on the same reasoning as every other end of the bar.
+  
+  It takes `font.label.sm` because NavbarItem does. The two sit in one row and the contract above says a reader should not be able to tell which of them the site implemented differently — a step between them is the one difference that would give it away.
+  
+  Floating, a mouse over it opens the panel without a press. That is what a bar of sections is expected to do on a desktop, and the press still works — hover is added to the button, not substituted for it, so Enter and Space reach it where no pointer exists and a reader who uses both gets the same result from either.
+  
+  Only a mouse, and only floating. The event is asked what kind of pointer it is rather than the device being asked once whether it hovers: a tap reports `touch` and a stylus `pen`, and a laptop with a touchscreen answers both at different moments. Inline the question does not arise — a panel row is read down with a finger, and a section that opened as one passed over it would open every section on the way to the last.
+  
+  It takes the bar's ink rather than the browser's. A `<button>` does not inherit `color`, so without this a section's name draws in the UA's `buttontext` — near-black, which passes for `color.fg.default` on a light bar and is the reason this went unnoticed. On an inverse bar the sections rendered dark while the plain destinations beside them rendered light, from one missing declaration.
+  
+  It reserves the same height a destination does, because it is one of them as far as a reader scanning the row is concerned.
+  
+  It pads its words by the same step a destination does. The two sit in one row and a reader scanning it cannot see which of them opens something until they meet the mark at the end — so anything that made them measure differently would be a difference with no meaning behind it.
+- `chevron` — `<span>`, class `dds-navbarmenu__chevron`. The mark that says this one opens. It turns rather than swapping — the same glyph rotated, so the shape stays recognisable and the movement is what carries the state.
+  
+  Decoration, and hidden from assistive technology. `aria-expanded` on the trigger says the same thing to a reader who cannot see it turn, and a glyph announced as well would say it twice.
+  
+  In the panel it is as wide as a target, not as wide as itself. The row sends it to the far edge, where the panel's close button is already standing on that line one row above — and the two marks are not the same size, so boxes that end together still put their centres four pixels apart, which is exactly the distance the eye reads as a column that does not line up. Taking `size.target.min`, the measure the close button already claims, and centring the glyph in it puts both on one line by construction rather than by arithmetic that would need redoing the next time either glyph changes step.
+  
+  Only in the panel. In the bar the mark sits against its own label inside a pill, where a box wider than the glyph would read as a gap opening between the word and its mark.
+- `surface` — `<div>`, class `dds-navbarmenu__surface`. The panel: the section's groups on one side, whatever the site wants shown beside them on the other. Under `floating` it is `position: absolute` against the root, so it hangs from the trigger rather than from the page — a panel positioned against the document would need the bar's own offset subtracted and would be wrong the moment anything above the bar changed height. Under `inline` it is in the flow, because inside the collapsed panel there is no bar to hang from and nothing to float over.
+  
+  It is `size.menu-panel.max` wide, and that is a width rather than a ceiling. A ceiling was the first attempt and it did nothing: an absolutely positioned box with one inset is shrink-to-fit, so a `max-inline-size` only clamps a panel whose contents already want more — and three groups beside a card want less, so every panel came out a different width decided by how many destinations happened to be in it. A section's panel is a surface with a measure, not a box that fits its words.
+  
+  Narrower than the page's own measure on purpose. A panel is scanned across with a pointer already on it, so one as wide as the page leaves its last column a long way from the name that opened it. What decides its position is the bar, not the trigger — a panel starting at the trigger's leading edge would run off the end of the page for the last section in the row. A panel starting at the trigger's leading edge would run off the end of the page for the last section in the row.
+  
+  Its own inset is `space.inset.xs` and not the step a surface usually takes. The card is the thing that meets the panel's edge, and a promotional picture floating in a wide white margin is a card that has been set down rather than fitted. What the words need instead is the groups' own inset, which they carry — so the copy keeps the measure it had and only the card moved.
+  
+  It clears the pill by `space.gap.sm`, and now the number and the distance are the same thing. `inset-block-start: 100%` is the pill's own height once the pill is what the panel resolves against, so the margin starts at the pill's bottom edge rather than the trigger's — which also retires an inset role that was standing in for a gap at a step the gap ramp does not have.
+  
+  Its corner is `radius.container` and not the `radius.surface` a panel would otherwise reach for, because a corner has to answer to what is inside it. The feature card takes `radius.surface` and sits `space.inset.xs` from the panel's edge, and two curves are concentric only when the outer one is the inner plus the distance between them — twenty-four and eight, which is thirty-two. Matched instead, the two arcs share a radius but not a centre, and the gap between them narrows through the corner and opens again on the straight: the shape reads as slightly wrong without it being obvious which of the two is at fault.
+  
+  It follows the inset rather than leading it. Change the panel's padding and this has to move with it, which is the cost of nesting two rounded boxes and worth paying over the alternative of a corner that only looks right at one measure.
+  
+  It has a floor as well as a width. A bar's sections rarely hold the same number of destinations, so panels sized by their contents alone are a different height each — and a reader moving along the row watches the surface under the pointer grow and shrink for reasons that are about the site's structure rather than about anything they did.
+  
+  A floor rather than a height, which is the honest half of the promise: it makes every panel the same size while every panel's contents fit inside it, and a section with more destinations than that is taller. The alternative is a fixed height that either crops the largest section or leaves the smallest one mostly empty, and neither is better than a panel that grows when it genuinely has more to say.
+  
+  Inline it takes the row's own inset rather than none, so a destination inside a set starts on the same line as the name that opened it. The panel pulls its list back out to the surface's edge and each row pads itself back in; a set that skipped that step would hang a step to the leading side of every row above it, which reads as the sets belonging to something other than the section they opened from.
+  
+  It does not animate in when it is replacing another. Moving along a row of sections, the panel that was open unmounts and this one mounts — two elements, so there is nothing to tween between — and playing the entrance on the second reads as the first closing and a new one opening rather than as the two exchanging places. What the eye sees at that moment is a flicker where a panel already was.
+  
+  So the entrance is for arriving over a page with nothing else open, which is the only time it is describing anything. Whether this is an arrival or an exchange is the container's to know: a menu cannot see its neighbours, and the bar holding one open at a time can.
+  
+  Inline, the step between the sets and the picture is `space.gap.md` — a step below the one that separates two sets, and the same one that separates two destinations inside a set. Stacked in a column the picture is the end of the section rather than a break in it, and the larger steps read as a division: at those, the card looked like something that had been appended to the panel rather than the last thing in it.
+  
+  The floating form keeps its own, which is a different question — there the two sit side by side and the gap is the column between them. Rendered only when `open` is set.
+- `groups` — `<div>`, class `dds-navbarmenu__groups`. The sets, in two columns, across half the panel — the feature beside it takes the other half, and neither holds that measure as a number: both ask for the whole surface and shrink against each other until they agree. A section of a marketing site has more destinations than one column holds at a readable height, and a single column of twenty is a scroll inside something that opened on a hover. Two rather than one per group: a column per set makes the panel as wide as the number of sets it happens to hold, so adding a fourth would push the feature card out.
+  
+  Columns rather than a grid, and the difference is what a set does with the space beside it. A grid aligns its rows, so a set of one laid out beside a set of seven is stretched to the taller one's height and the next set down starts below both — a column of two items with a hand's width of nothing under it. Columns pack instead: each one fills, and a set begins where the set above it ended.
+  
+  It also makes the count a decision about the panel rather than about the content. Two, whatever the number of sets — where a row of them made the panel as wide as however many it happened to hold, and a fourth would have pushed the feature card out of the surface.
+  
+  It sets the type the destinations inherit. A `list` Link takes the ink and the measure around it — that is the variant's whole point, a column of coral being a column nobody reads — so with nothing set here the rows fell back to the browser's own default. `font.body.sm` is the fourteen-pixel step at a regular weight, and the weight is the half that matters here: the labels over these rows are `font.label.sm`, the same size semibold, so what tells a signpost from a destination is the weight and the ink rather than the measure. `font.label.md` was the first attempt and is the bar's own step — semibold, right for a row scanned across and heavy enough in a column that these rows stopped looking like list links anywhere else in the system.
+  
+  The role is imperfect and worth naming as such: `font.body.sm`'s own description is written for de-emphasised text — disclaimers, copyright lines — where this is a column of destinations. The alternative reads better on paper and worse on screen: `font.label.sm` names footer links in as many words, and is exactly what the labels above these rows already take, so the two would part company on colour alone.
+  
+  Its foot is deeper than its head, and the depth belongs here rather than on the surface — which is where it went first, and was wrong. The panel's own frame is one small measure on all four sides because the picture beside these sets is meant to reach it: a card inset from the panel's edge is a card floating in a box rather than filling its half of one. Only the words need the extra room, so only the words take it.
+  
+  Why the extra at all: the sets carry the space between them as a margin, since multi-column has no row gap to put it in, and whether a margin at the end of a column counts towards that column's height is a thing browsers do not agree on. The container cancels it either way, so the space under the last set is the one measure here not fully under this component's control — a deeper declared inset is what makes it look right whichever way the browser goes.
+- `feature` — `<div>`, class `dds-navbarmenu__feature`. What the site wants shown beside the destinations — a promotion, a feature, a piece of art. A slot, because it is a Card and a Card is a component the page already has; this declares where it sits and what shape it holds.
+  
+  `aspect.widescreen` — sixteen by nine, the shape most moving media already is. It is on this region rather than on the card inside it, and the difference matters: CardBody's own `aspect` shapes the picture, and under `overMedia` the picture is the ground, so the card's height still came from however much copy it was given. A card that is a different height every time the words change is not a shape anybody laid out.
+  
+  It takes half the panel, and the groups take the other half. Both declare `inline-size: 100%` and both flex, so each asks for the whole surface and the two shrink against each other to the same measure — a half that follows from the pair rather than a number either of them holds. Content-sized was the arrangement before, and the card's width then moved with however many words the copy ran to.
+  
+  Beside the groups under `floating` and beneath them under `inline`. The panel is wide and the collapsed one is narrow, and a promotional card in a column half a phone wide is a picture nobody can read the words on. Rendered only when `feature` is set.
+
+Apply these classes from the generated `navbarMenuParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `NavbarMenuGroup`, `NavbarItem`
+- Never contains: `Navbar`, `NavbarMenu`, `NavbarPanel`, `BottomSheet`, `TabList` — in children or in any prop that takes a node
+
+## Props
+
+### presentation — `floating` | `inline` (default `floating`)
+
+- `floating` — The menu is in the bar, which is everywhere a page puts one. The panel hangs from the trigger and floats over what is beneath it
+- `inline` — NavbarPanel is rendering the menu, and it sets this itself — a page should not. Inside the collapsed panel there is nothing to float over and no bar to hang from, so the panel opens in the flow and pushes what follows it down, which is what an accordion row does
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The bar has a light ground under it, which is every bar on a marketing page today. The trigger's tints are ink-based and read against paper
+- `inverse` — The bar sits on a dark ground and the ink runs light. Only the trigger mirrors — the panel is its own surface with its own ground, and is the same either way
+
+### label — `string` **Required.**
+
+Use when: Always — it is the name of the section, the words on the trigger, and the accessible name of the control. Name the section rather than the act: 'Trading', not 'Open trading menu'
+Never for: A description of what is inside. The panel says that by holding it, and a trigger long enough to explain itself is a trigger that breaks the row it sits in
+
+### open — `boolean`
+
+Use when: The bar is holding which section is open, because only one should be at a time. Passing it makes the menu controlled: it shows what it is told and reports presses through onOpenChange.
+
+Leave it off and the menu holds its own answer, which is right for a menu standing alone and wrong for a row of them — two panels open at once is two surfaces overlapping in front of the page
+Never for: Half of a controlled menu. An open passed without an onOpenChange to move it is a panel that cannot be closed by pressing the trigger that opened it
+
+### onOpenChange — `callback`
+
+Use when: Whenever open is — together they are how a bar holds which section is showing. It is called with the state being moved to, by the trigger and by Escape
+Never for: Navigation. This says whether the panel is showing; a reader pressing a destination inside it is leaving by a different door
+
+### replacing — `boolean` (default `false`)
+
+Use when: Another section's panel was already on screen when this one opened. A container that holds one section open at a time knows this and a menu cannot, so the container sets it — Navbar does, and a page should not
+Never for: Turning the entrance off generally. A panel that arrives over a page with nothing else open has something to say about where it came from, and saying it is the difference between a panel appearing and a panel being noticed
+
+### feature — `node`
+
+Use when: The section has something the site wants shown alongside its destinations — a promotion, a platform, a piece of art. A Card, which already knows how to hold a picture with words over it.
+
+That is not declared as an `accepts`, and the omission is deliberate: the workbench builds a sample for any slot naming a component, from that component's own showcase, and it cannot build one whose children are themselves components — which a Card's are. Naming it would document the slot by breaking the page that shows it.
+Never for: More destinations. Anything that goes to a section of the site belongs in a group, where the reader is looking for it
+
+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: `button`
+- `Tab` — Reaches the trigger, then the destinations inside the panel once it is open, then on out of the menu. There is no roving tabindex and no arrow keys: what opens is a set of links rather than a menu of commands, so a reader keeps the key they already have and is not trapped in a widget they did not ask to enter.
+- `Escape` — Closes the panel and returns focus to the trigger. The way out that does not have to be seen, and the only one for a reader who opened it from the keyboard. It also ends a panel the pointer opened, so a reader who reaches for the keyboard is not told the way out belongs to the mouse.
+- `Enter` — Opens and closes the panel, which a button does without anything being added.
+- accessible name from label on the trigger, which is the name of the section and the words a reader sees
+- The trigger reports whether the panel 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.
+- A button rather than a link. It goes nowhere: there is no href, no history entry and nothing for the back button to undo, and every assistive technology is told the same.
+- The chevron is hidden from assistive technology. aria-expanded already says which way the panel is, and a glyph announced beside it says it twice.
+- The panel is not a menu and takes no menu role. What it holds is links, and role="menu" would promise a widget with arrow-key navigation and a set of commands — a promise whose first consequence is that a screen reader stops announcing the links as links.
+- Only one panel in a bar is open at a time, which is the bar's to enforce and not this component's. Two open panels overlap in front of the page, and a menu holding its own answer cannot see its neighbours.
+
+## 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
+
+❌ NavbarMenu for: The destination is a single place
+   A trigger that opens a panel holding one link is two presses where one would do, and it takes a link out of the tab order to put it behind a button
+   → use `NavbarItem` instead.
+
+❌ NavbarMenu for: What opens is a single column of choices rather than a section of the site
+   A menu opens at its trigger and is as wide as its longest option, which is right for a language picker and wrong for a section — and its rows are commands a reader picks from rather than places the site has
+   → use `DropdownMenu` instead.
+
+## Example
+
+```tsx
+import { NavbarMenu, NavbarMenuGroup } from '@deriv-com/dds-marketing'
+
+<NavbarMenu label="Trading">
+  <NavbarMenuGroup href="/forex">Forex</NavbarMenuGroup>
+  <NavbarMenuGroup href="/stocks">Stocks</NavbarMenuGroup>
+  <NavbarMenuGroup href="/commodities">Commodities</NavbarMenuGroup>
+</NavbarMenu>
+```
+
+## In use
+
+Most rows below hold the same set, written once here:
+
+```tsx
+import { NavbarMenuGroup } from '@deriv-com/dds-marketing'
+
+const navbarmenugroups = (
+  <>
+    <NavbarMenuGroup href="/forex">Forex</NavbarMenuGroup>
+    <NavbarMenuGroup href="/stocks">Stocks</NavbarMenuGroup>
+    <NavbarMenuGroup href="/commodities">Commodities</NavbarMenuGroup>
+  </>
+)
+```
+
+### Closed, and open
+
+The trigger is a button and goes nowhere. Closed it reads as one of the destinations beside it; open it fills its shape in and the chevron turns.
+
+```tsx
+import { NavbarMenu } from '@deriv-com/dds-marketing'
+
+// At rest — one name in the row
+<NavbarMenu label="Trading">{navbarmenugroups}</NavbarMenu>
+
+// Open — the section's own destinations
+<NavbarMenu label="Trading" open>{navbarmenugroups}</NavbarMenu>
+```
+
+### In the bar, and in the panel
+
+One component, two presentations. NavbarPanel sets inline itself — there is nothing to float over at that width, so the panel opens in the flow and pushes what follows it down.
+
+```tsx
+import { NavbarMenu } from '@deriv-com/dds-marketing'
+
+// floating — hanging from the bar
+<NavbarMenu label="Trading" open>{navbarmenugroups}</NavbarMenu>
+
+// inline — opened inside the collapsed panel
+<NavbarMenu label="Trading" open presentation="inline">{navbarmenugroups}</NavbarMenu>
+```
+
+### Which ground the trigger is on
+
+Only the trigger mirrors. The panel is a surface of its own with its own ground, so it is the same either way — the tone is about the row, not about what opens.
+
+```tsx
+import { NavbarMenu } from '@deriv-com/dds-marketing'
+
+// default — a light bar
+<NavbarMenu label="Trading">{navbarmenugroups}</NavbarMenu>
+
+// inverse — a bar on a dark ground
+<NavbarMenu label="Trading" tone="inverse">{navbarmenugroups}</NavbarMenu>
+```