@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/subdomainnavbar.md

@@ -0,0 +1,327 @@
+<!-- GENERATED from subdomain-navbar.contract.json. Do not edit. -->
+
+# SubdomainNavbar
+
+The bar across the top of a subdomain — a documentation site, a playground, a product surface that lives beside the marketing site rather than inside it. Three regions in one line: the mark and what the product is called, the places that subdomain has, and what a reader reaches for at the far end.
+
+It is the plain sibling of Navbar, and the difference is a decision rather than an omission. A marketing bar gathers into a pill as the page moves, because a marketing page is a thing a reader travels down and the bar is asking to stay with them. A subdomain is somewhere a reader works: they are not being sold anything, the chrome should stop asking for attention, and a bar that rearranged itself while somebody read documentation would be motion answering nothing. So this one is flat, and stays exactly where it was put.
+
+It holds no destinations of its own, for the same reason Navbar does not: what goes in it is the NavbarItems and NavbarMenus the site composes. The destinations, the sections that open and the panel it collapses into are all the same components the marketing bar uses — only the bar around them is different, which is the whole argument for this being a second component rather than a switch inside the first.
+
+## Use when
+
+- A subdomain needs its top-level navigation — the mark, the places that subdomain has, and whatever sits at the far end
+- The bar should sit still. Nothing about it changes as the page scrolls, which is what a reader working in a page rather than reading down one wants of the chrome above it
+- The destinations belong at the far end with what a reader reaches for, rather than centred over the page: the mark holds one edge, everything a reader does holds the other, and the middle is left empty on purpose
+
+## Do not use
+
+- The page is the marketing site itself → `Navbar`
+- The items are versions of one thing rather than places the subdomain has → `TabList`
+- A second bar further down the page. There is one landmark of this kind per page, and a reader who meets two has been told twice where they are and once too often which is authoritative
+- A toolbar. Controls that act on what is below them belong in the page, not in a landmark that announces itself as the way around the site
+- The marketing site's own bar. The two are different components because they behave differently, and using this one there loses the thing that bar is for
+
+## Anatomy
+
+SubdomainNavbar renders 7 elements. A token binding names the part it applies to.
+
+- `root` — `<header>`, class `dds-subdomainnavbar`. The rail: what sticks, and the ground the bar is drawn on.
+  
+  Unlike the marketing bar's rail this one paints. There is no pill here to be the surface a reader sees, so the bar itself is that surface — which is also why it needs no part standing in for it: the ground is unconditional, drawn at every width, and a binding on this element covers the whole of it.
+  
+  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 difference between a bar the page has made room for and a bar that covers the first line of it.
+  
+  No `role="banner"`. A `<header>` outside a sectioning element already is that landmark, and writing it as well says so a second time in a way that goes stale if the element is ever nested.
+- `inner` — `<div>`, class `dds-subdomainnavbar__inner`. The row: the mark, the destinations, the far end. It takes the whole width and is not capped at `size.content.max` — a bar is the frame around a page rather than a column of it.
+  
+  The mark takes one end and everything else takes the other. The destinations sit with the far end rather than beside the mark or centred over the page — a tool's bar is read as two groups, the name of the thing you are in and the set of things you can do, and the space between them is what says they are two groups rather than one long row.
+  
+  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.
+  
+  `min-inline-size: 0` so the row is allowed to shrink at all. Without it a long set of destinations pushes the far end off the edge rather than letting the row reach the width where it gives up.
+  
+  Its height is declared, not emergent. `block-size` rather than a floor, so the bar is `size.bar.height` whatever it is handed — a page with a button at the far end and a page without one have the same bar, which is the whole of what a reader notices when they move between them. A floor was the first version and is a different promise: it says the bar is at least this tall, and a single control one step larger than the rest silently made every page carrying it taller.
+  
+  What it costs is that a control too big for the row overflows rather than growing it, which is deliberate. A page can see that at a glance and fix it; a bar that had quietly got eight pixels taller is something nobody notices until two subdomains are open side by side.
+  
+  Its air narrowed when the destinations grew. The bar's height is declared and the rows in it are `size.control.lg` now, so the inset either side is what is left over rather than a step chosen on its own — the height is the decision, and this follows it.
+- `brand` — `<div>`, class `dds-subdomainnavbar__brand`. The leading end: whose subdomain this is. A slot rather than a prop with a shape, because a mark here is usually a logo and the product's name side by side — an `<a href="/">` around both, in practice.
+  
+  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 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 far end; the mark stays, because a bar with no mark is no longer a site's bar.
+  
+  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. Rendered only when `brand` is set.
+- `nav` — `<nav>`, class `dds-subdomainnavbar__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 row rather than being the row, 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 sits at the trailing end, with the far end rather than against the mark. An auto margin on its leading side takes everything left over, so the destinations and what follows them travel together however wide the bar is and whatever the mark turns out to measure.
+- `utilities` — `<div>`, class `dds-subdomainnavbar__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. Rendered only when `utilities` is set.
+- `trigger` — `<button>`, class `dds-subdomainnavbar__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-subdomainnavbar__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.
+
+Apply these classes from the generated `subdomainNavbarParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `NavbarItem`, `NavbarMenu`
+- Never contains: `NavbarPanel`, `TabList`, `Card`, `CardButton`, `Table`, `BottomSheet`, `Accordion`, `Button`, `Link`, `Navbar`, `SubdomainNavbar` — in children or in any prop that takes a node
+
+## Props
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The subdomain's chrome is light, which is the page's decision rather than this bar's
+- `inverse` — The subdomain's chrome is dark, which is the usual case for a tool and is why nearly every page using this bar will pass it. It is not the default all the same: a default is what the component does when nobody says, and a bar that painted itself black unasked would be a component with an opinion about a page it has not seen. The bar paints `color.bg.strong`, its ink runs light, and the destinations and the far end are told the same so nothing in the row is dressed twice
+
+### 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, NavbarSwitcher
+Use when: The bar's trailing end has something in it — a language switcher, a theme switcher, what the subdomain wants pressed, or some combination. All three sit together at the far end, which is the whole of the trailing group: this bar has no second home for what a reader sets, because it has no pill for them to live in the way the marketing bar does.
+
+A switcher with a set of choices is a NavbarSwitcher, which the panel turns into a page of its own when the bar collapses. A switcher that draws a mark and no words is a DropdownMenu given a ButtonIcon as its `trigger` — DropdownMenu keeps the menu, the keys and the `aria-expanded`, and the ButtonIcon is what is drawn. A theme toggle that flips rather than opens is a ButtonIcon on its own. Both take `variant="plain"`, which gives up the edge so they sit beside the action without competing with it, and both are told the bar's tone.
+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
+
+### 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
+
+## 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.
+- 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
+
+❌ SubdomainNavbar for: The page is the marketing site itself
+   That bar centres its destinations in a pill and gathers the whole row into it once the page moves. The behaviour is the marketing site's signature and reads as restlessness anywhere a reader is trying to work
+   → use `Navbar` instead.
+
+❌ SubdomainNavbar for: The items are versions of one thing rather than places the subdomain has
+   A landmark says the items go somewhere. A strip says these are the same thing seen differently, and its items carry no href at all
+   → use `TabList` instead.
+
+## Example
+
+```tsx
+import { SubdomainNavbar, NavbarItem, Button } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/dashboard">Dashboard</Button>}>
+  <NavbarItem href="/docs">Documentation</NavbarItem>
+  <NavbarItem href="/playground">Playground</NavbarItem>
+  <NavbarItem href="/ai">AI Hub</NavbarItem>
+</SubdomainNavbar>
+```
+
+```tsx
+import { useState } from 'react'
+import { SubdomainNavbar, NavbarItem, Button } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// SubdomainNavbar 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)
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/dashboard">Dashboard</Button>} menuOpen={menuOpen} onMenuOpenChange={setMenuOpen}>
+  <NavbarItem href="/docs">Documentation</NavbarItem>
+  <NavbarItem href="/playground">Playground</NavbarItem>
+  <NavbarItem href="/ai">AI Hub</NavbarItem>
+</SubdomainNavbar>
+```
+
+## In use
+
+Most rows below hold the same set, written once here:
+
+```tsx
+import { NavbarItem } from '@deriv-com/dds-marketing'
+
+const navbaritems = (
+  <>
+    <NavbarItem href="/docs">Documentation</NavbarItem>
+    <NavbarItem href="/playground">Playground</NavbarItem>
+    <NavbarItem href="/ai">AI Hub</NavbarItem>
+  </>
+)
+```
+
+### The ground the chrome is on
+
+A subdomain says which chrome it has rather than assuming one. The destinations and the far end are told the same tone, so nothing in the row is dressed twice.
+
+```tsx
+import { Button, SubdomainNavbar } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// default — a subdomain whose chrome is light
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/dashboard">Dashboard</Button>}>{navbaritems}</SubdomainNavbar>
+
+// inverse — the usual case for a subdomain
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/dashboard">Dashboard</Button>} tone="inverse">{navbaritems}</SubdomainNavbar>
+```
+
+### Where the reader is
+
+One destination carries aria-current, which is the half of this a fill cannot say. The bar does not decide which — the page knows what it is rendering.
+
+```tsx
+import { Button, NavbarItem, SubdomainNavbar } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+
+// Reading the documentation
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/dashboard">Dashboard</Button>}>
+  <NavbarItem href="/docs" current>Documentation</NavbarItem>
+  <NavbarItem href="/playground">Playground</NavbarItem>
+  <NavbarItem href="/ai">AI Hub</NavbarItem>
+</SubdomainNavbar>
+```
+
+### The far end
+
+What a reader reaches for rather than navigates to. A real bar carries several of these together; a row here can name one, because JSON holds a component and not a list of them.
+
+```tsx
+import { Button, ButtonIcon, SubdomainNavbar } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// What the subdomain wants pressed
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/dashboard">Dashboard</Button>}>{navbaritems}</SubdomainNavbar>
+
+// A switcher — a mark, and no words to read
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<ButtonIcon variant="plain" size="md" label="Language" icon={<GlobeRegularIcon />} />}>{navbaritems}</SubdomainNavbar>
+
+// Nothing at all — the destinations alone
+<SubdomainNavbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />}>{navbaritems}</SubdomainNavbar>
+```