@deriv-com/dds-marketing 0.1.0 → 1.0.0

package/.llm/components/buttonicon.md

@@ -0,0 +1,321 @@
+<!-- GENERATED from button-icon.contract.json. Do not edit. -->
+
+# ButtonIcon
+
+One press carried by a glyph alone, in the space a label would need. What the press does decides the element: an `<a>` when it is given an href, a `<button>` when it is not — the fork CardButton already settled in this package, and for the same reason, that a control going to a page and a control the page handles itself are the same gesture with different destinations, and the element is what tells a browser which. The glyph is decorative to a screen reader; the name the control is announced by comes from `label`, which is never drawn, so the control is named for everyone whether or not the shape happens to be legible to them. This is the gap Button names in its own guidance: Button's words are both its accessible name and its destination, and a glyph alone has nowhere to put either.
+
+## Use when
+
+- One press with no room for words — a promotional bar's dismiss, a hero's play control, a carousel step, a footer's social links. Whether it navigates or acts in place is decided by href alone, so the same component covers both
+- A row of glyph-alone destinations where words would only repeat — social accounts in a footer, app stores in a download band, a region switch in a header
+- A control the page owns rather than a destination — dismissing a promotional bar, playing a hero video, advancing a carousel, opening a mobile nav. Leave href off and it is a button, which answers Space and fires what the page says
+- The glyph is one a visitor reads without being taught — a play triangle, a dismiss cross, a chevron, a social mark in its monochrome cut. A marketing page gets no onboarding and usually no second visit to learn in
+- Room is genuinely short and the words would be the same words several times over. One of these on its own beside prose is usually a Button that lost its label
+
+## Do not use
+
+- The control has words, or needs them to be understood → `Button`
+- The whole surface is the target — a card standing for a feature, a market or a plan → `CardButton`
+- The mark is an ornament rather than a control → `Icon`
+- The mark reports a state the visitor sets and reads back — sound on or off, a light and dark switch → nothing here does this
+- A glyph whose meaning arrives only from a tooltip. Hover does not exist on a touch screen and a marketing page is read on a phone as often as not, so that explanation reaches only some of the people who need it
+- The call to action the page exists to produce. That step is named rather than drawn, which is Button — a visitor deciding whether to convert should not have to decode a shape first
+- A placeholder href while the destination is undecided. Given one this becomes a real anchor, so a # or an empty string is a control that looks live, offers to open in a new tab and goes nowhere
+- Several glyphs in one control, or a glyph beside a count. One control, one action, one shape; anything else is a Button whose label happens to be short
+
+## Anatomy
+
+ButtonIcon renders 2 elements. A token binding names the part it applies to.
+
+- `root` — `<button>`, class `dds-buttonicon`. The control, and the whole of what this component decides. An `<a>` when given an href and a `<button>` when not, exactly as CardButton does it: one answers Space and does what the page says, the other gives cmd-click, a destination in the status bar and a link that can be copied and crawled. Two components for that would be two names for one gesture, and this package already made that call once.
+  
+  A fixed square from the control ramp rather than a box its contents size — both steps of the control ramp stand well clear of size.target.min, so nothing here needs a minimum bound on top. Fixed is what makes the glyph swappable: a circle that grew with its mark would change size between a chevron and a social mark, and a row of them would step up and down.
+  
+  radius.pill rather than radius.control, so it is a circle. On a square box the pill radius and a full round are the same thing, and it is the shape Button takes — a glyph-alone control beside a pill CTA reading as a different family of control would be this package disagreeing with itself over one press.
+  
+  It carries the variant and the size, so the fill, the square and the mark inside it all follow one decision. Its own structural keywords are the contract's top-level staticCss, which is where the root's belong.
+  
+  There is no label part, because nothing is drawn: the accessible name is an attribute rather than a hidden span. And there is no loading state, which is the one place this leaves product's ButtonIcon behind rather than following it — an anchor has no honest pending state, the browser owning that and showing it in the chrome, so a spinner here would be correct on the button branch and a lie on the other.
+  
+  It sets its own colour on every variant rather than letting one inherit, which the anchor makes necessary: a `<button>` takes the text colour around it and an `<a>` does not — it takes the browser's link blue, and the glyph goes with it through currentColor. CardButton records the same finding, arrived at the same way.
+  
+  It can be told which ground it is on. `plain` is the variant that paints nothing of its own, which makes it the one that reads whatever is behind it — and a near-black mark on a bar standing on a dark hero is a control nobody can see. The tone moves the ink and the two tints and stops there. The focus ring moves at every variant, because a ring the colour of the ground is no ring at all whatever the mark inside it is doing.
+- `icon` — `<svg>`, class `dds-buttonicon__icon`. The mark, which is a Quill glyph the caller passes rather than a shape this component draws. The part class goes on the `<svg>` itself, not on a box around it, because that is where icon.control.* has to land: every glyph in the icon package ships width and height presentation attributes defaulting to 24, and sizing a parent does nothing to them — a CSS length is what beats an attribute. Marketing Button puts its arrow's class in the same place, and product's Icon clones for this exact reason and records it.
+  
+  The glyph arrives through a prop as an element already built, so the implementation clones it to add the class rather than wrapping it. A wrapper was the first shape here and was wrong twice over: it left the mark at whatever size the package shipped, and the hand-written rule that pulled it back to the box's measure was a second place the size was decided.
+  
+  It carries icon.control.md and icon.control.lg — the same two steps Button gives the arrow beside its label, so a glyph moved from beside words into a circle does not change size on the way. Those steps were cut to clear a label's line box and there is no label here, which reads as a coincidence and is not one: what they fix is the mark's rank against the control around it, and that is the same question in a circle. Which is also why the step is bound here rather than handed to Icon, as Badge and Tab hand theirs: Icon draws from icon.size, whose steps are 16 and then 20, while the control ramp is 18 and then 20 — so an md control has no step to ask Icon for. Rounding it to either neighbour would put a glyph-alone control's mark a measure away from the same glyph beside a label in the same band, which is the disagreement this component's own guidance argues against.
+  
+  It takes the control's colour through currentColor, which is what makes one glyph correct on a brand fill and on an inverse one alike, and it never shrinks. It is aria-hidden in the implementation: it names nothing, `label` having already named the control, and announced it would repeat that on every one of these in a row.
+
+Apply these classes from the generated `buttonIconParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `Button`, `ButtonIcon`, `Card`, `CardButton`, `CardBody`, `Breadcrumb`, `BreadcrumbItem` — in children or in any prop that takes a node
+
+## Props
+
+### variant — `primary` | `secondary` | `inverse` | `plain` (default `primary`)
+
+- `primary` — The one glyph-alone press a section is built around — a play control over a hero, the single action a band exists for. Carries the brand fill, which is what makes it findable at a glance and what makes it meaningless once there are two.
+- `secondary` — The ordinary case for these, because they usually arrive several at a time — a footer's social row, a carousel's two directions, a bar's dismiss. Button's secondary, drawn as a circle: the lightest tint the ramp offers, color.bg.subtle, with hover and press layered over the fill as a background-image rather than replacing it, so a glyph-alone control and a labelled one beside it read as one family. On the dark band, tone="inverse" keeps the fill and turns it white.
+- `inverse` — A section that paints its own ground — a brand-coloured band, a photo, a dark takeover. There the brand fill is invisible against the fill behind it and a neutral tint is lost over a photograph, so the only thing that reads is a solid at the far end of the neutral ramp: pure black in light, pure white in dark. It outranks everything near it, which is what makes it right there and wrong anywhere else.
+- `plain` — The control sits on a surface that has already said what it is — the exit on a sheet, a step in a set of marks — and a tint behind it would be the loudest thing there. It keeps the target and the states and gives up only the fill, so what a reader presses is unchanged and what they see is the glyph.
+
+Use when: Deciding how much of the section one press claims. The three tiers are Button's three, deliberately — a glyph-alone control and a labelled CTA in the same band have to rank against each other, and they cannot do that in two vocabularies.
+Never for: Ranking a row of these against each other. A footer's five social links are peers; one of them drawn heavier says the other four are lesser, which is not a thing anybody meant to say. And never inverse on the ordinary page ground: against it the fill carries roughly six times the contrast of the brand, so the primary beside it stops reading as the primary and one-primary-per-view is broken with no second primary anywhere in sight. And never for a control that has to be found rather than recognised: with no fill, a plain one is a glyph until it is hovered, so it belongs where the reader already knows something is — a corner, a row of marks, the end of a header — and not adrift on a page.
+
+### size — `sm` | `md` | `lg` (default `md`)
+
+- `sm` — A dense row of controls — a filter bar, a utility strip, a compact carousel. A square of size.control.sm holding a mark at icon.control.sm. Desktop only: at thirty-two it is below what a finger reliably hits.
+- `md` — The default, and nearly everywhere — footers, navigation bars, promotional bars, carousels. A square of size.control.md holding a mark at icon.control.md, which is the measure Button's label-side glyph takes at the same step.
+- `lg` — One prominent press, usually the only control in view — a play control over a hero, a single action in a conversion band. A square of size.control.lg holding a mark at icon.control.lg. One per page, in the same spirit as Button's own lg.
+
+Use when: Matching the control to the density of the band it sits in, which on a marketing page is set by the section rather than by the control.
+Never for: Making one of a set stand out. Two of these side by side at different steps read as a control and its afterthought, and a carousel whose next is larger than its previous has said the path runs one way.
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The control is on a light ground, which is every surface this package paints by default
+- `inverse` — The control stands on the dark band, color.bg.brand-strong — a mark in a navigation bar on a hero, a social mark in a footer — which is the same near-black in light and dark. The ink and the tints move to the band's fixed roles; nothing else does
+
+### icon — `node` **Required.**
+
+Accepts: QuillSystemIcon
+Use when: Always — the glyph is the whole control, so it is required rather than a slot that may be empty. Pass the glyph itself, from the icon package, rather than one already sized: the size a mark takes in this circle is this component's decision, at icon.control.md on md and icon.control.lg on lg, and the width and height the glyph shipped with are overridden by the class this component clones onto it.
+Never for: A glyph whose meaning the visitor has to be taught, and never a second glyph — one control, one action, one shape. Nor a mark carrying a fill of its own: the icon set ships its social marks in both cuts, and only the monochrome one works here — LinkedinInIcon and InstagramIcon paint with currentColor, while LinkedinBlackIcon and the *BrandIcon family hard-code theirs, so they ignore the variant's colour and a black mark lands on the inverse tier's black fill. Nor a picture: a logo lockup or a photograph in a circle this size is an image asking to be a mark and failing at both.
+
+### label — `string` **Required.**
+
+Use when: Always. It is the entire accessible name, because nothing on screen carries one — the words that would have been the label if there had been room for one. Required rather than optional: an optional name on a control that draws none is a control that ships unnamed. On the anchor branch it names the destination; on the button branch it names what happens.
+Never for: Describing the picture rather than what the press does — "cross" instead of "Close", "triangle" instead of "Play the tour". And not the gesture either: a footer of links announced as "click here" names nothing, which is the requirement Button's own guidance already sets for its words.
+
+### href — `string`
+
+Use when: The press goes somewhere with a URL of its own — a social account, an app store, another page. It makes this an anchor rather than a button, which is what gives a visitor cmd-click, a visible destination and a copyable link, none of which mean anything for a press the page handles itself. This is the ordinary case on a marketing page.
+
+`target` and `rel` are not props of this component and do not need to be: it is typed against AnchorHTMLAttributes, so `target="_blank"` and `rel="noopener noreferrer"` are already in reach and land on the anchor. A destination leaving the site is common enough here that the pairing is the page's decision rather than an axis of this component, which is the ruling Button recorded first.
+Never for: A press the page handles itself — a dismiss, a carousel step, opening a video in place. An anchor with an href nothing can navigate to is a promise the browser will try to keep.
+
+Also accepts everything from `AnchorHTMLAttributes<HTMLAnchorElement>`.
+
+## 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 row of social accounts in the page footer** — `variant="secondary"` `size="md"`, not `variant="primary"`
+  These are destinations a visitor looks for rather than ones the page pushes, and there are several of them at once. The brand fill repeated five times across a footer is five primaries, which is the one-primary-per-view rule broken by a row nobody would call a call to action. Secondary keeps the circle and the target and gives up the fill.
+- **Dismissing a promotional bar or a cookie band** — `variant="secondary"` `size="md"`
+  It is a button rather than an anchor — leave href off — because the page handles the press itself and nothing about it is a place a visitor could bookmark. Secondary rather than primary: the bar's own call to action is the primary, and a dismiss that outranks it is a band arguing with itself.
+- **Playing a video in a hero, or over a photograph** — `variant="inverse"` `size="lg"`, not `variant="primary"`
+  A brand fill is invisible against a brand ground and a neutral tint is lost over a photograph, so the only thing that reads there is a solid at the far end of the neutral ramp. lg because it is the one control in view and it is read at a distance, which is the case size.control.lg was cut for.
+- **The previous and next controls of a carousel** — `variant="secondary"` `size="md"`, not `size="lg"`
+  A pair of peers, sized by the band they sit in rather than by themselves. lg stands a step taller than md, which puts it above the copy beside it in most bands — the one place a hero measure is wrong. Both take the same variant, because one of two directions drawn heavier says the other is unavailable.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- Announced as: `button`
+- `Tab` — move focus. One stop, on the control itself — there is nothing inside it to reach, the glyph being hidden from the accessibility tree
+- `Enter` — press it. A button and an anchor both answer Enter, so this reads the same either way
+- `Space` — press it, where it is a button. An anchor does not answer Space, and that difference belongs to the element rather than to this component — a visitor who knows the difference is told which by how it was announced
+- accessible name
+- focus-visible ring
+- a label naming what the press does rather than what the glyph looks like, because a picture named after itself tells a screen reader user the one thing they cannot use
+- the glyph hidden from the accessibility tree. It restates the control the element already announces, and a footer row of these would repeat that on every one
+- an href that resolves, wherever one is given — an anchor without a real destination is announced as a link and goes nowhere, and one with no href at all is neither focusable nor announced as a link, so the control disappears for anyone not using a mouse
+
+## 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.
+- **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
+
+❌ ButtonIcon for: The control has words, or needs them to be understood
+   A glyph a visitor has to interpret unaided is a label the page failed to write. Button also gets its accessible name from its own children, so the words do two jobs there — they name the control and they say where it goes — and a marketing page is read by someone deciding whether to stay, who will not stop to work out a picture
+   → use `Button` instead.
+
+❌ ButtonIcon for: The whole surface is the target — a card standing for a feature, a market or a plan
+   That press belongs to the surface rather than to a control sitting on it, and one of these inside a CardButton is a button inside a button, which no-nested-interactive refuses. The two components share this component's href fork on purpose; what differs is how much of the page is the target
+   → use `CardButton` instead.
+
+❌ ButtonIcon for: The mark is an ornament rather than a control
+   This takes focus, sits in the tab order and announces itself as a control, so an ornament made into one puts a stop in the keyboard order that does nothing when it is reached. A decorative mark is Icon, which draws a glyph at a token step and takes no press at all.
+   → use `Icon` instead.
+
+❌ ButtonIcon for: The mark reports a state the visitor sets and reads back — sound on or off, a light and dark switch
+   A button reports an event and a toggle reports a value, so the change would be announced as an action rather than as a new setting, and one glyph meaning two things cannot say which one it currently is. Nothing here covers that; it needs its own component, the way product has Switch
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+## Example
+
+```tsx
+import { ButtonIcon } from '@deriv-com/dds-marketing'
+import { PlaySolidIcon } from '@deriv-com/quill-icons-web'
+
+<ButtonIcon label="Play the product tour" icon={<PlaySolidIcon />} />
+```
+
+## In use
+
+### Tiers
+
+How much of the section one press claims. Primary for the press a band is built around, secondary for a set of peers, inverse on a painted ground, plain where the surface already says what it is.
+
+```tsx
+import { ButtonIcon } from '@deriv-com/dds-marketing'
+import { PlaySolidIcon, XmarkRegularIcon } from '@deriv-com/quill-icons-web'
+
+// Primary — the press a band is built around
+<ButtonIcon variant="primary" label="Play the product tour" icon={<PlaySolidIcon />} />
+
+// Secondary — the ordinary case, and the one that repeats
+<ButtonIcon variant="secondary" label="Dismiss this offer" icon={<XmarkRegularIcon />} />
+
+// Inverse — on a brand band, a photo or a dark takeover
+<ButtonIcon variant="inverse" label="Play the product tour" icon={<PlaySolidIcon />} />
+
+// Plain — where the surface has already said what it is
+<ButtonIcon variant="plain" label="Close" icon={<XmarkRegularIcon />} />
+```
+
+### Steps
+
+Three squares from the control ramp, each holding the mark Button gives its own glyph at that step. md is nearly everywhere; lg is one prominent press; sm is a dense desktop row.
+
+```tsx
+import { ButtonIcon } from '@deriv-com/dds-marketing'
+import { ChevronLeftRegularIcon } from '@deriv-com/quill-icons-web'
+
+// sm — a dense row, desktop only
+<ButtonIcon size="sm" variant="secondary" label="Previous market" icon={<ChevronLeftRegularIcon />} />
+
+// md — the default step
+<ButtonIcon size="md" variant="secondary" label="Previous market" icon={<ChevronLeftRegularIcon />} />
+
+// lg — one step up
+<ButtonIcon size="lg" variant="secondary" label="Previous market" icon={<ChevronLeftRegularIcon />} />
+```
+
+### A destination, or a press
+
+href decides the element. With one it is an anchor and the browser navigates; without one it is a button and the page handles the press itself.
+
+```tsx
+import { ButtonIcon } from '@deriv-com/dds-marketing'
+import { BarsRegularIcon, LinkedinInIcon } from '@deriv-com/quill-icons-web'
+
+// With href — an anchor. Cmd-click opens a tab
+<ButtonIcon variant="secondary" href="https://www.linkedin.com/company/deriv" label="Deriv on LinkedIn" icon={<LinkedinInIcon />} />
+
+// Without href — a button. Answers Space, acts in place
+<ButtonIcon variant="secondary" label="Open the menu" icon={<BarsRegularIcon />} />
+```
+
+### A row of peers
+
+Social accounts in a footer: several at once, all one tier. One drawn heavier would say the other two are lesser, which is not something anybody meant to say.
+
+```tsx
+import { ButtonIcon } from '@deriv-com/dds-marketing'
+import { FacebookFIcon, InstagramIcon, LinkedinInIcon } from '@deriv-com/quill-icons-web'
+
+// LinkedIn
+<ButtonIcon variant="secondary" href="https://www.linkedin.com/company/deriv" label="Deriv on LinkedIn" icon={<LinkedinInIcon />} />
+
+// Instagram
+<ButtonIcon variant="secondary" href="https://www.instagram.com/deriv_official" label="Deriv on Instagram" icon={<InstagramIcon />} />
+
+// Facebook
+<ButtonIcon variant="secondary" href="https://www.facebook.com/deriv" label="Deriv on Facebook" icon={<FacebookFIcon />} />
+```
+
+### Which ground the mark is on
+
+Plain paints nothing of its own, so what is behind it decides whether the mark can be seen at all.
+
+```tsx
+import { ButtonIcon } from '@deriv-com/dds-marketing'
+import { PlaySolidIcon } from '@deriv-com/quill-icons-web'
+
+// default — a light surface
+<ButtonIcon label="Play the product tour" icon={<PlaySolidIcon />} variant="plain" />
+
+// inverse — a bar on a dark hero
+<ButtonIcon label="Play the product tour" icon={<PlaySolidIcon />} variant="plain" tone="inverse" />
+```