@deriv-com/dds-marketing 0.2.0 → 1.0.0

package/.llm/components/navbar.md

@@ -55,7 +55,7 @@ Navbar renders 11 elements. A token binding names the part it applies to.
   
   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 control it reserves is `size.control.md`, 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.
@@ -77,7 +77,7 @@ Navbar renders 11 elements. A token binding names the part it applies to.
   
   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 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 pill leaves eight 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.
   
@@ -101,6 +101,8 @@ Navbar renders 11 elements. A token binding names the part it applies to.
   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.
+  
+  Not positioned, on purpose. A section's panel hangs from the nearest positioned ancestor, and with the landmark out of that chain it is the pill — so every panel centres on the pill rather than on the destinations alone, which sit to one side of it once the language switcher and the theme toggle share it.
 - `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.
@@ -178,7 +180,7 @@ Apply these classes from the generated `navbarParts` constant rather than writin
 ### 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
+- `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, and the pill and the collapsed bar take the dark see-through material — a near-opaque black base, a white tint and a blur — so a light photograph behind cannot wash them out
 
 ### label — `string` **Required.**
 
@@ -203,13 +205,13 @@ Never for: A heading for the page. This is the site's mark, not the page's title
 ### 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
+Use when: The bar's trailing end has the site's actions in it: one Button, which is primary, or two — one primary and one secondary, the conversion beside the way back in. 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. The bar dresses what it is handed: every Button here is drawn at md and takes the tone of the ground the bar is on at that scroll position — inverse on the hero, default once the pill gathers — and a ButtonIcon or a DropdownMenu takes the tone too. That reaches the controls handed in directly, or in a fragment; a control inside a component of the page's own is past it, so a wrapper takes tone and size as props and passes them down
+Never for: More than two Buttons, a lone Button that is not primary, or a pair that is not one primary and one secondary — the bar's actions are a conversion and its alternative, and a third pill or a second of either rank makes the reader choose between things the bar should have ranked. A switcher is not a Button and does not count against the two. Nor destinations: anything that goes to a section of the site belongs in the children, where the navigation landmark announces it as one
 
 ### 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
+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. Dressed like utilities: a Button here is drawn at md and takes the bar's tone
 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`
@@ -218,6 +220,28 @@ 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
 
+### showThemeToggle — `boolean` (default `false`)
+
+Use when: The site offers light and dark and a reader can choose between them. The bar draws the toggle itself, after whatever preferences holds — a plain ButtonIcon in a pill-height square, a moon on the light page and a sun on the dark one, with no words — so every site's toggle is the same control in the same place. In the collapsed panel it is drawn at the panel's foot beside the other preferences.
+Never for: A site that ships one theme. A toggle that changes nothing is a control that lies about the page.
+
+### theme — `light` | `dark` **Required when showThemeToggle=true.**
+
+- `light` — The page is drawn in its light theme, so the toggle offers dark
+- `dark` — The page is drawn in its dark theme, so the toggle offers light
+
+Use when: Whenever showThemeToggle is — the theme in force. The page owns it, because what it switches is the page's data-theme rather than anything inside the bar; the bar only draws the toggle and reports presses.
+
+### onThemeChange — `callback` **Required when showThemeToggle=true.**
+
+Use when: Whenever showThemeToggle is. Called with the theme a press moves to; the page sets its data-theme from it and hands the new value back as theme.
+Never for: Persisting a preference the page has not decided to keep. Remembering the choice across visits is the site's call, made where it sets data-theme.
+
+### themeToggleLabel — `string` **Required when showThemeToggle=true.**
+
+Use when: Whenever showThemeToggle is — the toggle draws a glyph and no words, and this is the only name it has. Name the theme it turns on, not the gesture: 'Dark theme', read with aria-pressed, so a screen reader hears 'Dark theme, not pressed' on the light page and the name stays the same when the state changes.
+Never for: Visible text. Nothing is drawn beside the glyph; a toggle with words is a NavbarSwitcher.
+
 ### 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.
@@ -232,6 +256,16 @@ Never for: Navigation. This says whether the panel is showing; a page that also
 
 Also accepts everything from `HTMLAttributes<HTMLElement>`.
 
+## Choosing a variant
+
+Placement in, props out. When one of these describes what you are building, take
+its props — do not re-derive them from the variant descriptions above.
+
+- **A site bar with a language picker and a light and dark choice** — `preferences={<NavbarSwitcher>…</NavbarSwitcher>}` `showThemeToggle`
+  The language is a choice among many, so it is a NavbarSwitcher — a trigger and a menu in the pill, a page of its own in the collapsed panel. The theme is one of two, so it is a toggle rather than a menu, drawn by the bar after the language: a glyph with no words at the same height as every other item in the pill.
+- **The actions at the bar's trailing end — a sign-up, and a log-in for a reader who already has an account** — `utilities={<Button (primary) + Button (secondary)>…</Button (primary) + Button (secondary)>}`, not `utilities={<three Buttons, or two of one variant>…</three Buttons, or two of one variant>}`
+  Two actions, ranked: the conversion is primary and the way back in is secondary. With only one, it is the primary. A third button is a third demand in a row that has room for a pair, and the bar starts to read as a second navigation.
+
 ## 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.
@@ -314,6 +348,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples
 
@@ -328,6 +370,15 @@ Declared rather than emergent. Padding plus contents does clear 24px in several
 ❌ 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.
 
+❌ showThemeToggle=true + theme missing or empty
+   A toggle that does not know which theme is in force cannot say which one a press moves to, and would draw the wrong glyph half the time.
+
+❌ showThemeToggle=true + onThemeChange missing or empty
+   A toggle with nothing to call answers the pointer and changes nothing — the one failure the affordance cannot disclose.
+
+❌ showThemeToggle=true + themeToggleLabel missing or empty
+   The toggle draws a glyph and no words, so without this it ships unnamed and a screen reader announces a button and nothing else.
+
 ## Example
 
 ```tsx
@@ -390,25 +441,19 @@ import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
 <Navbar label="Main" menuLabel="Menu" closeLabel="Close">{navbaritems}</Navbar>
 ```
 
-### The two tiers at the trailing end
+### The action 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.
+A lone Button is the primary. With two, the other is secondary beside it — never three, never two of one rank. See the navbar-actions-are-a-pair rule.
 
 ```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
+// Primary — the one action the bar offers
 <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
@@ -456,3 +501,22 @@ import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
 // 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>
 ```
+
+### What a reader sets
+
+The language is a NavbarSwitcher in preferences. The theme is a toggle the bar draws itself after it with showThemeToggle — a glyph, no words, the height of every item.
+
+```tsx
+import { Button, Navbar, NavbarSwitcher, NavbarSwitcherOption } from '@deriv-com/dds-marketing'
+import { DerivCoralWordmark } from '@deriv-com/quill-logos-web'
+import { GlobeRegularIcon } from '@deriv-com/quill-icons-web'
+
+// Language only
+<Navbar label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>} preferences={<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<GlobeRegularIcon />} />}>{navbaritems}</Navbar>
+
+// Language and the theme toggle
+<Navbar onThemeChange={(theme) => { /* your handler */ }} label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>} preferences={<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<GlobeRegularIcon />} />} showThemeToggle theme="light" themeToggleLabel="Dark theme">{navbaritems}</Navbar>
+
+// On a dark page — a sun, the theme a press moves to
+<Navbar onThemeChange={(theme) => { /* your handler */ }} label="Main" menuLabel="Menu" closeLabel="Close" brand={<DerivCoralWordmark />} utilities={<Button size="md" href="/signup">Open account</Button>} preferences={<NavbarSwitcher label="EN" menuLabel="Language" backLabel="Back to the menu" icon={<GlobeRegularIcon />} />} showThemeToggle theme="dark" themeToggleLabel="Dark theme">{navbaritems}</Navbar>
+```

package/.llm/components/navbaritem.md

@@ -36,7 +36,7 @@ NavbarItem renders 4 elements. A token binding names the part it applies to.
   
   `position: relative`, for the one thing it holds that is not drawn: an external destination's warning in words, clipped out of the page. That recipe is absolutely positioned, so without a positioned ancestor it takes the document as its containing block and adds its offset to the bottom of a long landing page.
   
-  It reserves `size.control.lg`, the same height the bar's actions take. A destination is words and a button is a filled shape, so they are never the same object — but they stand in one row, and a row whose items are two heights reads as two rows that failed to line up.
+  It reserves `size.control.md`, the same height the bar's actions take. A destination is words and a button is a filled shape, so they are never the same object — but they stand in one row, and a row whose items are two heights reads as two rows that failed to line up.
   
   It pads its words by `space.inset.md`. With no gap between the destinations — the row sets none, so their targets touch and a pointer crossing from one to the next is never over neither — this inset is the whole of the space a reader sees between two names, twice over. It is the spacing decision for the row, not a detail of one item.
 - `icon` — `<span>`, class `dds-navbaritem__icon`. A mark before the words, for a bar that uses them. Optional and uncommon: a marketing site's sections are named in words a reader reads, and a glyph beside every one of them costs width the destinations need.
@@ -167,6 +167,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples
 

package/.llm/components/navbarmenu.md

@@ -237,6 +237,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples
 

package/.llm/components/navbarmenugroup.md

@@ -137,6 +137,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples
 

package/.llm/components/navbarpanel.md

@@ -38,7 +38,7 @@ NavbarPanel renders 8 elements. A token binding names the part it applies to.
   
   It is paper at every tone, including under a bar that is not. An inverse bar is inverse because the section beneath it painted itself dark and the bar is standing on that section — but this covers the page rather than standing on it, so there is no dark ground here to answer to, only the one this surface chooses. It had a tone briefly and it was wrong for the same reason the scrolled bar's was: a treatment that belongs to a ground, carried somewhere the ground is not.
   
-  What the page passes still comes out right without being passed twice. The foot holds the bar's own utilities, and a secondary action taking Button's `tone="inherit"` reads the ink of whatever surface it lands on — white against the bar, near-black here.
+  What the page passes still comes out right without being passed twice. The foot holds the bar's own utilities, re-dressed at the default tone, so a secondary action the bar turned white is drawn on paper here as the page's own.
 - `header` — `<div>`, class `dds-navbarpanel__header`. The top: the mark at one end, the way out at the other. The mark is repeated here rather than the panel being drawn beneath the bar, because a panel covering the page has covered the bar too — and a reader who has lost the mark has lost the one thing telling them whose site they are still on.
   
   Its height is the bar's row, and stated the same way: `size.control.md`, a control's height, under the same `space.inset.xs` the bar's row takes above it. Both reserve a control because both hold one — the bar keeps an action beside the trigger, this keeps the way out — and a row sized by whatever happens to be in it would put the mark at one height here and another there. Two tokens rather than one measure that happens to equal their sum, so retuning either moves both halves together.
@@ -207,6 +207,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples
 

package/.llm/components/navbarswitcher.md

@@ -40,7 +40,7 @@ NavbarSwitcher renders 7 elements. A token binding names the part it applies to.
   It pads its words by the same step the destinations do, for the same reason: it stands in their row.
 - `icon` — `<span>`, class `dds-navbarswitcher__icon`. The mark that says which question this answers — a globe for a language, without which the trigger is two letters nobody can place.
   
-  It is drawn at the step that sits with the words rather than above them. The trigger is set in `font.label.sm` and `icon.size.xs` is the nearest step to it — a mark a step larger reads as the thing being said and the letters beside it as a note on it, when the sentence is the other way round: the choice is what a reader came for and the globe only says which question it answers. It is also the measure the chevron at the other end takes, so the two marks bracketing the row agree. Rendered only when `icon` is set.
+  It is drawn at icon.control.md, the measure a glyph-alone control takes at the bar's md step. A theme toggle beside it is a ButtonIcon at md, whose mark is drawn at that same measure, and a Quill glyph carries its stroke through any scale — so two marks side by side at different sizes draw different stroke weights, and read as two kinds of control when they are the same kind, a thing a reader sets. The chevron at the other end stays at icon.size.xs because it qualifies the row rather than naming it. Rendered only when `icon` is set.
 - `chevron` — `<span>`, class `dds-navbarswitcher__chevron`. The mark that says this opens. Absent by default, because in a bar this sits among destinations that each carry one and a third would be repetition rather than signal — and present in the panel whatever the page said, because a row in a list gives a reader nothing else to go on. It points along the reading direction there rather than down: what opens is a page beside this one, not a drawer beneath it. Rendered only when `chevron` is set.
 - `surface` — `<div>`, class `dds-navbarswitcher__surface`. The choices. Floating, it is a panel hanging off the trigger. In the panel it covers the destinations and the switchers below them and stops at the header, so the mark and the way out stay on screen while a reader is two levels in.
   
@@ -196,6 +196,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples
 

package/.llm/components/navbarswitcheroption.md

@@ -120,6 +120,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples
 

package/.llm/components/option.md

@@ -158,6 +158,14 @@ The target and the mark are separate decisions, and conflating them is what prod
 
 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.
+- **A component is written along the reading axis, not along the page's left and right** — Every measure, inset and placement in this package names an axis rather than a side: inline-size and block-size, padding-inline and padding-block, inset-inline-start and inset-block-end, margin-inline: auto, text-align: start. Written that way a component follows whichever direction the page is read in, and a band whose claim ranges to the leading edge with its subject on the trailing one is the same composition in Arabic as in English, mirrored, with nothing restated. Written as left and right it is the same pixels in both, which is a layout nobody designed for the second language.
+
+The enum values follow the same rule and for the same reason. A prop that names where a picture sits takes start and end, never left and right — FeatureSplit, FeatureBullets and FeatureScroll all declare mediaPosition that way, and the flex directions they generate flip on their own because row already means the reading order. A value called left would have to be re-read as right by every author working in a mirrored page, which is a translation this system should be doing rather than asking for.
+
+The guidance a contract carries is part of the component, so it follows too. Describing a claim as ranging left is describing one of the two languages, and it was written that way here for a while: three of the opening bands said so in their own intent. A reader in a mirrored page meets that sentence and has to decide whether the component is wrong or the sentence is, and neither answer is one documentation should force.
+
+Two things genuinely have no logical form and are not covered by this. A CSS gradient takes a physical direction — there is no to inline-end — so a pattern that must mirror has to be stated twice under a direction query, and one that is periodic and centred, like PageHeader's rule grid, does not need to. A glyph that points the way onward is the other: an arrow is a picture of a direction, and mirroring it belongs to the icon set rather than to the component holding it.
+  Guidance only — cannot be checked automatically.
 
 ## Anti-examples