@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/card.md

@@ -0,0 +1,313 @@
+<!-- GENERATED from card.contract.json. Do not edit. -->
+
+# Card
+
+A surface that holds content belonging together. The marketing page is white and this is a step off it, so a card is told apart by being recessed rather than by floating — a column of them reads as a set of things rather than a stack of panels. It holds a fill and a corner and nothing else: it does not pad what is inside it, and what is inside it is the page's to compose. One variant holds no fill either: `plain` paints nothing and lets whatever is beneath it through, for an editorial card that is told apart by its picture and its headline rather than by a ground.
+
+## Use when
+
+- Content that is read as one thing — a feature and the sentence explaining it, a plan and what it costs, a step and what it asks for
+- A picture that reaches the card's edges, with or without copy inset beneath it — a screenshot, a photograph, a band of art. The corner clips it, and the card adds no inset that would leave it floating in a margin
+- A row or a column of such groups, where the fill is what separates one from the next
+- A measure a landing page should not be choosing for itself: the corner a card takes and the ground it sits on
+- An editorial card — an article, a post, a story — where the picture and the headline do the separating and a fill would be a second, weaker edge. That is `plain`, which paints no ground and keeps the corner
+
+## Do not use
+
+- The whole surface is the thing the reader presses → `CardButton`
+- A promotional tile as a component of its own. A tile is this surface holding a heading, some words, a mark and a Button — each of which already exists and already knows what it looks like. There is nothing left for a second component to decide
+- A band running the width of the page. That is the page changing ground under a whole section, which is a section's own fill — color.bg.subtle or color.bg.brand-strong — rather than a container sitting on it. A card that stretched edge to edge would be a page with rounded corners
+- Padding. A card that padded its own contents could not hold a picture reaching its edges, which is the shape a marketing card most often takes. The inset is CardBody's, and it sits on the region holding the words rather than on the body as a whole — which is how one component draws both the inset copy and the bled picture beneath it
+- Nesting inside a control or a mark. A card is a thing you put components into, never one you put inside something
+
+## Anatomy
+
+Card renders one element.
+
+- `root` — `<div>`, class `dds-card`. The surface: a fill, a corner, and the regions it is given. It pads nothing itself — that is CardBody's job — because a picture reaching the edges with words inset beneath it is the shape a marketing card most often takes, and a card that padded its own contents could not draw one. `overflow: hidden`, so a picture put straight into the card meets the corner it is clipped by rather than squaring it off.
+  
+  No shadow and no border. The page is white and color.bg.surface is a step off it, so the fill is already the edge; an elevation would say the card floats, which it does not. On a color.bg.subtle band the same fill reads the other way round — lighter than its ground rather than darker — and is still an edge, which is what color.bg.surface's own description means by recessed against the page and raised on a subtle band.
+  
+  A <div>, and no role: it holds content rather than doing anything, so there is nothing to announce about the container itself.
+  
+  It holds one child. The wildcard beside `CardBody` in `allowedChildren` is older than that: it was there for a picture reaching the card's edges while the copy stayed inset, which was a second child until CardMedia folded into the body and became `src`. What the wildcard still buys is content that is not a body at all — a chart, a band of art — and there is still only ever one of it. Two bodies in one card is two padded stacks with a seam down the middle, which is a page composing a section rather than a card holding one.
+  
+  `plain` is the one variant that paints no background at all. Everything else on this part still holds for it — the corner, the clip, the absence of a shadow and of a border — so the only thing that changes is that the fill stops being the edge and something else has to be. On an editorial card that something is the picture and the headline. On a card holding nothing but copy it is nothing, which is what makes `plain` the one ground here that can be wrong on its own rather than only wrong for where it was put.
+  
+  The corner is the fill's, which is why `plain` has none. `radius.surface` rounds a ground so it reads as one shape against the page; with no ground the only thing left to round is the picture, and a rounded photograph on the page reads as a tile floating on it rather than as art the page opens with. So the binding is conditional where the fill is, and the two are the same decision written twice — a card with a ground gets a corner, a card without one does not.
+  
+  The ground has two directions. `tone: inverse` turns the neutral fills into a veil of white over whatever the band behind is painted, rather than a sheet of paper laid on it — an opaque `color.bg.surface-raised` on a dark footer is a white rectangle punched through the band, which reads as a hole rather than as a card. The brand fills are untouched: they carry their own ground and their own ink in either direction.
+  
+  The corner has two steps. `radius.surface` is a feature card in a grid; `compact` takes `radius.surface-compact`, the same ramp one step down and the corner a card two hundred pixels wide wants — at twenty-four the corner is a fifth of the card. `plain` keeps `radius.none` either way: it has no ground, so it has no corner to soften.
+
+Apply these classes from the generated `cardParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: any content
+- Never contains: `Card` — in children or in any prop that takes a node
+- Holds at least 1 and at most 1
+
+## Props
+
+### variant — `surface` | `surface-raised` | `plain` | `accent` | `accent-strong` (default `surface`)
+
+- `surface` — The default, and right for a card on the page. The marketing page is white and this is a step off it, so the card is told apart by being recessed — no shadow and no border, because the fill is already the edge
+- `surface-raised` — The card sits on a color.bg.subtle band rather than on the page. There the recessed fill is only 1.09:1 against its ground and all but disappears; this one is 1.23:1 the other way, lifting off the band instead of sinking into it
+- `plain` — An editorial card — an article, a post, a story — where the picture and the headline are what separate one card from the next. It paints no background, so it shows whatever is under it: the page, a subtle band, or a section that has taken a colour. The corner and the clip are still the card's, so a picture at the top of it meets a rounded edge rather than squaring one off It takes no corner either: radius.surface is the shape of a fill, and with no fill there is nothing to round — a rounded picture sitting on the page reads as a floating tile rather than as the art leading an article.
+- `accent` — One card in a set is the promotional one and the page has already earned the colour. The coral is the loudest ground here, so a row of them is a row of nothing louder than the rest
+- `accent-strong` — A card carrying more weight than its neighbours, where the coral would be too loud and the page ground too quiet. The darkest of the four, and the one that takes white at 20.55:1 — the most legible ground a marketing card has
+
+### tone — `default` | `inverse` (default `default`)
+
+- `default` — The page is light, which is nearly every page. The fills are opaque and the ink is dark
+- `inverse` — The card sits on a band that paints its own dark ground. The neutral fills become a veil of white over that ground rather than a sheet of paper on top of it, which is what keeps a card on a dark band from reading as a hole cut in it. The two neutral variants stay two steps apart: `surface` is the quiet one a panel wants, `surface-raised` the stronger lift that suits something the size of a control.
+
+Use when: Which way round the ground is. A card sits on the page by default; `inverse` is for one sitting on a band that paints its own dark ground — a footer, a dark hero, a brand takeover. The neutral fills flip to a veil of white over whatever is behind them and the ink runs light, which is the same move the bar makes when it stands on a dark first section.
+
+It reaches the neutral variants only. `accent` and `accent-strong` already paint a ground of their own and carry the ink to go with it, so there is nothing for this to invert — a coral card is coral on a white page and on a dark band alike.
+Never for: Making a card darker on a light page. This does not mean "dark" — it means "the thing behind me is dark". On a white page an inverse card is a barely-there wash nobody can see the edge of
+
+### compact — `boolean` (default `false`)
+
+Use when: The card is small enough that a generous corner is a fifth of its width. `radius.surface` is twenty-four, which is the corner of a feature card in a grid; on a rail beside a footer's columns it reads as bulbous. This takes it to `radius.surface-compact`.
+
+It pairs with CardBody's prop of the same name, and the two are separate because the box and its contents are separate components: this one owns the ground and the corner, that one owns the inset and the type. A small card wants both.
+Never for: A card that is merely less important. The corner follows the card's size, not its rank — a full-width card with a tight corner reads as a panel that has lost its edges rather than as a quiet one
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## 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
+
+❌ Card for: The whole surface is the thing the reader presses
+   A surface that responds to a press is a control: it takes focus, it announces itself, and the element decides whether it navigates. This holds content and does nothing, which is why it is a div with no role. CardButton is the same four grounds and the same corner with a target around them — an <a> when given an href and a <button> when not — and it gives up holding a control of its own, because a button inside a button is unreachable
+   → use `CardButton` instead.
+
+## Example
+
+```tsx
+import { Card, CardBody } from '@deriv-com/dds-marketing'
+
+<Card>
+  <CardBody title="Trade your way" description="Access 250+ markets with tight spreads and powerful tools." />
+</Card>
+```
+
+## In use
+
+### The grounds
+
+Which one is right follows from what the card is sitting on, not from how important it is. The page is white, so the default is a step off it. The fifth paints nothing and shows what is under it.
+
+```tsx
+import { Card, CardBody } from '@deriv-com/dds-marketing'
+
+// surface — on the page
+<Card variant="surface">
+  <CardBody title="Tight spreads" description="Competitive pricing on every market, with no hidden markup." />
+</Card>
+
+// surface-raised — on a subtle band
+<Card variant="surface-raised">
+  <CardBody title="Fast execution" description="Orders filled in milliseconds, even when the market moves." />
+</Card>
+
+// accent — the promotional one
+<Card variant="accent">
+  <CardBody title="Balance protection" description="Protect your account from unexpected market swings." />
+</Card>
+
+// accent-strong — carrying more weight
+<Card variant="accent-strong">
+  <CardBody title="High leverage" description="Maximise your exposure with high leverage and tight spreads." />
+</Card>
+
+// plain — no fill at all
+<Card variant="plain">
+  <CardBody flush title="Market insights" description="Read what moved this week, and what it means for the week ahead." />
+</Card>
+```
+
+### Which way round the ground is
+
+A card on a band that paints its own dark ground takes a veil of white over it rather than a sheet of paper on top of it. An opaque fill there reads as a hole punched in the band.
+
+```tsx
+import { Card, CardBody } from '@deriv-com/dds-marketing'
+
+// default — a card on the page
+<Card variant="surface-raised" tone="default">
+  <CardBody title="Deriv App" description="Manage accounts, transfer funds, and access markets anytime, anywhere." />
+</Card>
+
+// inverse — the same card on a dark band
+<Card variant="surface-raised" tone="inverse">
+  <CardBody title="Deriv App" description="Manage accounts, transfer funds, and access markets anytime, anywhere." />
+</Card>
+```
+
+### Why the card pads nothing
+
+A picture reaching the edges and copy that does not are one card, and one measure cannot draw both. The inset is CardBody's, so content put straight into the card meets the corner.
+
+```tsx
+import { Card, CardBody } from '@deriv-com/dds-marketing'
+
+// Straight into the card — no inset
+<Card>This text touches the corner, which is what a picture wants and copy does not.</Card>
+
+// In a body — inset from the edges
+<Card>
+  <CardBody title="In a body" description="This text is inset, which is what copy wants and a picture does not." />
+</Card>
+```
+
+### A card that leads with a mark
+
+The mark is inset with the copy and sized to sit above a heading, which is what makes it a slot in the body rather than a picture. A card can carry one, the other, or neither.
+
+```tsx
+import { Card, CardBody, Icon } from '@deriv-com/dds-marketing'
+import { MemoCircleCheckRegularIcon } from '@deriv-com/quill-icons-web'
+
+// surface-raised — a mark, and no picture
+<Card variant="surface-raised">
+  <CardBody mark={<Icon size="xs"><MemoCircleCheckRegularIcon /></Icon>} title="Be reliable" description="We settle all contracts fairly, process all deposits and withdrawals promptly, and provide reliable support to all our customers." />
+</Card>
+
+// No mark — the same card without one
+<Card variant="surface-raised">
+  <CardBody title="Be reliable" description="We settle all contracts fairly, process all deposits and withdrawals promptly, and provide reliable support to all our customers." />
+</Card>
+```
+
+### Copy above an edge-to-edge picture
+
+The inset sits on the words, not on the body, so one component holds copy held off the corner and a picture that meets it. The picture takes the height the copy left.
+
+```tsx
+import { Card, CardBody } from '@deriv-com/dds-marketing'
+
+// accent-strong — alt describes what the picture shows
+<Card variant="accent-strong">
+  <CardBody title="Teamwork" description="We value team players that collaborate freely across departments with humility and ambition." src="/sample-card-image.svg" alt="Two colleagues talking over a laptop in an open-plan office." />
+</Card>
+
+// accent — a decorative picture, alt is empty
+<Card variant="accent">
+  <CardBody title="Competence" description="We value colleagues with good judgement and an aptitude to learn." src="/sample-card-image.svg" alt="" />
+</Card>
+
+// above — the picture leads and the words caption it
+<Card variant="surface">
+  <CardBody title="Controlled risk, unlimited opportunities" description="Set your limits and manage your trades with take profit and stop loss." src="/sample-card-image.svg" alt="" mediaPosition="above" />
+</Card>
+```
+
+### An editorial card
+
+The shape `plain` exists for. With no fill the picture is the card's edge, so the body goes `flush` and the copy lines up with it rather than indenting from it.
+
+```tsx
+import { Card, CardBody } from '@deriv-com/dds-marketing'
+
+// plain — a picture, a date, and a headline
+<Card variant="plain">
+  <CardBody flush src="/sample-card-image.svg" alt="The entrance to a bank, seen from street level." mediaPosition="above" aspect={1.7777777777777777} eyebrow="14 August 2026" title="A bank can bank your IPO and still refuse your account" />
+</Card>
+
+// plain — no picture, so the copy carries it alone
+<Card variant="plain">
+  <CardBody flush 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." />
+</Card>
+
+// surface — the same card with a fill, for comparison
+<Card variant="surface">
+  <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." />
+</Card>
+```
+
+### The corner follows the card's size
+
+Twenty-four is the corner of a feature card in a grid. On something the size of a rail beside a footer's columns it is a fifth of the card's width, and the box reads as bulbous.
+
+```tsx
+import { Card, CardBody } from '@deriv-com/dds-marketing'
+
+// the standard corner
+<Card variant="surface" tone="inverse">
+  <CardBody compact title="Deriv App" description="Manage accounts and access markets anytime." />
+</Card>
+
+// compact — radius.surface-compact
+<Card variant="surface" tone="inverse" compact>
+  <CardBody compact title="Deriv App" description="Manage accounts and access markets anytime." />
+</Card>
+```