@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/navbar.md

@@ -0,0 +1,458 @@
+<!-- GENERATED from navbar.contract.json. Do not edit. -->
+
+# Navbar
+
+The bar across the top of a marketing page, and three regions: the mark that says whose site this is, the places the site has, and the things a reader reaches for rather than navigates to — the language, the theme, and what the site wants them to do.
+
+It holds no destinations of its own. What goes in it is the NavbarItems and NavbarMenus a page composes, because a marketing site's navigation is written by the site rather than enumerated by this system, and a component that took an array of routes would be a second router nobody asked for. What this owns is the bar: where it sits, what it is made of, and what happens when it runs out of room.
+
+Running out of room is the whole of its behaviour. Below the width its three regions fit in, the destinations and the utilities stop being drawn and a single control takes their place — and what that control opens is NavbarPanel, which this renders. The threshold is the bar's own width rather than the window's, because what decides whether the destinations fit is the room the bar has, and a bar in a column has less of it than a bar across a page.
+
+## Use when
+
+- A marketing page needs its top-level navigation — the mark, the sections of the site, and whatever sits at the far end
+- The same bar has to persist while the page scrolls, so a reader deep in a long page can still leave it
+- The navigation has to work at a phone's width without the page writing a second version of it
+
+## Do not use
+
+- The items are versions of one thing rather than places the site has → `TabList`
+- What is wanted is one section's panel rather than the bar it hangs from → `NavbarMenu`
+- The navigation runs down the side of an application rather than across the top of a page → nothing here does this
+- A second bar further down the page. There is one landmark of this kind per page, and a reader who meets two has been told twice where they are and once too often which is authoritative
+- A toolbar. Controls that act on what is below them — a filter row, a sort row, a set of view switches — are not places, and putting them in the site's navigation landmark means a screen reader announces them as somewhere to go
+- A footer. The same links at the bottom of a page are a sitemap a reader reaches at the end, not a frame they navigate from, and they need none of the sticking or collapsing this does
+- An app shell. This sticks to the top of a document that scrolls; an application whose regions scroll independently needs a frame this cannot be, and the product package is where that lives
+
+## Anatomy
+
+Navbar renders 11 elements. A token binding names the part it applies to.
+
+- `root` — `<header>`, class `dds-navbar`. The rail: what sticks, and nothing else. It paints no ground of its own — what a reader sees as the bar is the row inside it, and a rail that painted its own would be a band behind a surface that already has one.
+  
+  It sticks: `position: sticky` with `inset-block-start: 0`, so it travels with the reader rather than being scrolled off and hunted for. Sticky rather than fixed, which is the whole difference between a bar the page has made room for and a bar that covers the first line of the page — a fixed bar obliges every consumer to pad the top of their own document by a height only this component knows.
+  
+  It carries the ink, and that is what lets the whole bar change together. Every end inherits it: the mark, the destinations, the utilities and the trigger follow one declaration, and none of them can be left behind on a ground the others moved off.
+  
+  It is a `<header>` and takes no role of its own. A `<header>` at the top level of a document is already the `banner` landmark, and writing `role="banner"` says the same thing a second time in a way that goes stale if the element ever moves inside a `<section>`. The accessible name goes on the `nav` inside it, because what a reader needs named is the set of destinations rather than the box around it.
+  
+  Its gutter does not change when the page moves, and that is a correction rather than an omission. It gained one on scroll while the ends were being removed and the pill was the only thing left — but a gutter appearing is the row narrowing, and the ends take a share of whatever width the row has, so both of them lost half of it at the instant they were meant to be rising cleanly away. Nothing about the condensed state touches layout now: what changes is what can be seen, and every box stays exactly where it was.
+  
+  It holds no air of its own. That moved to the row when the collapsed bar gained a ground: paint cannot cover a parent's padding, so a rail that padded itself would have left a transparent strip above and below an otherwise opaque bar. What the reader sees is unchanged — the row's `space.inset.sm` is the rail's eight and the row's four said once — and so is the thing that measure exists to protect: the mark sits the same distance below the top edge here as it does in the panel that opens over this bar, so it does not move at the moment the panel appears.
+- `inner` — `<div>`, class `dds-navbar__inner`. The row: three regions in order — the mark, the destinations, the utilities. It takes the whole width the rail gives it and is not capped at `size.content.max` the way the page's own content is. A bar is the frame around a page rather than a column of it: its mark belongs at the edge of the window and its actions at the other edge, and a bar that stopped where the paragraphs stop would leave both floating in from the sides of a wide screen with nothing under them.
+  
+  Drawn in full it paints nothing. No ground, no corner and no lift: the only shape in the bar is the pill around the destinations, and a container behind it would be a second rounded box holding one rounded box. The bar is an arrangement rather than a surface at that width, and what separates it from the page is the air it holds above and below itself.
+  
+  Collapsed it is a surface, and the ground it takes then is a part of its own rather than a binding here — see `ground`, which explains why the paint cannot sit on the box it belongs to.
+  
+  It carries the bar's air, which the rail used to. A rail that padded itself would hold the row's ground off its own edges by that much, and the collapsed bar would be an opaque band with a transparent strip above and below it. The step is unchanged where it shows: the rail's eight and the row's four were always read together, and `space.inset.sm` is the two of them said once.
+  
+  It reserves `size.control.md` in the block axis — a control's height, because a control is what it holds: the action the bar keeps when it collapses is a button, and a row that reserved only a tap target would be sized by that button instead, growing the bar and dropping the mark eight pixels below where the panel draws it. The panel's own header reserves the same measure for the same reason, which is what keeps the mark still when one opens over the other. With eight either side that is a bar of fifty-six. Forty-eight was right while the collapsed bar held a mark and a glyph, and stopped being right the moment it held a control as well: four pixels above a forty-pixel button is not a margin, it is the button very nearly touching the edge of the bar. The step went up rather than the button coming down, because the button is the page's and a bar that only looked correct at one button size would be a bar with an undeclared requirement in it. The row is otherwise as tall as the tallest thing in it, and what is in it changes with the width — so without a floor the bar would be one height beside a set of destinations and another beside a single control, and the page below would move when it changed.
+  
+  It is the query container, and it is this row rather than the rail for a reason that is easy to get wrong: `container-type: inline-size` brings layout containment with it, and a box with layout containment becomes the containing block for any `position: fixed` inside it. Put on the rail, it would resolve the panel's `inset: 0` against the bar — a full-page surface collapsed to a strip the height of the header. The row holds no fixed descendants, and its width is the bar's own less the gutter, which is the measure the regions actually have to fit in.
+  
+  `min-inline-size: 0` so the row is allowed to shrink at all. Without it a long set of destinations pushes the utilities off the end rather than letting the row reach the width where it gives up.
+  
+  Once the page moves it becomes the pill. The shape does not travel between elements and nothing in the markup is rearranged: the row already holds all three ends, so what changes is which of the two boxes paints. That is the whole of the condensed state — the mark and the actions were always inside this box, and at rest it simply drew nothing around them.
+  
+  The control it reserves is `size.control.lg`, which is what the bar's actions are. Collapsed, the row holds one of them beside the mark and the way in, so reserving anything smaller would let that button set the bar's height and make a page with one taller than a page without.
+  
+  The measure it reserves is `size.bar.height`, not a control's. Reserving a control was the near miss: it is a floor, and the action the bar keeps when it collapses is taller than the floor less this row's own air — so that button set the height, the row's contents came out a step shorter than the panel's header, and the mark moved down four pixels at the moment a surface opened over the bar drawing it. Reserving the bar's height instead puts the contents at one measure whatever is in them, which is the thing the panel can then agree with.
+- `ground` — `<div>`, class `dds-navbar__ground`. The collapsed bar's ground, and an element rather than a binding on the row it paints.
+  
+  The row cannot paint itself, which is the whole reason this exists. Whether the bar is collapsed is a question about the row's width, `@container` is the only thing that can ask it, and a container query styles the descendants of the box that declares it — never that box. The row declares it, so the row is the one element in the bar the query cannot reach. A child of the row can be reached, and `position: absolute` with `inset: 0` makes that child exactly the size of what it stands in for: the containing block is the row's padding box, so the ground covers the row's air as well as its contents and the bar is opaque edge to edge.
+  
+  `color.bg.page` rather than the pill's `surface-raised`, though the two resolve to the same white today. The pill is a surface lifted off the page; this is the page's own chrome, held at the top while the rest of it goes by — and the roles say which is which even where the values agree.
+  
+  `elevation.surface.sticky` for the same reason, and it is the role's own stated job: a surface pinned in place while content scrolls beneath it, stronger than `raised` because it has to stay distinct from whatever passes under it. The pill's `floating` would be the wrong claim — nothing here floats over anything, it is the top of the page.
+  
+  Not drawn where the bar is drawn in full, which is the stylesheet's call and not this contract's. A width is not something `presentWhen` can name.
+  
+  It lifts only once there is something to lift over. A shadow is a claim that what it is on is behind it, and at the top of an unscrolled page nothing is — the bar is level with the first thing the reader meets. Bound in the condensed state alone rather than at rest and overridden, so the resting appearance is the absence of a rule rather than a rule cancelling another.
+- `brand` — `<div>`, class `dds-navbar__brand`. The leading end: whose site this is. A slot rather than a prop with a shape, because a mark is a logo, a wordmark, or both side by side, and each is an element the page already has — an `<a href="/">` around an SVG, in practice.
+  
+  It does not shrink, and it is the one thing that survives every width. A bar too narrow for everything in it gives up the destinations and the utilities; the mark stays, because a bar with no mark is no longer a site's bar.
+  
+  Nothing here makes it a link. A mark that goes home is an `<a>` the page passes in, and a `<header>` that wrapped its contents in a link it was not given would be a nested interactive element the first time anyone passed one.
+  
+  It moves. At rest it stands outside the pill at the leading end of the row; once the bar gathers it is rendered inside the pill instead, which is the whole of what the condensed state does. Rendered in one place at a time rather than drawn twice and hidden — two marks in the markup is two things a screen reader has to be kept from announcing, and a hidden one is only ever one stylesheet away from being read out.
+  
+  It decides how tall the mark is rather than taking whatever it was handed. A slot that let the page set the measure would let the page set the bar's height with it — a logo an inch tall does not overflow, it makes the row an inch tall and every page below it move down. The step is `icon.size.md`, which sits inside the pill with room either side rather than filling it: a mark as tall as the shape around it reads as a label in a box rather than a mark on a bar. Twenty-four in a forty-eight pill leaves twelve either side, and it is the step the subdomain bar was already drawing its mark at — two bars off the same family disagreeing about how tall a logo is was a difference saying nothing.
+  
+  It measures border-box, which matters only because it collapses. Both copies of this part go to nothing wide when they are not the live one — and a width set on a content box leaves the padding standing, so the inset this carries would sit in the bar as a strip of nothing: twelve pixels inside the pill, a gutter's worth at the row's edge. Border-box takes the padding with the width, so nothing is what nothing means.
+  
+  It carries the corner of what it holds, which matters only while it is collapsing. The box clips its contents for the part of that journey where it is narrower than they are — and a rectangle cuts a pill-shaped button off square, so the actions appeared to have corners for four hundred milliseconds and then grow them back. `radius.pill` on the box that does the cutting means the cut has the shape of the thing being cut.
+  
+  At rest it is invisible either way: the box is a share of the row, far wider than what is in it, so its own corners are nowhere near anything. Rendered only when `brand` is set.
+- `nav` — `<nav>`, class `dds-navbar__nav`. The destinations, and the part that carries the accessible name. `<nav>` is the `navigation` landmark, which is the honest role for a set of places — and it goes inside the pill rather than being the pill, so the mark and the actions can join them there without being announced as somewhere to go.
+  
+  What goes in it is the page's: NavbarItems for single destinations, NavbarMenus for the sections that open. This declares the row, the gap and the landmark, and nothing about what the row holds or what it reveals.
+  
+  It does not wrap and it does not scroll sideways. A bar that wrapped to two lines has changed the height of something every page below it has made room for; a bar that scrolled sideways would hide destinations behind a gesture nobody is offered on a marketing page. What happens instead when they stop fitting is that the whole region goes and the trigger takes over, which is a decision a reader can see.
+  
+  It is not rendered at the widths the panel is. The panel carries the landmark there, and two landmarks naming the same destinations would tell a reader the site has two navigations — the one they cannot see being the one they are offered first.
+  
+  It does not shrink below what is in it. `min-inline-size: 0` was on this box and let it, which is a licence a container can only use by breaking: everything inside declares `flex-shrink: 0` and keeps its measure, so the box got narrower and its contents stayed the same size and drew over each other — a destination printed across a switcher, which is what a squeeze looks like when nothing is allowed to give.
+  
+  The default is `auto`, which for a flex item means its own min-content, so running out of room now overflows the row instead. That is not a good outcome either and it is a far better failure: it is visible, it is obviously wrong, and it says the bar has more in it than its width can hold — which is a decision for the page rather than something for this component to hide.
+  
+  The row above still carries the licence, and has to: it is the query container, and a container that cannot shrink never reaches the width where it gives up and collapses.
+  
+  No gap between the destinations, which is about the pointer rather than about the spacing. Each one pads its own words, so there is a clear step between them either way — what a gap adds is a strip of row belonging to neither, and a section that opens under the pointer treats that strip as having left. Moving from one name to the next, a reader crossed it: the first section armed its close, and if the hand paused in the four pixels between them it fired, so the panel shut and the next one opened rather than the two exchanging places.
+  
+  At nothing the targets touch, and the pointer is over a destination at every moment of the journey. The words stay `space.inset.sm` apart because that is what each of them is padded by — the spacing a reader sees was never the gap.
+- `preferences` — `<div>`, class `dds-navbar__preferences`. What a reader sets rather than goes to, kept with the destinations.
+  
+  Inside the pill and outside the landmark, which is the whole reason it is a part of its own. A language picker is not a place the site has, so it cannot go in `nav` — a reader tabbing the navigation would be offered it as somewhere to go. And it is not a conversion either, so the trailing end is the wrong home: the pill is the set of things the bar is about, and the locale a reader is reading in belongs to that set rather than to the pair of buttons asking them to sign up.
+  
+  Drawn at every scroll position, unlike the two ends. The pill is the one region that is always itself: at rest it holds the sections, gathered it holds everything, and this sits beside the sections in both. That is what makes it worth being here rather than in `utilities`, which is drawn in the row at one moment and inside the pill at the next.
+  
+  Gone with the pill when the bar collapses, and handed to the panel's foot with the utilities — so a reader on a phone still finds it, in the one place the bar's trailing end has gone. Rendered only when `preferences` is set.
+- `utilities` — `<div>`, class `dds-navbar__utilities`. The trailing end: what a reader reaches for rather than navigates to. A language switcher, a theme switcher, and what the site wants them to do — a slot, because each of those is a component the page already has and none of them is this one's to invent.
+  
+  Separate from the destinations on purpose, and outside the landmark. A language is not a place the site has and a sign-up is not a section of it; a reader tabbing the navigation landmark should reach the end of the site's sections before meeting either. Putting them inside `nav` would announce a language picker as somewhere to go.
+  
+  It does not shrink, and it is not drawn once the bar collapses. Everything here moves to the foot of the panel, where there is room for each of them at full width — which is the arrangement a narrow screen wants anyway.
+  
+  Like the mark, it moves inside the pill once the bar gathers, and for the same reason: the gathered bar is one object, and an action outside the shape is an action that has been left behind by it.
+  
+  It measures border-box, which matters only because it collapses. Both copies of this part go to nothing wide when they are not the live one — and a width set on a content box leaves the padding standing, so the inset this carries would sit in the bar as a strip of nothing: twelve pixels inside the pill, a gutter's worth at the row's edge. Border-box takes the padding with the width, so nothing is what nothing means.
+  
+  It carries the corner of what it holds, which matters only while it is collapsing. The box clips its contents for the part of that journey where it is narrower than they are — and a rectangle cuts a pill-shaped button off square, so the actions appeared to have corners for four hundred milliseconds and then grow them back. `radius.pill` on the box that does the cutting means the cut has the shape of the thing being cut.
+  
+  At rest it is invisible either way: the box is a share of the row, far wider than what is in it, so its own corners are nowhere near anything. Rendered only when `utilities` is set.
+- `compact-action` — `<div>`, class `dds-navbar__compact-action`. The action the bar keeps when it collapses.
+  
+  Everything else at the trailing end stops being drawn at that width and is laid out down the foot of the panel instead, which is right for a language switcher and wrong for the one thing the page most wants pressed: a reader would have to open a menu to find it. So one action stays out, beside the control that opens the panel.
+  
+  A slot of its own rather than the first of `utilities`, because the bar cannot tell which one matters. A pair reading "Log in" and "Sign up" is the usual case and the first of them is the wrong answer — and a component that picked by position would be making a decision about the site's funnel from the order two elements happened to be written in.
+  
+  It is a duplicate, and deliberately. Whatever goes here almost certainly also goes in `utilities`, so the panel's foot carries it too — a reader who opens the panel looking for it finds it where the rest of the set is rather than having to close the panel again. Only one of the two is ever on screen, because the panel covers the bar.
+  
+  Drawn only where the trigger is. At the widths where the bar draws its trailing end in full, this would be the same action twice in one row. Rendered only when `compactAction` is set.
+- `trigger` — `<button>`, class `dds-navbar__trigger`. The control that opens the panel, drawn only at the widths where the other two regions are not. Always rendered rather than conditional: what decides whether a reader sees it is the bar's width, and a width is not something a contract can gate a part on — so it is always in the markup and the stylesheet decides, which is also what lets its name and its state be checked at all.
+  
+  `size.target.min` in both directions, declared rather than emergent. The glyph is drawn at whatever step reads correctly beside the bar's own text, and a bar that let that step decide the target ships a control smaller than the pad of a finger — the one accessibility failure a navigation bar cannot afford, because at that width it is the only way through the site.
+  
+  It carries `aria-expanded`, which is the only thing telling a reader who cannot see the panel whether it is open. The glyph swaps from a bar stack to a close mark to say the same thing to everyone else.
+  
+  No hover fill. A pointer over it gets the cursor and nothing else, which is the one departure here from how a bare control usually answers: the bar draws a pill behind the destinations, and a second filled shape appearing beside it under the pointer reads as a competing object rather than as feedback. The control is still reachable and still says where focus is — the focus ring is the affordance that had to stay, because it answers to a reader who has no pointer to hover with.
+  
+  It takes the bar's ink rather than the browser's. A `<button>` does not inherit `color` — the UA gives it `buttontext`, which is near-black and indistinguishable from `color.fg.default` on a light bar, so this was invisible until a bar was asked to stand on a dark ground and the one control that opens the panel went on drawing itself in black on black. The destinations beside it say the same thing for the same reason.
+  
+  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.
+- `panel-host` — `<div>`, class `dds-navbar__panel-host`. Where the panel is rendered, and nothing else. It holds no ground, no measure and no arrangement — NavbarPanel brings all of those — so what this part is for is being a place in the tree rather than a box on the page. `display: contents` is how it says so.
+  
+  In the bar rather than a portal. The panel is `position: fixed`, so it escapes the flow without having to escape the tree, and staying in the tree keeps it in the DOM order a screen reader walks: immediately after the control that opened it, which is where a reader expects to find what they just opened.
+  
+  It carries no tone. It did while the panel took one, and the binding outlived the axis: the panel paints paper at every tone now and sets its own ink, so an inverse colour here was inherited by nothing and would have been white on white the moment the panel stopped saying otherwise. Rendered only when `menuOpen` is set.
+- `cluster` — `<div>`, class `dds-navbar__cluster`. The pill, and the one shape in the bar. At rest it holds the destinations alone and hugs them; once the page moves, the mark and the actions come inside it and it takes the row. Same element throughout — what changes is what is in it, not which box is painted, so the ground, the corner and the lift are declared once and never handed between parts.
+  
+  It is not the `<nav>`, and that is the whole reason it exists rather than the landmark being the pill. A reader moving between landmarks should be given the sections of the site; a mark that goes home and a pair of conversion actions are neither, and a pill that was also the landmark would announce all three as places. The box a reader sees and the box a screen reader is told about are different boxes here, and this is the first.
+  
+  Nothing about it changes with the state. The ground, the corner and the lift are bound once and hold whether the bar is at rest or gathered — what the condensed state moves is the contents, not the shape around them.
+  
+  It carries a gap of its own, which does nothing while it holds the destinations alone and separates the three ends once they are inside it. Declared rather than conditional: a measure that only applies when there is more than one thing to space is a measure that costs nothing when there is not.
+  
+  Its inset is the same on both axes and it is tight, because everything that meets its ends brings its own. A button is a filled shape with its own padding inside it and a destination pads its words, so the pill only has to clear them rather than space them. The mark is the exception — a picture with nothing of its own — and it carries the difference itself rather than the pill widening for it, which would push the two ends that were already right further in.
+  
+  When it gathers is a declared state again. It was removed when the tone axis arrived, because exhaustiveness asks for a binding in every cell of the grid an axis creates and there was nothing honest to give — the pill looks the same gathered as at rest, which is the point of it. What brought it back is a part that does have something to say: the collapsed bar's ground takes its lift only once the page is moving under it, and a single unconditional binding in that state covers both tones. The state was always real; it simply had nothing to bind until then.
+  
+  It does not shrink below what is in it. `min-inline-size: 0` was on this box and let it, which is a licence a container can only use by breaking: everything inside declares `flex-shrink: 0` and keeps its measure, so the box got narrower and its contents stayed the same size and drew over each other — a destination printed across a switcher, which is what a squeeze looks like when nothing is allowed to give.
+  
+  The default is `auto`, which for a flex item means its own min-content, so running out of room now overflows the row instead. That is not a good outcome either and it is a far better failure: it is visible, it is obviously wrong, and it says the bar has more in it than its width can hold — which is a decision for the page rather than something for this component to hide.
+  
+  The row above still carries the licence, and has to: it is the query container, and a container that cannot shrink never reaches the width where it gives up and collapses.
+  
+  It is a positioning context, which it needs because of what it holds rather than what it is. The copies of the ends inside it are taken out of flow while they are not being shown — a box at zero opacity that still reserved width would keep the pill at its gathered size at every scroll position — and an out-of-flow box resolves against the nearest positioned ancestor. Without this that was the row, so on the way back from a scroll the pill's own mark and actions jumped to the row's leading edge and faded out there, over the mark that was arriving.
+
+Apply these classes from the generated `navbarParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `NavbarItem`, `NavbarMenu`
+- Never contains: `Navbar`, `NavbarPanel`, `TabList`, `Card`, `CardButton`, `Table`, `BottomSheet`, `Accordion`, `Button`, `Link` — in children or in any prop that takes a node
+
+## Props
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The page begins on a light ground, which is most marketing pages. The bar paints in ink and the pill is paper
+- `inverse` — The first section of the page paints its own dark ground and the bar stands on it — a dark hero, a photograph, a brand-coloured takeover. The bar's ink runs light, the pill becomes a veil of white rather than a sheet of it, and the collapsed bar takes a solid dark ground of its own
+
+### label — `string` **Required.**
+
+Use when: Always — it names the navigation landmark, and a page with an unnamed one tells a screen-reader user there is navigation here without saying which navigation. Name the set rather than the act: 'Main', not 'Main navigation' — the role already supplies the word, and a name carrying it is announced as 'main navigation navigation'
+Never for: A visible heading. Nothing draws this. A bar needs no title, and a page that wants one has a heading of its own below the bar
+
+### menuLabel — `string` **Required.**
+
+Use when: Always — the trigger is an icon-only button and this is the only name it has, at the width where it is the only way through the site. Name what it reveals rather than its state: 'Menu', not 'Open menu', because aria-expanded already says which way it is and a name that also said so would contradict itself every other press
+Never for: A tooltip or visible text. The trigger draws a glyph and nothing else; this is the name a screen reader reads
+
+### closeLabel — `string` **Required.**
+
+Use when: Always — it names the panel's close button, which is the only visible way out of a surface covering the whole page. 'Close' is enough; the panel it closes is the only thing open
+Never for: The trigger's name. They are two controls in two places — the trigger is in the bar underneath the panel, and a reader cannot reach it while the panel is open
+
+### brand — `node`
+
+Use when: Effectively always on a real site — the mark, and usually an anchor to the home page wrapped around it. It is drawn twice: in the bar, and again in the panel's header, where it is the only thing left saying whose site this is
+Never for: A heading for the page. This is the site's mark, not the page's title, and a reader who meets the page's `<h1>` in the bar has been told the name of somewhere they already are
+
+### utilities — `node`
+
+Accepts: Button, ButtonIcon, DropdownMenu
+Use when: The bar's trailing end has something in it — a language switcher, a theme switcher, a conversion action, or some combination. A switcher is a DropdownMenu with the current choice on its trigger, which is what DropdownMenu's own guidance describes and why it is accepted here alongside the two controls. They are drawn in the row at wide widths and across the foot of the panel once it collapses
+Never for: Destinations. Anything that goes to a section of the site belongs in the children, where the navigation landmark announces it as one. The trailing end is for what a reader reaches for, not for the places the bar ran out of room for
+
+### compactAction — `node`
+
+Accepts: Button, ButtonIcon
+Use when: The one thing a reader should still be able to do once the bar has collapsed and everything else has gone into the panel — a sign-up, usually. Drawn beside the control that opens the panel, and only at the widths where that control is drawn
+Never for: The whole of utilities. A phone has room for one action beside a mark and a menu button, and a bar handed two of them either wraps or pushes the mark off its own edge — the rest belong in utilities, which the panel lays out down its foot where there is room for all of them
+
+### preferences — `node`
+
+Accepts: NavbarSwitcher, DropdownMenu, ButtonIcon
+Use when: A switcher that belongs with the destinations rather than with the conversion — a language picker, a theme toggle. It is drawn inside the pill, beside the sections, at every scroll position. A NavbarSwitcher is the one built for it: in the pill it is a trigger and a menu, and in the collapsed panel the same element becomes a row that opens a page of its own with a way back, because a dropdown inside a surface already covering the screen is a surface inside a surface
+Never for: A conversion action. Those belong in utilities, at the trailing end of the bar where a reader looks for them, and drawing one inside the pill would put the thing the page most wants pressed in among the places it goes
+
+### menuOpen — `boolean`
+
+Use when: The page is holding whether the panel is open, because something else depends on it — a route change that should close it, a surface of its own that must not open at the same time. Passing it makes the bar controlled: it shows what it is told and reports presses through onMenuOpenChange.
+
+Leave it off and the bar holds its own answer, which is the ordinary case: a narrow-width navigation panel is opened and closed by the reader and by nothing else
+Never for: Half of a controlled bar. A menuOpen passed without an onMenuOpenChange to move it is a panel that cannot be closed from its own close button — a trap around the whole page rather than a bar with a bug
+
+### onMenuOpenChange — `callback`
+
+Use when: Whenever menuOpen is — together they are how a page holds the panel. It is called with the state being moved to, by the trigger, by the close button and by Escape, so a page listening to it hears every way the panel can change
+Never for: Navigation. This says whether the panel is showing; a page that also routed on it would close the panel by leaving, and a reader pressing a destination inside it would fire both
+
+Also accepts everything from `HTMLAttributes<HTMLElement>`.
+
+## 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: `banner`
+- `Tab` — Moves through the bar in reading order — the mark, then each destination, then the utilities. Nothing here is a composite widget, so there is no roving tabindex and no arrow keys: a reader uses the key they already have, and a menu inside the bar answers for its own. While the panel is open, focus is held inside it.
+- `Escape` — Closes the panel and returns focus to the trigger that opened it. The way out that does not have to be seen, which is what makes it the one the close button must not be the only alternative to.
+- accessible name from label, on the navigation landmark rather than on the bar, so a reader moving between landmarks is told which set of destinations this is
+- accessible name from menuLabel on the trigger, which draws a glyph and no text. Nothing else in the bar names it.
+- The trigger reports whether the panel is open with aria-expanded. An icon-only button that opens something and does not say whether it is open leaves a reader pressing it to find out.
+- The header carries no explicit role. A <header> that is not inside a sectioning element is already the banner landmark, and writing the role as well says it twice — and says it wrongly if the element is ever nested, where the implicit landmark correctly disappears and a hand-written role would not.
+- The bar sticks rather than fixes, so it takes its own height out of the page instead of covering the first thing in it. A fixed bar hides content at the top of every document and hides the target of every in-page anchor the site has.
+- At most one NavbarMenu in the bar is open at a time, which is this component's to enforce because no menu can see its neighbours. Two open panels overlap in front of the page.
+- The threshold at which the bar collapses is its own width rather than the window's. A viewport query is right about the page and wrong about the component, and it is wrong silently — the arrangement it draws is a real one, just not the one the width called for.
+- The mark the page passes as brand goes home, and carries its own accessible name. Nothing here can do either: wrapping the slot in an anchor would nest one inside the anchor a real site already passes, and the name has to describe a picture this component never sees — "Deriv home" rather than the word a reader would hear if the mark's own title were left to stand. A mark that is not a link is the one way out of a site's deepest page that every reader expects to be there, missing.
+
+## 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
+
+❌ Navbar for: The items are versions of one thing rather than places the site has
+   A landmark says the items go somewhere. A strip says these are the same offer seen differently, and its items carry 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 `TabList` instead.
+
+❌ Navbar for: What is wanted is one section's panel rather than the bar it hangs from
+   A menu belongs inside this rather than instead of it — a bar with a Trading panel in it is one of these holding one of those
+   → use `NavbarMenu` instead.
+
+❌ Navbar for: The navigation runs down the side of an application rather than across the top of a page
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+## Example
+
+```tsx
+import { Navbar, NavbarItem, Button } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>}>
+  <NavbarItem href="/trading">Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+  <NavbarItem href="/about">About</NavbarItem>
+</Navbar>
+```
+
+```tsx
+import { useState } from 'react'
+import { Navbar, NavbarItem, Button } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// Navbar holds nothing: menuOpen is the consumer's, and it does not move until
+// the value handed back by onMenuOpenChange is written to it.
+const [menuOpen, setMenuOpen] = useState(false)
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>} menuOpen={menuOpen} onMenuOpenChange={setMenuOpen}>
+  <NavbarItem href="/trading">Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+  <NavbarItem href="/about">About</NavbarItem>
+</Navbar>
+```
+
+## In use
+
+Most rows below hold the same set, written once here:
+
+```tsx
+import { NavbarItem } from '@deriv-com/dds-marketing'
+
+const navbaritems = (
+  <>
+    <NavbarItem href="/trading">Trading</NavbarItem>
+    <NavbarItem href="/platforms">Platforms</NavbarItem>
+    <NavbarItem href="/about">About</NavbarItem>
+  </>
+)
+```
+
+### Three regions
+
+The mark at one end, the destinations in the middle, what a reader reaches for at the other. Each region is a slot, and the bar takes no view on what is in it.
+
+```tsx
+import { Button, Navbar } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// Mark, destinations and a conversion
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>}>{navbaritems}</Navbar>
+
+// No utilities — a bar that only navigates
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />}>{navbaritems}</Navbar>
+
+// No mark — inside a flow the reader is already in
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close">{navbaritems}</Navbar>
+```
+
+### The two tiers at the trailing end
+
+What decides the tier is not how important the destination feels but how many the bar already has. Primary means something only while it is the one.
+
+```tsx
+import { Button, Navbar, NavbarItem } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// Primary — the step the site exists to produce
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>}>
+  <NavbarItem href="/trading">Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+</Navbar>
+
+// Secondary — the quieter of a pair
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/login" variant="secondary">Log in</Button>}>
+  <NavbarItem href="/trading">Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+</Navbar>
+```
+
+### Where the reader is
+
+One destination carries current. The bar takes no view on which — it is the item that says so, and at most one in a row should.
+
+```tsx
+import { Button, Navbar, NavbarItem } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// Trading is the current section
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>}>
+  <NavbarItem href="/trading" current>Trading</NavbarItem>
+  <NavbarItem href="/platforms">Platforms</NavbarItem>
+  <NavbarItem href="/about">About</NavbarItem>
+</Navbar>
+```
+
+### The ground the bar stands on
+
+A page whose first section paints its own dark ground needs a bar that reads on it. The mark and the actions are the page's to supply in a form that does.
+
+```tsx
+import { Button, Navbar } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// default — a page that begins on paper
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>}>{navbaritems}</Navbar>
+
+// inverse — a dark hero under the bar
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>} tone="inverse">{navbaritems}</Navbar>
+```
+
+### The action it keeps when it collapses
+
+Below the width its trailing end is drawn at, everything there goes into the panel. One action can stay out, beside the control that opens it.
+
+```tsx
+import { Button, Navbar } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// Without one — the mark and the way in
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>}>{navbaritems}</Navbar>
+
+// With one — the conversion stays reachable
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>} compactAction={<Button size="md" href="/signup">Sign up</Button>}>{navbaritems}</Navbar>
+```