@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/tablehead.md

@@ -0,0 +1,248 @@
+<!-- GENERATED from table-head.contract.json. Do not edit. -->
+
+# TableHead
+
+The column names, above the data, and the filter row where there is one. It exists as a component rather than a wrapper because a screen reader announces a column's header before every value under it — which is the whole of how a reader knows what a number means without looking it up — and that only happens if the header is marked up as one rather than styled to look like one.
+
+A second row is allowed and a third is not. The second is the filter row: one control per column, sitting under the name of the column it narrows, which is the whole reason it is in here rather than in a toolbar above the table — a toolbar has to say which column each control acts on, and a row under the names has already said it. It gives up the inset above it, so the controls sit under the names rather than a gap of two insets away — the head is one thing, and each of its rows carrying its own air made it read as two. It is cells rather than header cells, because a control is not the name of a column and a screen reader announcing it as one would read a search box out before every value beneath it.
+
+Beyond two there is nothing a head is doing that a reader can still follow. Column names, and at most one row of controls over them.
+
+## Use when
+
+- Naming the columns, which almost every table should. A column of numbers with nothing at the top is a column a reader has to infer
+
+## Do not use
+
+- The row is data rather than a name for data → `TableBody`
+- A second row of data dressed as a subheading. Everything here names columns, and a reader is told so on every cell beneath
+- Skipping. A table with no header is a grid of values a reader has to work out from the data itself, which is guesswork on the first row and wrong on the rest
+
+## Anatomy
+
+TableHead renders one element.
+
+- `root` — `<thead>`, class `dds-tablehead`. The header section. It carries no rules of its own — the line under a header is the header row's, drawn by TableRow the same way the rules between data rows are — so this element is structure and nothing else. It takes the table's size so the header row is drawn at the same rhythm as the rows under it.
+  
+  It paints no band. A tinted header was here first and was the wrong answer for this design: the names are told apart from the data by their ink and by the rule under them, and a second fill behind them makes the header the loudest thing in a table whose whole point is the values. Declared as transparent rather than left unsaid, so the table's own surface is what shows through rather than whatever a page happens to sit it on.
+
+Apply these classes from the generated `tableHeadParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `TableRow`
+- Never contains: `Table`, `TableHead`, `TableBody`, `TableCell` — in children or in any prop that takes a node
+- Holds at least 1 and at most 2
+
+## Props
+
+### headerCase — `upper` | `title` (default `upper`)
+
+- `upper` — The house setting: column names in capitals, at the role that suits them. A header is read once where the data under it is read many times, and capitals are what stop it competing
+- `title` — Names drawn as they were written, at twelve pixels. Right where the names are long, are proper nouns whose own capitals would be flattened, or are in a script with no case at all
+
+### dividers — `rows` | `grid` | `none` (default `rows`)
+
+- `rows` — The default. A line between rows and none between columns. The head draws neither: the rule under it is the first data row’s top edge, and there are no columns to separate
+- `grid` — Lines both ways, for a table read as a matrix rather than as a list of records. The head takes the vertical half of it — a column read top to bottom starts at its name, and a grid whose rules begin below the header leaves the names floating over the columns they belong to
+- `none` — No lines at all, which for the head is what it already draws
+Never for: Giving the head a rule of its own under the names. That line already exists as the first data row’s top edge, and a second drawn here would double it at exactly the weight a hairline is chosen to avoid
+
+### overflow — `wrap` | `truncate` (default `wrap`)
+
+- `wrap` — The default. Text too long for its column wraps and the row grows taller, so nothing is hidden — right whenever the value is the point and a reader has to read all of it
+- `truncate` — Rows must stay one line high — a dense table a reader scans down, where a row that grew would break the rhythm they are scanning by. The value is clipped with an ellipsis and the whole of it is still reachable, so this trades seeing for scanning rather than losing anything
+Never for: Making a column narrow enough to be worth truncating. Clipping is what a column does when it has run out of room, not a way to give it less — a table of ellipses has hidden its data behind a hover on every cell
+
+### size — `sm` | `md` | `lg` (default `md`)
+
+- `sm` — Compact. Dense data a reader scans rather than reads — a ledger, a positions table, anything where fitting more rows on screen is worth more than air around each one
+- `md` — Balanced, and the default: rows a reader moves through at reading pace, with enough room that the eye does not slip between them
+- `lg` — Spacious. Few rows, each carrying something substantial — a plan comparison, a summary of three accounts. Reach for it when the table is the page rather than a part of it
+Never for: Making the text bigger or smaller. It changes how tall a row is and nothing else — the type stays one size down the whole table, because a reader comparing values across three tables at three densities is comparing the values rather than the tables. A table too wide for its column scrolls, and a smaller size only makes the same problem harder to read
+
+Also accepts everything from `HTMLAttributes<HTMLTableSectionElement>`.
+
+## 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 control in the head sits in a cell and not in a header cell. A filter row marked up as headers gives every column a second name, and a screen reader reads that name out before every value beneath it — so a column of amounts is announced as "Filter by balance" three times over
+
+## 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
+
+❌ TableHead for: The row is data rather than a name for data
+   What goes here is announced as the header of everything below it, so a data row placed here is read out before every other row as though it were their name
+   → use `TableBody` instead.
+
+## Example
+
+```tsx
+import { TableHead, TableRow, TableHeaderCell } from '@deriv-com/dds-marketing'
+
+<TableHead>
+  <TableRow>
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>Role</TableHeaderCell>
+  </TableRow>
+</TableHead>
+```
+
+## In use
+
+Most rows below hold the same set, written once here:
+
+```tsx
+import { TableHeaderCell, TableRow } from '@deriv-com/dds-marketing'
+
+const tablerows = (
+  <>
+    <TableRow>
+  <TableHeaderCell>Name</TableHeaderCell>
+  <TableHeaderCell>Email</TableHeaderCell>
+  <TableHeaderCell>Role</TableHeaderCell>
+</TableRow>
+  </>
+)
+```
+
+### What it holds
+
+A header is announced before every value under it, which is how a reader knows what a number means without looking it up.
+
+```tsx
+import { TableHead } from '@deriv-com/dds-marketing'
+
+// Three columns
+<TableHead>{tablerows}</TableHead>
+```
+
+### Row density
+
+Taken from the table and handed to every row, so a table's air is one decision made once rather than a measure repeated per cell.
+
+```tsx
+import { TableHead } from '@deriv-com/dds-marketing'
+
+// sm
+<TableHead size="sm">{tablerows}</TableHead>
+
+// md
+<TableHead size="md">{tablerows}</TableHead>
+
+// lg
+<TableHead size="lg">{tablerows}</TableHead>
+```
+
+### When a value is too long
+
+Handed down so every cell in the section agrees. Wrapping grows the row; truncating keeps it one line high.
+
+```tsx
+import { TableHead } from '@deriv-com/dds-marketing'
+
+// wrap
+<TableHead overflow="wrap">{tablerows}</TableHead>
+
+// truncate
+<TableHead overflow="truncate">{tablerows}</TableHead>
+```
+
+### The case of the names it holds
+
+Set here and drawn by the cells, so one head's names agree with each other.
+
+```tsx
+import { TableHead } from '@deriv-com/dds-marketing'
+
+// upper — capitals
+<TableHead headerCase="upper">{tablerows}</TableHead>
+
+// title — as written
+<TableHead headerCase="title">{tablerows}</TableHead>
+```
+
+### The rules it draws
+
+The head takes the vertical half of a grid and never the horizontal one: the line under the names is the first data row’s top edge.
+
+```tsx
+import { TableHead } from '@deriv-com/dds-marketing'
+
+// rows — no rule between the names
+<TableHead dividers="rows">{tablerows}</TableHead>
+
+// grid — a column starts at its name
+<TableHead dividers="grid">{tablerows}</TableHead>
+
+// none — what the head already draws
+<TableHead dividers="none">{tablerows}</TableHead>
+```

package/.llm/components/tableheadercell.md

@@ -0,0 +1,298 @@
+<!-- GENERATED from table-header-cell.contract.json. Do not edit. -->
+
+# TableHeaderCell
+
+The name of a column, announced before every value under it. That is the whole of why it is a component rather than a styled cell: a screen reader reads the header before each cell in the column, which is how a reader knows what a number means without looking it up — and it only happens if the header is a header in the markup.
+
+Where the column can be sorted, the header holds the control that sorts it. A button rather than a click handler on the cell, because sorting is an action: it has to be reachable by keyboard, announced as pressable, and able to say which way the column is currently ordered.
+
+## Use when
+
+- Naming a column, which every column should have
+- A column a reader can order, where `sortable` draws the control and `sortDirection` says which way it is ordered now
+
+## Do not use
+
+- The cell holds a value rather than the name of a column → `TableCell`
+- A column that cannot actually be sorted. `sortable` draws a control, and a control that reports to nobody is the clearest promise a table can break — the reader presses it twice before deciding the page is broken
+- Holding which column is sorted. `sortDirection` draws the answer for this one column; which column the table is ordered by outlives the render and belongs to the page, through useTableSort or its own state
+- A row of names inside the data. Everything marked up this way is announced as naming what follows it, so a header in the middle of a table re-names every row beneath
+
+## Anatomy
+
+TableHeaderCell renders 3 elements. A token binding names the part it applies to.
+
+- `root` — `<th>`, class `dds-tableheadercell`. The column's name. It shares the cell's padding and alignment so a header sits directly over the values it names — a header ranged to the start above a column of numbers ranged to the end is two edges where a reader expects one.
+  
+  Its case is the table's decision, and the two settings are typographic pairings rather than one role with a transform on it. In capitals it takes font.overline — eleven pixels, medium, with that role's wide tracking, which is the role's own stated purpose: "uppercase category labels, e.g. stat labels, section tags, table column headers". Drawn as written it takes font.label.sm — twelve pixels, medium, ordinary tracking. Caps set at body spacing is the setting caps are least legible in, the letterforms being all one height, so the tracking travels with the case rather than being left behind by it.
+  
+  Capitals are the default because a header is read once where the values under it are read many times: a run of caps is a different texture from the data rather than a louder version of it, which is what a larger or heavier header would have been. As written is the setting for names that are long, for proper nouns whose own capitals capitals flatten, and for a script that has no case at all — where capitals are either unreadable or meaningless.
+  
+  The capitals are drawn and never typed. `text-transform` leaves the accessible name as written, so a screen reader says "Market" where a header typed MARKET into a sidecar would be spelled out letter by letter — and the sidecar would then hold a value no consumer could change the case of.
+  
+  The capitals reach the column's name and stop there. A header cell is a slot, and a page may put a control or a mark in one — a word inside it came out in capitals with the column names, shouting in a row of quiet names. A component placed in a header keeps its own case, its typography being its own.
+  
+  It aligns to the bottom of its row rather than the top, unlike a data cell. Headers are short and the data beneath starts at the row's top edge, so ranging the name to the bottom is what puts it closest to what it names when a header row wraps to two lines.
+  
+  It draws no rule of its own. The line under a header is the first data row's top edge — TableRow draws its rule above itself, so the separator between the names and the data is already there, and a second edge here would be two lines collapsing into one thicker one.
+  
+  It draws the rule above itself. A `<tr>` border is painted only while a table collapses its borders, and this table separates them so it can hold a corner — so the line between two rows is a run of cell edges rather than one row edge, and `border-spacing: 0` on the table is what keeps them touching.
+  
+  It always truncates, and takes no say in it. A header is one or two words naming a column, and a header that wrapped would push the whole row taller to fit a name — where the data under it is what the height should be answering to. A column whose name does not fit is a column named too long rather than one needing more room.
+- `trigger` — `<button>`, class `dds-tableheadercell__trigger`. The control that orders the column, drawn only where there is one. A real button rather than a handler on the cell: sorting is an action, so it has to be reachable by Tab, answer Enter and Space, and take a focus ring — none of which a `<th>` does.
+  
+  It fills the cell and takes its alignment, so the whole header reads as one target rather than a word with a hit area around it. Its own colour and font are the header's, inherited rather than restated — a button that set them would be a second place for the header's type to be decided.
+  
+  The cell keeps `aria-sort`, not this button. The sort state is a fact about the column, and the column is the cell; announcing it on the control would say the button is ascending rather than the data.
+  
+  It takes no fill of its own when the pointer is over it. A wash across the whole header is the same gesture a row uses to say a press would land there, and at the top of the table it reads as a selected column rather than as feedback — a block of grey behind a name that is not a value. The mark answers instead, which is the smaller thing that moved.
+  
+  Its case is inherited by declaration rather than by luck, the way its font and its colour already are. `text-transform` is an inherited property, but a `<button>` is a form control and a browser's own stylesheet resets those — so a sortable column drew its name as written while the plain column beside it drew the same word in capitals. Two cases in one row of names, which is the one thing a row of names cannot have. The `font: inherit` above does not cover it: the shorthand carries the family, the size, the weight and the line height, and the case is none of those.
+  
+  It translates the cell's alignment into its own, because the two are not the same property. The cell ranges its text with `text-align`, which moves nothing inside a flex container — so a sortable column ignored the alignment it was given: a header over a column of amounts sat at the start of a full-width button while every number under it ranged to the end, and the non-sortable column beside it lined up correctly. Two edges where a reader expects one, which is the fault the alignment exists to prevent, reintroduced by the control that makes the column sortable. Rendered only when `sortable` is set.
+- `indicator` — `<span>`, class `dds-tableheadercell__indicator`. Which way the column is ordered, as a mark beside its name. Always drawn where the column is sortable — including when it is not the sorted column — because a mark that appeared only on the active header would leave a reader guessing which of the others could be pressed at all. Unsorted it takes the muted ink; sorted it takes the default one, so the active column reads first. A colour rather than a transparency: an opacity would fade the mark against whatever it happens to sit on, where an ink is the same decision the header's own text is already making.
+  
+  It is not the announcement. `aria-sort` on the cell is, and this is the sighted half of the same fact — which is why a column's direction is never carried by the mark alone.
+  
+  It is also what answers the pointer. Hovering anywhere on the header takes this from the muted ink to the default one, and nothing else changes — the whole cell stays the target, so the hit area is unchanged and only the feedback moved. That cannot be a binding here: a binding names a part and a state, and this is one part's state drawn on another. It sits in the impl sheet for the reason the row's pointer gate does.
+  
+  A hovered unsorted mark and a sorted one both take the default ink, and they are still told apart, because the glyph is not the same: unsorted is the two-headed arrow, sorted is a single chevron pointing the way the column runs. The ink says the header is live, the glyph says what it did.
+  
+  A flex box rather than a plain span, which is a centring fix and not a layout choice. Holding the glyph inline put it on `vertical-align: middle`, which is the midpoint of the x-height rather than of the line — a few pixels low, and low enough that the mark hung under a name with no descenders to explain it. As a flex box the span is as tall as the glyph and the header's own centring does the rest.
+  
+  The glyph is drawn at xs, which is the smallest step this package has. Product draws the same mark a step below that, at a size its Icon reserves for "a subtle inline indicator that sits inside a line of text — a caret, a sort arrow, a status dot", and it reached that size by way of a bug: at xs the mark stood half again the height of the name beside it, so the column read as an arrow with a label rather than as a name with a mark. This package's icon ramp does not go there. Its steps run larger throughout, which is the same position its type ramp takes and deliberate rather than drift — but it means the mark is sixteen pixels against a twelve-pixel name, which is the ratio product's own argument objects to. The mark is the quietest thing this package can draw here, and it is still not as quiet as the one product settled on. Rendered only when `sortable` is set.
+
+Apply these classes from the generated `tableHeaderCellParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: any content
+- Never contains: `Table`, `TableHead`, `TableBody`, `TableRow`, `TableCell`, `TableHeaderCell`, `Button`, `Link` — in children or in any prop that takes a node
+
+## Props
+
+### size — `sm` | `md` | `lg` (default `md`)
+
+- `sm` — Compact. Dense data a reader scans rather than reads — a ledger, a positions table, anything where fitting more rows on screen is worth more than air around each one
+- `md` — Balanced, and the default: rows a reader moves through at reading pace, with enough room that the eye does not slip between them
+- `lg` — Spacious. Few rows, each carrying something substantial — a plan comparison, a summary of three accounts. Reach for it when the table is the page rather than a part of it
+Never for: Making the text bigger or smaller. It changes how tall a row is and nothing else — the type stays one size down the whole table, because a reader comparing values across three tables at three densities is comparing the values rather than the tables. A table too wide for its column scrolls, and a smaller size only makes the same problem harder to read
+
+### align — `start` | `center` | `end` (default `start`)
+
+- `start` — Words. Names, descriptions, statuses — anything read left to right starts where the reading does, and a column of them shares one edge the eye can run down
+- `center` — Rare, and worth arguing for: a single glyph or a very short state where neither edge means anything. A centred column of words has two ragged edges instead of one
+- `end` — Numbers that line up under each other — amounts, counts, percentages. The decimal point is what a reader compares down a column, and ranging to the end is what puts it in one place
+Never for: Making a table look balanced. Alignment says what kind of thing a column holds; using it to even out a layout tells the reader the numbers are words
+
+### sortDirection — `none` | `ascending` | `descending` (default `none`)
+
+- `none` — The column can be sorted and the table is not currently ordered by it. The mark is drawn quietly, which is what tells a reader the column is available rather than active
+- `ascending` — The table is ordered by this column, smallest first — A to Z, earliest date, lowest amount
+- `descending` — The table is ordered by this column, largest first. The commoner opening state for money and dates, where the newest or the biggest is what a reader came for
+Never for: Two columns at once. A table is ordered by one column, so a second header claiming a direction tells the reader the data is sorted two ways and leaves them unable to trust either
+
+### dividers — `rows` | `grid` | `none` (default `rows`)
+
+- `rows` — The default. A line between rows and none between columns, which is what stops the eye slipping from one row's start to another's end — the mistake a wide table invites and the one a reader never notices making
+- `grid` — Lines both ways, for a table read as a matrix rather than as a list of records: a rate card, a comparison where the reader traces a column as often as a row. It is more lines than most tables need, so it should be asked for
+- `none` — No lines at all. Right for two or three rows, where the rules are more structure than data, and for a table whose columns are already separated by their alignment
+Never for: Marking a group. A missing line is not a heading — a table that wants sections wants a header row inside the body, or two tables. Nor `grid` as decoration on a long table: every vertical line is another thing between a reader and the value they came for
+
+### headerCase — `upper` | `title` (default `upper`)
+
+- `upper` — The house setting. Column names in capitals at font.overline — eleven pixels with wide tracking — which reads as a different texture from the values rather than a louder version of them. A header is read once where the data under it is read many times, and capitals are what stop it competing
+- `title` — Names drawn as they were written, at font.label.sm — twelve pixels, medium, ordinary tracking. Right where the names are long, are proper nouns whose own capitals capitals would flatten, or are in a script that has no case at all, and right wherever a product has decided its tables read as sentences rather than as labels
+
+### sortable — `boolean` (default `false`)
+
+Use when: The reader can order the table by this column. It draws the control and the mark; what pressing it does is the page's, reported through `onSort`
+Never for: A column that only looks orderable. There is no state where the control is drawn and inert — a header that could be pressed to no effect is worse than one that was never offered
+
+### onSort — `callback` **Required when sortable=true.**
+
+Use when: Told the header was pressed. It hands back nothing: the page rendered this header and knows which column it is, and what the next direction should be is the page's rule rather than this component's — `useTableSort` is where that rule lives if you want one written
+Never for: Sorting the data. This reports the press; the order of the rows is decided by whatever holds them, and a table that re-ordered its own children would be holding state it cannot own
+
+Also accepts everything from `ThHTMLAttributes<HTMLTableCellElement>`.
+
+## 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: `columnheader`
+- `Tab` — reaches the sort control where the column has one. A header that cannot be sorted is not a tab stop — it is a name
+- `Enter` — sorts the column
+- `Space` — sorts the column, which is what makes it a button rather than a link
+- the sort state is announced with aria-sort on the header cell, not on the control inside it. The direction is a fact about the column, and a reader moving through the table is told it as they enter the column rather than only if they reach the button
+- the direction is never carried by the mark alone. The indicator is drawn and never announced, so aria-sort is what tells a reader which way the data runs
+- a sortable header is a real button — reachable by Tab, answering Enter and Space, and carrying a visible focus ring. A cell with a click handler is none of those
+- the header names its column in words. It is announced before every value beneath it, so a header drawn as a glyph alone leaves the whole column unnamed
+
+## 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
+
+❌ TableHeaderCell for: The cell holds a value rather than the name of a column
+   A header is announced before every cell beneath it, so a value placed here is read out as the name of its own column and of every value under it
+   → use `TableCell` instead.
+
+❌ sortable=true + onSort missing or empty
+   A control the reader can press that reports to nobody. `sortable` draws the button and `onSort` is what answers it, and the pair with the second missing is a column that looks orderable and is not — pressed once, pressed again, and then read as a page that is broken rather than one that meant it
+
+## Example
+
+```tsx
+import { TableHeaderCell } from '@deriv-com/dds-marketing'
+
+<TableHeaderCell>Name</TableHeaderCell>
+```
+
+## In use
+
+### Naming a column
+
+Announced before every value beneath it. It shares the cell's alignment so a header sits directly over the values it names rather than across from them.
+
+```tsx
+import { TableHeaderCell } from '@deriv-com/dds-marketing'
+
+// A name
+<TableHeaderCell>Name</TableHeaderCell>
+
+// center — a short state, rarely
+<TableHeaderCell align="center">Status</TableHeaderCell>
+
+// Over a numeric column
+<TableHeaderCell align="end">Balance</TableHeaderCell>
+```
+
+### Ordering the column
+
+A real button, because sorting is an action: reachable by Tab, answering Enter and Space, and carrying a focus ring. A cell with a click handler is none of those.
+
+```tsx
+import { TableHeaderCell } from '@deriv-com/dds-marketing'
+
+// Sortable, not currently sorted
+<TableHeaderCell onSort={() => { /* your handler */ }} sortable sortDirection="none">Name</TableHeaderCell>
+
+// Ascending
+<TableHeaderCell onSort={() => { /* your handler */ }} sortable sortDirection="ascending">Name</TableHeaderCell>
+
+// Descending
+<TableHeaderCell onSort={() => { /* your handler */ }} sortable sortDirection="descending">Name</TableHeaderCell>
+```
+
+### Row density
+
+Set in the strong cut of the body face: a header is read once and the data many times, so it needs telling apart rather than making prominent.
+
+```tsx
+import { TableHeaderCell } from '@deriv-com/dds-marketing'
+
+// sm
+<TableHeaderCell size="sm">Name</TableHeaderCell>
+
+// md
+<TableHeaderCell size="md">Name</TableHeaderCell>
+
+// lg
+<TableHeaderCell size="lg">Name</TableHeaderCell>
+```
+
+### Dividers
+
+A header draws no line above itself — the rule under it is the first data row's top edge — but it takes the vertical rules where the table is a matrix.
+
+```tsx
+import { TableHeaderCell } from '@deriv-com/dds-marketing'
+
+// rows
+<TableHeaderCell dividers="rows">Name</TableHeaderCell>
+
+// grid
+<TableHeaderCell dividers="grid">Name</TableHeaderCell>
+
+// none
+<TableHeaderCell dividers="none">Name</TableHeaderCell>
+```
+
+### How the name is cased
+
+Capitals at eleven pixels with wide tracking, or the name as written at twelve. The capitals are drawn rather than typed, so the accessible name keeps the case it was authored in.
+
+```tsx
+import { TableHeaderCell } from '@deriv-com/dds-marketing'
+
+// upper — capitals
+<TableHeaderCell headerCase="upper">Name</TableHeaderCell>
+
+// title — as written
+<TableHeaderCell headerCase="title">Name</TableHeaderCell>
+```