@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/cardbody.md

@@ -0,0 +1,409 @@
+<!-- GENERATED from card-body.contract.json. Do not edit. -->
+
+# CardBody
+
+Everything a card holds: the words inset from its edges and the picture that reaches them, in one region. The surface around it keeps a fill and a corner and nothing else. The inset belongs to the words alone rather than to this whole box, which is what lets a photograph meet the corner while a sentence three lines above it does not — one measure cannot serve both, and putting the padding on the copy instead of on the container is how the same component draws both.
+
+## Use when
+
+- Words, a picture, or both inside a Card — a feature and the sentence explaining it, a screenshot under the copy that describes it
+- A photograph, render or screenshot that should reach the card's edges while the copy above it stays inset
+- A picture that should absorb whatever height the copy leaves, so a row of cards ends flush no matter how much each one says
+- A mark above the words — the glyph a feature card leads with, sized and inset with the copy rather than reaching the card's edges
+- Copy that sits over the picture rather than beside it — a photograph as the card's ground, with a title and a sentence washed over it
+- A line above the title filing the card under something — the date an article ran, how long it takes to read, the category it belongs to. It is set in capitals at the eyebrow step, which is what tells it apart from the copy without it needing a colour of its own
+
+## Do not use
+
+- The whole card is one picture, with no words at all → `Card`
+- A surface of its own. It has no fill and no corner: outside a Card it is a stack with padding on part of it, which is a layout rather than a component
+- Copy over a picture with nothing to darken it. `overMedia` paints a ground and a wash under the words and is the only supported way to lay them over art — setting `src` alone puts the picture in the column, under the copy rather than behind it, which is a different card
+- Text baked into the picture. It cannot be selected, translated, or reflowed at the width a phone gives the card — words go in title and description, which are text at a size the type ramp chose
+- Controlling the gap between unrelated blocks. It stacks its copy at one measure, and a page needing two different gaps is composing the stack itself
+
+## Anatomy
+
+CardBody renders 9 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-cardbody`. The whole of the card's content, and no padding of its own. That is the entire trick: the inset sits on `content` one level in, so the picture beside it can reach the card's edges without anything being cancelled back off. A body that padded itself and then pulled the picture out again with a negative margin would be two decisions undoing each other, and neither would be findable from the other.
+  
+  `flex: auto` with `min-block-size: 0`, so the body takes the height the card was given rather than the height its words happen to need. This is what a row of cards depends on: the grid stretches every card to the tallest, the body inherits that height, and the picture inside it absorbs whatever the copy did not use. Without it the body would shrink to its text and the picture would have no slack to take.
+  
+  It stacks at no gap. The space between the copy and the picture is `content`'s own bottom padding, which is already the right measure and already there — a gap on top of it would be a second decision about one piece of space.
+  
+  `position: relative` always, so the layered case has something to pin to, and `display` is the one thing that varies: a flex column while the picture is a region in the flow, a grid once it is the ground behind everything. Under `overMedia` the content is the only child still in the flow — the picture and the wash are pinned to all four edges and out of it — so it lands in the single cell without a template being written for it.
+  
+  Under `overMedia` it paints `color.bg.brand-strong` and takes `color.fg.on-brand-strong`. The ground is never seen while the picture loads, which is the point of it: a photograph that 404s or has not arrived yet leaves white text on whatever was underneath, and the darkest ground the package has is the one that takes white at 20.55:1. It is a floor rather than a guarantee — no wash makes white legible over white, and what answers that is art with somewhere for the words to go.
+- `scrim` — `<span>`, class `dds-cardbody__scrim`. A wash over the picture, so the words have a ground rather than a photograph. Drawn whenever `overMedia` is set — one prop for one decision, rather than a second asking whether the first needs to be legible.
+  
+  Above the picture and below the words, which is markup order: all three are in the same grid cell, and the two pinned layers stack in the order they are written.
+  
+  A <span> rather than a <div> because it is not a region and holds nothing — there is no content here to group, only a colour between two layers. Rendered only when `overMedia` is set.
+- `content` — `<div>`, class `dds-cardbody__content`. The inset region: the mark, the title and the sentence, held off the card's edges so nothing reads as spilling out of the corner. It pads on both axes at `space.inset.lg` and stacks what it holds at `space.gap.sm` — close enough that a title and the sentence under it read as one block. Product's own card body stacks wider; the two packages disagree here and this one follows its own page.
+  
+  Always rendered, even with nothing in it. A conditional region would have to name the one prop that brings it back, and there are three that should — a card with only a description and no title still wants its copy inset. The cost is the case in `useInstead`: a card that is nothing but a picture gets an empty padded band above it, and belongs in a bare Card instead.
+  
+  Under `flush` the inline padding goes and the block padding stays. That asymmetry is the whole point of the prop rather than an oversight in it: the inset exists to hold words off a fill, so a card with no fill has nothing for the inline half of it to do — the picture is the card's edge there, and copy indented from it reads as a mistake rather than as a margin. The block half is answering a different question, the space between a picture and the first line under it, and no change of ground affects that. One prop, two paddings, and only one of them was ever a decision about the fill.
+  
+  It insets by space.inset.card rather than by a step off the generic scale. The generic step held one value at every width, so a card on a phone was padded as generously as one on a desktop while its column was a third as wide; the role comes down with the viewport, and it is a role rather than a size because a row of cards padded differently is a row of different cards.
+  
+  Its gap is space.heading.title-description-compact, which is the section heading group's step at the size a card sets. The relationship is the same one and the number is not, because what the eye reads is the gap plus the leading above it: under a display title the leading is most of it, under a card's title it is half as deep, and one value would make the card look loose where the section looked right. One gap for all three regions is the limit here: an eyebrow wants to sit nearer its title than the title sits to its description, and a single gap cannot say that — the same limit Stack has, and the reason a heading group is not one.
+  
+  The inset has two steps. `space.inset.card` is the one a card in a grid of cards wants; `compact` drops it to `space.inset.md` for a card small enough that thirty-two either side is most of its width — a rail beside a footer's columns is the case it was added for. One axis against the unconditional binding, so the cascade picks the narrower one and Figma is told which.
+- `mark` — `<div>`, class `dds-cardbody__mark`. The glyph the card leads with, above the title. A <div> wrapping whatever was passed rather than an element of its own: Marketing has no Icon yet, so what arrives here is a quill glyph, an inline <svg> or a small <img> depending on the page, and a wrapper is what gives all three the same position without this part claiming to know which it got.
+  
+  It is drawn by `Icon` at `icon.size.lg` — the step whose own description reads "cards and content sections", which is this exact job. The step is the card's rather than the page's: a set of feature cards has to agree about how big their marks are, and Icon unwraps one that arrives already sized so a call site cannot quietly disagree.
+  
+  This used to be sized here instead, and it did not work on its own — every Quill glyph ships width and height attributes, so a box with a measure has no effect on the SVG inside it, and there was an impl sheet reaching into a child to force it. That sheet is gone. A component that owns the SVG needs no rule about somebody else's.
+  
+  `align-self: flex-start`, so the box is as wide as the mark rather than as wide as the card. Stretched, it would be a full-width block whose glyph merely happens to sit at the left, which reads identically until something is centred and cannot be. `display: flex` for the same class of reason: an inline SVG sits on a text baseline and leaves a few pixels under it that look like a spacing bug and are not one.
+  
+  It carries `space.gap.lg` beneath it, which the column's own `space.gap.sm` adds to, so the mark stands off the title by the two together. The column measure is right for a title and the sentence under it, which are one block of copy read as a unit; a mark is not part of that block, and at the column's own measure it reads as a bullet on the heading rather than as the card's own sign.
+  
+  It binds no colour, for the reason the title does not: Card sets one per variant and it inherits, so the same mark is white on the brand fill and near-black on the page. Rendered only when `mark` is set.
+- `eyebrow` — `<p>`, class `dds-cardbody__eyebrow`. The line above the title naming what the card is filed under — a date, a read time, a category. It takes font.eyebrow: twelve pixels, medium, and the wide tracking that setting needs, which is the step this package already uses for a tag above a headline.
+  
+  The capitals are this part's, through `text-transform`, rather than the page's through the string it was handed. That is the whole reason the transform is here: an accessible name is read from the markup, so a month typed as AUGUST reaches a screen reader as a token several of them spell out one letter at a time. Written as August and drawn as capitals, it is announced as a month and shown as a label.
+  
+  A <p> with `margin: 0`, for the reason the description is one — it is a line of text in the copy column, and the column's own gap is what stands it off the title rather than a margin of its own.
+  
+  It binds no colour, which is the decision the title and the description also make and the one most likely to be argued with here. An eyebrow is usually drawn quieter than the copy under it, and color.fg.muted is the role that would say so. But Card sets a colour per variant and this inherits it, so a muted role would hold on the page and fail on the two brand grounds — fg.muted is gray.600, which on color.bg.brand-strong is near-black on near-black. What tells this line apart from the title is its size, its weight and its tracking, and all three survive a change of ground.
+  
+  Muted, and the one part of this body that is. A date, a category, a kind — an eyebrow names which of something this is rather than what it says, so it is read once on the way to the title and not again. The title and the description are the pair the card is actually made of and they share an ink; a third thing in that same ink over them reads as the first line of the card rather than as the tag on it.
+  
+  Not when it sits over media. There the root has already taken the ink the scrim was drawn for, and a grey mixed for a white page laid over a photograph is neither legible nor a step back from anything — it is the one ground where being lighter stops meaning quieter.
+  
+  It is the one part here with an ink of its own, and so the one that has to be told which way round the ground is. Everything else takes the colour the card sets and inherits it; this is deliberately quieter than the copy beneath it, and "quieter" is a different colour on a dark card than on a light one — `color.fg.muted` against an inverse card is 3.08:1. Rendered only when `eyebrow` is set.
+- `title` — `<h3>`, class `dds-cardbody__title`. The card's name. An <h3> because a card most often sits under a section's own h2, and because a title that was a div would leave a page of cards with no structure in it at all — the same choice Dialog, Drawer and BottomSheet make. A page whose cards sit at another depth composes its own heading above the card instead.
+  
+  It takes font.h5, the smallest step the heading scale has and the one this package's cards already used. The level and the size are separate decisions and this part makes both, which is the trade for a consumer not having to know either.
+  
+  It binds no colour. The Card sets one per variant on its root and colour inherits, so a title on the brand fill takes fg.on-solid and the same title on the page takes fg.default without this part knowing which card it is in. Binding a role here would override that and put near-black text on the brand-strong fill.
+  
+  It has two steps. `font.h5` is the default and is a heading over a group of cards; `compact` takes `font.label.md`, sixteen at semibold.
+  
+  That role is described as interactive text — navigation links, form labels, a call to action — and a card's name is none of those. It is the only sixteen-pixel semibold step this package has, and the alternatives are worse: `field-label` at the same size is medium weight and names a form field, and `label-medium` stops at fourteen. A role named for one job doing another is worth writing down rather than leaving for the next reader to wonder at; the honest fix is a step in this scale for the name of a small surface. Rendered only when `title` is set.
+- `description` — `<p>`, class `dds-cardbody__description`. The sentence under the title, at font.body.md — the default body step, because a card's copy is copy rather than a caption. It sits at space.gap.sm from the title, close enough that the two read as one block.
+  
+  A <p>. It binds no colour, for the reason the title does not.
+  
+  It moves with the title. `font.body.md` by default and `font.body.sm` when the card is compact, which keeps the two a step apart — a sixteen-pixel title above sixteen-pixel copy is a card with no heading in it. Rendered only when `description` is set.
+- `media-frame` — `<div>`, class `dds-cardbody__media-frame`. The picture's own box, and the reason a zoom looks like a zoom. An <img> cannot clip itself — `overflow` does not apply to replaced content — so a picture that scales has to be scaled inside something. Without this the nearest clip is the Card's, one level up and around the copy as well, and a picture growing by a per cent pushes its bottom edge down over the eyebrow and the headline. In a body with no card around it at all, nothing clips it and it simply paints over whatever is below.
+  
+  So the frame holds the shape and the picture moves inside it: the box keeps its place in the column while the art grows past its edges and is cut off at them, which is the whole effect.
+  
+  It is drawn whenever there is a `src`, rather than only when `zoomOnHover` is set. A part that appeared with the zoom would be a second thing the prop did, and the layout role has to move here either way — the frame is what now takes the height the copy leaves, and the picture fills it. One shape for every card with a picture is cheaper to reason about than two.
+  
+  It carries the flex sizing the media used to: `flex: auto` with `min-block-size: 0`, so it absorbs whatever height the copy did not use, and `aspect` is applied here rather than to the picture, being a fact about the box rather than about the art in it. Rendered only when `src` is set.
+- `media` — `<img>`, class `dds-cardbody__media`. The picture, reaching the card's edges because nothing above it in this box has padding to keep it off them. The corner is Card's, drawn by its overflow, which is why this meets a rounded edge rather than squaring one off.
+  
+  `display: block`, which is the decision a page most often gets wrong on its own. An img is inline by default, so it sits on a text baseline and leaves a strip of the card's fill beneath it that looks like a spacing bug and is not one — no gap token is involved, and no amount of hunting through the padding finds it.
+  
+  It fills `media-frame` at 100% in both axes and sizes nothing itself. The `flex: auto` and `min-block-size: 0` that used to be here are the frame's, which is the element in the column now: a flex item will not shrink below its content size without the second of those, and an image's content size is its natural height, so a tall photograph would otherwise push the card open from the inside. Product's banner learned this the hard way and took its art out of the flow entirely; here the frame stays in the column and is allowed to shrink instead.
+  
+  `object-fit: cover`, because a region whose height is decided by something else cannot also honour the picture's own proportions. Cover crops; the alternative letterboxes, which shows the card's fill at two edges of a picture asked to reach them.
+  
+  It binds `radius.none`, which is a decision rather than a default. Avatar's image rounds itself, at `radius.pill`, because the status mark at its corner means its root cannot hide its overflow. This is the same property argued the other way: the clip belongs to Card, so rounding here would curve the two corners the card already curved and leave the two in the middle of the column square.
+  
+  It binds no ground. A render with transparency is meant to sit on the card's own fill — the coral behind a rosette, the near-black behind a shield are the Card's — and a fill of its own would paint a rectangle over the bottom half of the card.
+  
+  Under `zoomOnHover` it grows by `motion.scale.media-hover` while the pointer is over the body, and `media-frame`'s `overflow: hidden` is what makes that read as anything: the frame holds still and the art moves inside it. The card's own clip is one level further out and around the copy as well, which is why it could not do this job — see the frame's own description. CSS's own `scale` property rather than a `transform`, which is what CardButton's lift already uses for its `translate` — the two are independent properties, so a card could in principle do both without either having to know the other's matrix. It does not, and that is a decision rather than a limitation: CardButton drops its lift whenever the body it holds zooms, on every variant, so one gesture moves one thing.
+  
+  The rule itself is in the impl sheet, because the contract cannot hold its shape. A state bound on a part emits hover on that part — `.dds-cardbody__media:hover` — which would zoom the picture only while the pointer was on the picture, and leave it still when the pointer was on the headline of the very same card. What is wanted is the root's hover reaching one of its own children, and there is no vocabulary for that here. Rendered only when `src` is set.
+
+Apply these classes from the generated `cardBodyParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `Card`, `CardBody` — in children or in any prop that takes a node
+
+## Props
+
+### overMedia — `boolean` (default `false`)
+
+Use when: The picture is the card's ground and the copy is read on top of it. Set explicitly rather than inferred from src, which BannerBody can afford to do and this cannot: there, art is always behind the words, so having art and being over it are the same fact. Here a picture is a region in the column by default, and the same src means two different cards
+Never for: Making a card look richer. It forces the dark ground and the light ink on every word in the body, so a title that was near-black on the page turns white — and over a pale photograph with no wash strong enough to hold it, that is the least legible card on the page rather than the most striking
+
+### flush — `boolean` (default `false`)
+
+Use when: The card has no fill for the copy to be held off — Card's `plain` variant, where the picture is the card's edge rather than the ground being it. The inline inset goes and the copy lines up with the picture above it; the block padding stays, because the space between a picture and the line under it is still doing its job
+Never for: A filled card. The inset is what keeps the words off the ground's edge, and on surface, accent or accent-strong removing it puts a headline hard against the colour — which is the one way a card looks broken rather than merely tight.
+
+It is paired with variant="plain", and the two are set together or neither is: a plain card that is not flush reads as copy indented from its own picture, and a flush card that is not plain reads as text spilling out of a fill. Nothing can check the pair, because the ground is the Card's prop and the inset is this one's, and neither component can see the other.
+
+### zoomOnHover — `boolean` (default `false`)
+
+Use when: The card is pressable and its picture is what answers the pointer — an editorial card inside a CardButton, on any ground. The picture grows by motion.scale.media-hover and media-frame clips it, so what the reader sees is the frame holding still while the art moves inside it. Setting this is also what stops the card lifting: CardButton suppresses its own lift when the body it holds zooms, so the two motions never compete
+Never for: A card that is not pressable. Motion under the cursor is how a surface says it responds to a press, and on a plain Card — a div with no role — it says that to a mouse user about something that does nothing, while telling a keyboard user nothing at all, since there is no hover without a pointer and no focus without a control. Inside a CardButton the same movement is decoration on a real target that already has a focus ring.
+
+Not every card with a picture, either. This is the editorial card's motion, and a row of feature tiles that all zoom is a page where nothing is being pointed out.
+
+### compact — `boolean` (default `false`)
+
+Use when: The card is small enough that the standard inset and the standard type are most of it. `space.inset.card` is thirty-two, which is a fifth of the width of a rail beside a footer's columns; `font.h5` is twenty-four, which is a heading over a group of cards rather than the name of one two hundred pixels wide.
+
+This takes the inset to `space.inset.md`, the title to `font.label.md` and the description to `font.body.sm` — sixteen and fourteen, where the standard card runs twenty-four and sixteen. The pair moves together: dropping the title alone would put a heading two pixels above its own body copy.
+
+It is about the card's size rather than its importance. A compact card is not a lesser one.
+Never for: Fitting more words into a card that is too small for them. The inset is not what is wrong with a card whose copy will not fit — taking sixteen pixels off each side buys one word a line and leaves the same card overfull
+
+It does not undo `flush`. A flush card has no inline inset at all — the copy lines up with the picture above it — and the two together keep that: the compact inline step names `flush: false`, so the wider rule cannot win on source order alone. The block inset still narrows, which is what `flush` leaves alone anyway.
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The card is on the page, which is nearly every card
+- `inverse` — The card sits on a band that paints its own dark ground, and carries `tone="inverse"` itself. The eyebrow takes the inverse muted ink so it stays quieter than the copy without falling below what a reader can make out
+
+Use when: Which way round the ground under it is, and it pairs with Card's prop of the same name for the reason `compact` does: the box and its contents are separate components, and only the page knows it has put one inside the other.
+
+Only the eyebrow reads it. Everything else here takes the ink the card sets and inherits it — the eyebrow is the one part with a colour of its own, because it is quieter than the copy beneath it, and `color.fg.muted` is quieter than dark text on a light card rather than quieter than anything. On a dark card it comes to 3.08:1, which is a line a reader with low vision is asked to take on trust.
+Never for: Setting it on one of the pair and not the other. A card whose ground is inverse and whose body is not has one line in an ink chosen for a page it is not on
+
+### eyebrow — `string`
+
+Use when: The card is filed under something a reader scans before the headline — the date an article ran, how long it takes to read, the category it sits in. Write it in the case it should be read in: the part draws the capitals itself, so 'August' is what belongs here and AUGUST is what appears
+Never for: A sentence, or a second headline. It is set at twelve pixels with wide tracking, a measure chosen for three or four words and a wall at the length of a clause — what the card is about is the title's job.
+
+Nor a status or a count. It paints no ground and binds no colour, so it cannot say 'New' or '2 left' the way a filled pill does; it is a filing label at the body's own ink, and a reader scanning a column of cards reads it as one.
+
+### title — `string`
+
+Use when: The card names what it is about. A noun phrase rather than a sentence — 'Balance protection', not 'We protect your balance' — because it is read as a label on the block beneath it. A string rather than a node: a node could carry a mark or a link, and would cost the component its examples — the checker requires a named element there, so no row could ever show a card with real copy in it.
+Never for: The sentence explaining the card. That is description, which sits under this at a gap close enough that the two read as one block. A title that runs to a sentence leaves the copy with nothing to add
+
+### description — `string`
+
+Use when: What the title means, usually a sentence or two. It takes the default body step, because a card's copy is copy rather than a caption. A string rather than a node, for the reason the title is one — a node prop cannot be given text in an examples row, and a card nobody can show is worse than a sentence that cannot hold a link.
+Never for: A control. This body holds two regions and neither is a place to act from — a card with a call to action puts it in the Card beneath this, where it is not wearing the body's copy styling
+
+### mark — `node`
+
+Accepts: Icon
+Use when: The card leads with a glyph — a badge, a shield, a small piece of art that makes the feature recognisable before the title is read. Set it on every card in a set or on none of them: one card in a row carrying a mark reads as the important one, which is a claim the mark was not meant to make. Pass the glyph; the body draws it at its own step, and an Icon passed already sized is unwrapped rather than obeyed
+Never for: A picture that should reach the card's edges. This is inset with the copy and sized to sit above a heading; a photograph put through it is a stamp in the corner of a wide margin. That is src, which renders the media region below or above this whole block rather than inside it
+
+### src — `string`
+
+Use when: The card shows a picture — a photograph, a product render, a screenshot of the thing being described. Absent is the ordinary case: most cards are words
+Never for: A data URI holding a photograph. A card's picture is the heaviest thing on a marketing page and inlining it costs the page its cache; a path belongs here, and the formats and sizes behind it are the page's build to decide
+
+### alt — `string`
+
+Use when: Whenever src is, and empty when the picture says nothing the copy has not already said. A decorative render beside a title naming it — a shield next to 'Integrity' — takes alt="", which tells a screen reader to skip it rather than read a filename aloud. A photograph carrying meaning of its own takes a sentence describing what it shows
+Never for: Repeating the card's title. The reader heard it from the heading a moment earlier, and hearing it twice is how a decorative image makes a card worse than one with no image at all. If the sentence you would write is the title, the right value is the empty string.
+
+Nothing enforces that this is set when src is, and it is worth knowing why rather than assuming an oversight. The rule exists in the vocabulary — a `null` consequent is how one prop obliges another — but `null` there matches undefined, null and "" alike, on the argument that a label of "" puts no button on screen and so obliges nothing. That argument does not survive contact with alt, where "" is not absence but the decision to say nothing, and is the correct answer for every decorative render in these cards. Written as a rule it would fail exactly the examples that teach the right thing, so it is written here instead and repeated in the accessibility requirements.
+
+### aspect — `number`
+
+Use when: The picture must hold a known shape rather than absorb the card's spare height — a logo that distorts the moment it is cropped, or a chart whose proportions are the point. Written as the division rather than the result, so the shape is legible: aspect={16 / 9}, not aspect={1.7778}
+Never for: A row of cards that should end flush. Setting this stops the picture absorbing the height the copy leaves, so a card whose title runs to two lines grows taller than its neighbours and the row goes ragged. Absent is right for almost every card in a set
+
+### mediaPosition — `below` | `above` (default `below`)
+
+- `below` — The copy introduces the picture — a feature named and explained, then shown. The ordinary case, and what a reader scanning a column of cards is reading for
+- `above` — The picture is what the reader recognises the card by and the words caption it — a photograph leading an article, a screenshot the copy then describes. Changes the order of the elements themselves rather than only their appearance, so what a screen reader hears follows what the page shows
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- A card that sets src sets alt too, and sets it to the empty string when the picture is decorative. An img with no alt attribute announces its filename; alt="" is the deliberate silence, and the two are not the same thing to anything reading the page aloud.
+- Copy the reader has to be able to select, translate or reflow does not go in the picture. A card's words belong in title and description, where they are text at a size the type ramp chose; baked into an image they are pixels a phone shrinks along with everything else.
+
+## 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
+
+❌ CardBody for: The whole card is one picture, with no words at all
+   This is a body, and it draws its inset region whether or not anything was put in it — a card with no copy gets a band of empty padding above the picture. A picture that is the entire card goes straight into the Card, which pads nothing and clips the corner itself
+   → use `Card` instead.
+
+## Example
+
+```tsx
+import { CardBody } from '@deriv-com/dds-marketing'
+
+<CardBody title="Balance protection" description="Protect your account from unexpected market swings, with no action needed on your part." />
+```
+
+## In use
+
+### What a body holds
+
+Every region appears only once it is given something. A card with no description is a title with nothing under it rather than a title and an empty line holding space open.
+
+```tsx
+import { CardBody, Icon } from '@deriv-com/dds-marketing'
+import { MemoCircleCheckRegularIcon } from '@deriv-com/quill-icons-web'
+
+// A title on its own
+<CardBody title="Tight spreads" />
+
+// A title and the sentence under it
+<CardBody title="Tight spreads" description="Competitive pricing on every market, with no hidden markup." />
+
+// An eyebrow filing it under a date
+<CardBody eyebrow="14 August 2026" title="A bank can bank your IPO and still refuse your account" />
+
+// A mark above the words
+<CardBody mark={<Icon size="xs"><MemoCircleCheckRegularIcon /></Icon>} title="Be reliable" description="We settle all contracts fairly and process every withdrawal promptly." />
+```
+
+### The eyebrow
+
+A short label above the title — a date, a read time, a category. The capitals are the stylesheet's, not the string's, so a screen reader hears the case it was written in. It binds no colour.
+
+```tsx
+import { CardBody } from '@deriv-com/dds-marketing'
+
+// A date
+<CardBody eyebrow="14 August 2026" title="A bank can bank your IPO and still refuse your account" />
+
+// A read time, over a headline and its summary
+<CardBody eyebrow="3 min read" title="When a boss hypes the boom that sells his product" description="Nvidia's boss says AI has arrived, but insiders sold shares and a top customer is building its own chips." />
+
+// The same card without one
+<CardBody title="When a boss hypes the boom that sells his product" description="Nvidia's boss says AI has arrived, but insiders sold shares and a top customer is building its own chips." />
+
+// Over the picture — it takes the light ink with the rest
+<CardBody overMedia eyebrow="Technology" title="Tech stocks" description="Companies that lead the charge in digital evolution and breakthroughs." src="/sample-card-image.svg" alt="" />
+```
+
+### Where the picture goes
+
+The copy is inset and the picture is not, which is how both live in one body. mediaPosition reorders the elements themselves, so a screen reader hears what the page shows.
+
+```tsx
+import { CardBody } from '@deriv-com/dds-marketing'
+
+// below — the copy introduces the picture
+<CardBody title="Teamwork" description="We value team players that collaborate freely across departments." src="/sample-card-image.svg" alt="Two colleagues talking over a laptop in an open-plan office." />
+
+// above — the picture leads and the words caption it
+<CardBody title="Teamwork" description="We value team players that collaborate freely across departments." src="/sample-card-image.svg" alt="" mediaPosition="above" />
+```
+
+### Copy over the picture
+
+overMedia takes the picture out of the column and makes it the ground. It paints a dark fill and a wash under the words, so the copy has something to be read on if the art does not answer for it.
+
+```tsx
+import { CardBody } from '@deriv-com/dds-marketing'
+
+// overMedia — the picture is the ground
+<CardBody overMedia title="Teamwork" description="We value team players that collaborate freely across departments." src="/sample-card-image.svg" alt="" />
+
+// The same picture in the column, for comparison
+<CardBody title="Teamwork" description="We value team players that collaborate freely across departments." src="/sample-card-image.svg" alt="" />
+
+// overMedia with no picture — the ground it falls back to
+<CardBody overMedia title="Teamwork" description="We value team players that collaborate freely across departments." />
+```
+
+### Flush, for a card with no fill
+
+The inline inset holds words off a fill. On Card's `plain` variant there is none, so the picture marks the edge, and `flush` drops that half of the padding to meet it.
+
+```tsx
+import { CardBody } from '@deriv-com/dds-marketing'
+
+// flush — the copy meets the picture's edge
+<CardBody flush src="/sample-card-image.svg" alt="" mediaPosition="above" aspect={1.7777777777777777} eyebrow="14 August 2026" title="A bank can bank your IPO and still refuse your account" />
+```
+
+### Two sizes of card
+
+Thirty-two of inset with a twenty-four title over sixteen copy is right for a feature card in a grid. On a rail beside a footer it is most of the card, so all three step down together.
+
+```tsx
+import { CardBody } from '@deriv-com/dds-marketing'
+
+// standard — inset 32, title 24, copy 16
+<CardBody title="Deriv App" description="Manage accounts, transfer funds, and access markets anytime, anywhere." />
+
+// compact — inset 16, title 16, copy 14
+<CardBody compact title="Deriv App" description="Manage accounts, transfer funds, and access markets anytime, anywhere." />
+```
+
+### Which way round the ground is
+
+Only the eyebrow reads this. Everything else takes the ink the card sets; the eyebrow has one of its own, and quieter is a different colour on a dark card than on a light one.
+
+```tsx
+import { CardBody } from '@deriv-com/dds-marketing'
+
+// default — the eyebrow at color.fg.muted
+<CardBody eyebrow="New" title="Deriv App" description="Manage accounts and access markets anytime." />
+
+// inverse — it follows the dark ground
+<CardBody tone="inverse" eyebrow="New" title="Deriv App" description="Manage accounts and access markets anytime." />
+```