@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/table.md

@@ -0,0 +1,660 @@
+<!-- GENERATED from table.contract.json. Do not edit. -->
+
+# Table
+
+Structured data in rows and columns, where every row has the same shape. It owns what the whole table shares — a row's air, the rule between rows, how the columns take their widths — and none of what a cell holds, which is the page's to compose.
+
+It remembers nothing. Which column is sorted outlives a render, so it arrives as a hook beside this component; the toolbar above and the footer beneath are the page's too, on the same surface. None of the three is a prop, and a table that grew one would hold a second copy of what the page already has.
+
+## Use when
+
+- Data with a uniform structure, where the same fields exist on every row and a reader compares one row against another down a column
+- Values that line up — amounts, dates, counts. A column is what makes them comparable, and comparison is the only reason to pay for a table's weight
+- Rows that carry more than words: a badge against a name, a link at the end. The cell is a slot, so what a row holds is the page's decision
+
+## Do not use
+
+- The records do not share a shape, or each is a thing in itself rather than a row to compare → `Card`
+- There is one field per record → nothing here does this
+- Layout. A table means the rows and columns carry meaning, and using one to place things puts a grid in the accessibility tree that a screen reader reads out as rows and columns of nothing
+- A single record's fields. Two columns of label-and-value is a description list wearing a table's markup, and it announces every label as a column header it is not
+- Data a reader cannot compare. If nobody will read down a column, the alignment, the rules and the header are all cost with no return
+- Holding the answer to its own sorting or selection. Both outlive the render, so a table that kept them would be a second copy of what the page already has, and the two disagree the first time anything else changes either
+- A row placed straight into the table. `forbiddenChildren` refuses it and the reason is worth more than the refusal: `<table>` cannot contain `<tr>`, so an HTML parser inserts an implied `<tbody>` around it — and React does not do the same on the client. Server-rendered markup therefore gains a node the client render lacks, and the two disagree at hydration. Every row belongs inside a section, which is what the sections are for
+
+## Anatomy
+
+Table renders 3 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-table`. The scroll container, and the only thing here that is not the table. A table cannot scroll itself — `display: table` establishes no scroll container — so the element that does has to be a box around it, which is why this component renders two elements where it used to render one.
+  
+  It earns that second element on the narrowest screen. A table is as wide as its columns need and a phone is not, and the surface it sits on clips: Card holds a corner and `overflow: hidden` to keep it, so a table wider than its card was cut off at the edge with nothing to say so and no way to reach the rest. That is the same unrecoverable failure the grid itself has — a column that is not there and a column that was never asked for look identical — and it is why this is the component's problem rather than the page's.
+  
+  It scrolls on one axis only. The block axis is the page's: a table long enough to scroll vertically inside a box of its own is a table a reader cannot get out of, and the rows are the page's to paginate.
+  
+  It is declared focusable, which is the contract saying what the implementation does: a div takes no focus on its own, and this one is given a tabindex. That is the cost of being a scroll region and not optional — a region a pointer can scroll and a keyboard cannot is unreachable for anybody not using a mouse. Named from the caption where there is one, so what a reader arrives in is announced rather than being an unlabelled box.
+- `grid` — `<table>`, class `dds-table__grid`. The grid itself, and nothing under it. It paints no fill and holds no corner: a table is data, and the surface it sits on belongs to whatever put it there — a card, a panel, a section of a page. A table that painted its own would be a second surface inside the one it was given, and the two would disagree about the corner the moment either changed.
+  
+  Its borders are separate with no spacing between them. A collapsed table ignores `border-radius`, which matters here even though this element draws none: a wrapper that rounds and clips a collapsed table cannot, so the table would fight the very surface it is meant to sit inside. The cost is that `<tr>` borders stop being painted at all, so the rules moved onto the cells — each cell draws the line above it, and a run of cells across one row draws one rule. `border-spacing: 0` keeps them touching, so the line is continuous rather than dashed by gaps.
+  
+  It fills the scroller it is given rather than hugging its contents, so a table narrower than its container does not leave the last column floating with nothing under it. Where the columns need more room than that, the scroller takes over.
+  
+  It owns the size, the rules and the column strategy, and hands all three to what it holds, section by section and then row by row. Each part re-declares them so it is still correct on its own, and nothing has to look upward to know how it is drawn.
+  
+  It holds sections and never rows, which `forbiddenChildren` enforces and hydration is the reason for. `<table>` cannot contain `<tr>`: a parser reading server-rendered markup inserts an implied `<tbody>` around a bare row, and React does not insert one on the client — so the two trees differ by a node that nothing in the source asked for, and hydration mismatches.
+- `caption` — `<caption>`, class `dds-table__caption`. What the table is, in words, above it. A table is announced as a grid of so many rows and columns and nothing else, so without a name a reader arrives inside one with no idea what it holds.
+  
+  Visible rather than hidden, which is the point of it being a caption at all: a name a sighted reader can see is one they can also skip past, and a table in the middle of a page needs saying what it is as much as any other reader does. Where a heading directly above already says so, omit this and point at that heading instead. Rendered only when `caption` is set.
+
+Apply these classes from the generated `tableParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: `TableHead`, `TableBody`
+- Never contains: `Table`, `TableRow`, `TableCell`, `TableHeaderCell`, `Card` — in children or in any prop that takes a node
+- Holds at least 1 and at most 2
+
+## Props
+
+### layout — `auto` | `fixed` (default `auto`)
+
+- `auto` — The default. Columns take their widths from what is in them, which is right when the content is known and varied — a name column wants more room than a status one and can say so itself
+- `fixed` — Columns take an equal share of the width whatever they hold, and the table stops re-flowing as data changes. Reach for it when rows arrive over time: with auto widths every new page of results shifts every column and the reader loses the shape they had learnt.
+
+Equal shares is the whole of what it does here. `table-layout: fixed` exists to make declared column widths authoritative, and this component declares none — there is no per-column width to set — so three columns are a third each however unlike they are.
+Never for: A table whose columns need unequal room. Fixed gives them a third each, and a column that needs more does not clip — the text wraps instead — so the one carrying a name becomes a column of three-line cells while the one carrying a status keeps two thirds of its width empty. That is worse than the re-flow it was avoiding, and there is no width prop to correct it with: the pair that fixes it is a per-column width, which this component does not have yet.
+
+### pinFirstColumn — `boolean` (default `false`)
+
+Use when: The first column is what identifies the row — a market, a product, a plan — and the columns after it are the values being compared. Pinned, the name stays while the numbers scroll, so a reader who has scrolled three columns out still knows which row they are reading. It is worth asking for exactly when the table is wider than the screen it is read on, which on a marketing page is most tables on a phone
+Never for: A table that fits. Nothing sticks until there is something to scroll, so the pinning itself costs nothing — but the rule marking the pinned column is drawn either way, and a line down a table that never moves is a boundary the reader cannot act on. Nor a first column that is one of the values rather than the name of the row: pinning it says the rest are read against it, and a reader will believe that whether it is true or not
+
+### caption — `string`
+
+Use when: Where nothing else names the table. A table is announced as a grid of so many rows and columns, so a reader landing inside an unnamed one has to read a cell to find out what they are in — "Open positions", "October statements". It renders a real `<caption>`, which browsers centre above the grid in bold, so it is a visible heading rather than a hidden label.
+
+Most pages already have that heading, sitting above the table and styled by the page rather than by this component. Point at it with aria-labelledby and leave this out: two headings, one of them the browser's own idea of what a caption looks like, is worse than the one the page had.
+Never for: Explaining the table. It is a name rather than a sentence: what the columns mean belongs in the header row, and anything longer than a few words is a paragraph the reader has to get past before reaching the data
+
+### 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 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
+
+### hoverable — `boolean` (default `true`)
+
+Use when: On by default. A wash follows the pointer and says which row a press would land on, which a wide table needs and a narrow one is not harmed by: the further a row runs, the easier it is to be reading one and about to click another. Only on devices that have a pointer, which the row's own stylesheet gates
+Never for: Nothing, usually — turning it off is the decision that takes a reason. A table that is only ever read is the case: a row that lights up under the pointer says it can be acted on, and one that lights up and does nothing makes that promise on every row at once
+
+### 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<HTMLDivElement>`.
+
+## Behaviour
+
+A table renders what it is given and remembers nothing. Which column is sorted outlives a render and belongs to the page — a table that kept it would hold a second copy of what the page already has, and the two disagree the first time anything else changes either.
+
+So it arrives as a hook beside the component. It owns one answer and hands back what to spread; it touches no DOM, and a table composed without it is a static grid, which is what most of a marketing page wants.
+
+```tsx
+import { TableHeaderCell, useTableSort } from '@deriv-com/dds-marketing'
+
+// The hook holds which column and which way; the header cell draws the mark and reports the
+// press. Ordering the rows stays the page's, since only the page knows what a value means.
+const sort = useTableSort({ column: 'spread', direction: 'ascending' })
+
+<TableHeaderCell align="end" {...sort.columnProps('spread')}>Spread</TableHeaderCell>
+```
+
+It takes the state the table opens in, because a table arriving already ordered the way its page means it to be read is the ordinary case rather than the exotic one.
+
+Product ships two more hooks beside this one — row selection and column management. Neither comes over. They are how an application operates a table, and a marketing table is read rather than operated: a page that needs a reader to pick rows out of a set is an application view, and the table there is product's.
+
+The hook makes a table using it a client component, since useState cannot cross the server boundary. A table composed without it is markup and props only and renders on a server perfectly well — worth knowing on a marketing page, because it is the difference between a static section and a bundle every reader downloads.
+
+- `useTableSort` — with `TableSort`, `TableSortDirection`
+
+All from `@deriv-com/dds-marketing`, the same import as the component.
+
+## 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: `table`
+- `Tab` — reaches the controls inside cells, in the order they are drawn. The table itself is not a tab stop — it is content, and a reader arrives at it by reading
+- the scroll container is named where the table has a caption, so a reader who tabs into it is told what they have arrived in rather than meeting an unlabelled box
+- the scroll container is reachable by keyboard and says so when it is reached. A region a pointer can scroll and a keyboard cannot is unreachable for anybody not using a mouse — and a tab stop that lands somewhere with nothing drawn on it is a reader losing their place in a table, which is the one thing this component exists to prevent. So it takes a tab stop and the ring this package paints on everything else that takes one
+- the table has an accessible name, which caption supplies. A table is announced as a grid of so many rows and columns and nothing else, so a reader landing inside an unnamed one has to read a cell to find out what they are in
+- the header row is marked up as header cells rather than styled to look like them. A screen reader announces the column header before each cell's value, which is the whole of how a reader knows what a number means without looking it up
+- every row has the same number of cells. A table promises a shape, and a short row shifts every value after it into the wrong column for anyone reading it a cell at a time
+- nothing here is focusable but the controls the cells hold. The grid takes no tabindex of its own
+- a pinned column is a visual arrangement and nothing more. The cell keeps its place in the row, its header keeps naming its column, and the reading order is untouched — a reader who cannot see the scrolling meets the same table either way
+
+## 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
+
+❌ Table for: The records do not share a shape, or each is a thing in itself rather than a row to compare
+   A table promises that every row answers the same questions, and a column with nothing in it for half the rows is that promise broken in the one place a reader is looking. A card is a group of content read as one thing — reach for it when the reader looks at records one at a time, because a table is for looking across them and its whole cost buys that comparison
+   → use `Card` instead.
+
+❌ Table for: There is one field per record
+   A table of one column is a stack of values with rules around it. The grid earns its weight by aligning values against each other, and with a single column there is nothing to align — the same words in a plain stack say as much for none of the weight
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+## Example
+
+```tsx
+import { Table, TableHead, TableRow, TableHeaderCell, TableBody, TableCell } from '@deriv-com/dds-marketing'
+
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell>Name</TableHeaderCell>
+      <TableHeaderCell>Email</TableHeaderCell>
+      <TableHeaderCell>Role</TableHeaderCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Alice Johnson</TableCell>
+      <TableCell>alice@example.com</TableCell>
+      <TableCell>Engineer</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Bob Smith</TableCell>
+      <TableCell>bob@example.com</TableCell>
+      <TableCell>Designer</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Charlie Brown</TableCell>
+      <TableCell>charlie@example.com</TableCell>
+      <TableCell>PM</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## In use
+
+Most rows below hold the same set, written once here:
+
+```tsx
+import { TableBody, TableCell, TableHead, TableHeaderCell, TableRow } from '@deriv-com/dds-marketing'
+
+const tableheads = (
+  <>
+    <TableHead>
+  <TableRow>
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>Role</TableHeaderCell>
+  </TableRow>
+</TableHead>
+    <TableBody>
+  <TableRow>
+    <TableCell>Alice Johnson</TableCell>
+    <TableCell>alice@example.com</TableCell>
+    <TableCell>Engineer</TableCell>
+  </TableRow>
+  <TableRow>
+    <TableCell>Bob Smith</TableCell>
+    <TableCell>bob@example.com</TableCell>
+    <TableCell>Designer</TableCell>
+  </TableRow>
+  <TableRow>
+    <TableCell>Charlie Brown</TableCell>
+    <TableCell>charlie@example.com</TableCell>
+    <TableCell>PM</TableCell>
+  </TableRow>
+</TableBody>
+  </>
+)
+```
+
+### What it is for
+
+Values a reader compares down a column. The alignment, the rules and the header are the whole cost, and comparison is the only thing that repays them.
+
+```tsx
+import { Table } from '@deriv-com/dds-marketing'
+
+// Three columns of uniform records
+<Table>{tableheads}</Table>
+```
+
+### The case of the column names
+
+Capitals read as a different texture from the values rather than a louder version of them. Names drawn as written are right where they are long, or are proper nouns, or are in a script with no case.
+
+```tsx
+import { Table } from '@deriv-com/dds-marketing'
+
+// upper — the default, capitals at eleven pixels
+<Table headerCase="upper">{tableheads}</Table>
+
+// title — as written, at twelve
+<Table headerCase="title">{tableheads}</Table>
+```
+
+### Row density
+
+One decision on the table, drawn by every cell: the padding and the size of the type together. Compact for scanning, spacious when the table is the page.
+
+```tsx
+import { Table } from '@deriv-com/dds-marketing'
+
+// sm — compact
+<Table size="sm">{tableheads}</Table>
+
+// md — balanced
+<Table size="md">{tableheads}</Table>
+
+// lg — spacious
+<Table size="lg">{tableheads}</Table>
+```
+
+### Dividers
+
+Rows for a list of records, which is most tables. Grid for one read as a matrix, where a reader traces a column as often as a row. None where alignment already separates them.
+
+```tsx
+import { Table } from '@deriv-com/dds-marketing'
+
+// rows — the default
+<Table dividers="rows">{tableheads}</Table>
+
+// grid — lines both ways
+<Table dividers="grid">{tableheads}</Table>
+
+// none
+<Table dividers="none">{tableheads}</Table>
+```
+
+### How the columns take their widths
+
+Auto lets content decide, which suits known data. Fixed shares the width evenly so the table stops re-flowing as rows arrive over time.
+
+```tsx
+import { Table } from '@deriv-com/dds-marketing'
+
+// auto — content decides
+<Table layout="auto">{tableheads}</Table>
+
+// fixed — steady as data changes
+<Table layout="fixed">{tableheads}</Table>
+```
+
+### Hover
+
+On by default: a wash under the pointer saying which row a press would land on. Only on devices that have a pointer. Turning it off is what takes a reason.
+
+```tsx
+import { Table } from '@deriv-com/dds-marketing'
+
+// The default — rows answer the pointer
+<Table hoverable>{tableheads}</Table>
+
+// Off — a table that is only read
+<Table hoverable={false}>{tableheads}</Table>
+```
+
+### When a value is too long
+
+Wrapping grows the row and hides nothing. Truncating keeps every row one line high, which is what a reader scanning a dense table is using. Headers always truncate.
+
+```tsx
+import { Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow } from '@deriv-com/dds-marketing'
+
+// wrap — the row grows
+<Table overflow="wrap">
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell>Name</TableHeaderCell>
+      <TableHeaderCell>Email</TableHeaderCell>
+      <TableHeaderCell>Role</TableHeaderCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Charlotte Featherstonehaugh-Willoughby</TableCell>
+      <TableCell>charlotte@example.com</TableCell>
+      <TableCell>Engineer</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Bob Smith</TableCell>
+      <TableCell>bob@example.com</TableCell>
+      <TableCell>Designer</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+
+// truncate — the row stays one line
+<Table overflow="truncate">
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell>Name</TableHeaderCell>
+      <TableHeaderCell>Email</TableHeaderCell>
+      <TableHeaderCell>Role</TableHeaderCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Charlotte Featherstonehaugh-Willoughby</TableCell>
+      <TableCell>charlotte@example.com</TableCell>
+      <TableCell>Engineer</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Bob Smith</TableCell>
+      <TableCell>bob@example.com</TableCell>
+      <TableCell>Designer</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Ordering by a column
+
+Every sortable column carries a mark, not only the sorted one — a mark on the active header alone leaves a reader guessing which of the others can be pressed at all.
+
+```tsx
+import { Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow } from '@deriv-com/dds-marketing'
+
+// Sorted by balance, largest first
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell sortable sortDirection="none">Market</TableHeaderCell>
+      <TableHeaderCell align="end" sortable sortDirection="descending">Balance</TableHeaderCell>
+      <TableHeaderCell>Status</TableHeaderCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>EUR/USD</TableCell>
+      <TableCell align="end" numeric>1,284.00</TableCell>
+      <TableCell>Open</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>GBP/JPY</TableCell>
+      <TableCell align="end" numeric>942.50</TableCell>
+      <TableCell>Open</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>BTC/USD</TableCell>
+      <TableCell align="end" numeric>317.25</TableCell>
+      <TableCell>Closed</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Rich cells
+
+A cell is a slot, so a row can carry a badge rather than only words. What goes in is the page's to compose.
+
+```tsx
+import { Badge, Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow } from '@deriv-com/dds-marketing'
+
+// A status carried by a Badge
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell>Name</TableHeaderCell>
+      <TableHeaderCell>Email</TableHeaderCell>
+      <TableHeaderCell>Status</TableHeaderCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Alice Johnson</TableCell>
+      <TableCell>alice@example.com</TableCell>
+      <TableCell>
+        <Badge label="Active" variant="accent" />
+      </TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Bob Smith</TableCell>
+      <TableCell>bob@example.com</TableCell>
+      <TableCell>
+        <Badge label="Away" variant="neutral" />
+      </TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Filtering in the head
+
+A second row under the names, one control per column. Each control sits under the column it narrows, which is what a toolbar above the table would have to say in words.
+
+```tsx
+import { Badge, SearchInput, Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow } from '@deriv-com/dds-marketing'
+
+// A control under each column it filters
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell>Market</TableHeaderCell>
+      <TableHeaderCell align="end">Balance</TableHeaderCell>
+      <TableHeaderCell>Status</TableHeaderCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>
+        <SearchInput label="Filter by market" showLabel={false} placeholder="Any market" size="sm" />
+      </TableCell>
+      <TableCell>
+        <SearchInput label="Filter by balance" showLabel={false} placeholder="Any amount" size="sm" />
+      </TableCell>
+      <TableCell />
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>EUR/USD</TableCell>
+      <TableCell align="end" numeric>1,284.00</TableCell>
+      <TableCell>
+        <Badge label="Open" variant="accent" />
+      </TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>GBP/JPY</TableCell>
+      <TableCell align="end" numeric>942.50</TableCell>
+      <TableCell>
+        <Badge label="Open" variant="accent" />
+      </TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>BTC/USD</TableCell>
+      <TableCell align="end" numeric>317.25</TableCell>
+      <TableCell>
+        <Badge label="Closed" variant="neutral" />
+      </TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### The surface it sits on
+
+A Table paints no fill and holds no corner: the surface belongs to whatever the table is put in. This is that pairing, and it is the one composition every consumer writes.
+
+```tsx
+import { Card, Table } from '@deriv-com/dds-marketing'
+
+// Inside a Card, which brings the fill and the corner
+<Card bordered>
+  <Table>{tableheads}</Table>
+</Card>
+```
+
+### A column that stays put
+
+The first column names the row and the rest are the values compared against it. Pinned, the name stays while the numbers scroll out from under it.
+
+```tsx
+import { Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow } from '@deriv-com/dds-marketing'
+
+// Pinned — the name survives the scroll
+<Table pinFirstColumn overflow="truncate">
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell>Market</TableHeaderCell>
+      <TableHeaderCell align="end">Spread</TableHeaderCell>
+      <TableHeaderCell align="end">Commission</TableHeaderCell>
+      <TableHeaderCell align="end">Swap long</TableHeaderCell>
+      <TableHeaderCell align="end">Swap short</TableHeaderCell>
+      <TableHeaderCell align="end">Leverage</TableHeaderCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>BRKR.OQ: Bruker Corp (NASDAQ)</TableCell>
+      <TableCell numeric align="end">0.08</TableCell>
+      <TableCell numeric align="end">1200</TableCell>
+      <TableCell numeric align="end">-2.14</TableCell>
+      <TableCell numeric align="end">-0.87</TableCell>
+      <TableCell numeric align="end">1:20</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>BRO.N: Brown & Brown Inc (NYSE)</TableCell>
+      <TableCell numeric align="end">0.20</TableCell>
+      <TableCell numeric align="end">950</TableCell>
+      <TableCell numeric align="end">-1.96</TableCell>
+      <TableCell numeric align="end">-1.02</TableCell>
+      <TableCell numeric align="end">1:20</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>BSX.N: Boston Scientific Corp (NYSE)</TableCell>
+      <TableCell numeric align="end">0.23</TableCell>
+      <TableCell numeric align="end">500</TableCell>
+      <TableCell numeric align="end">-3.01</TableCell>
+      <TableCell numeric align="end">-0.44</TableCell>
+      <TableCell numeric align="end">1:10</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+
+// Not pinned — the name scrolls away with the rest
+<Table overflow="truncate">
+  <TableHead>
+    <TableRow>
+      <TableHeaderCell>Market</TableHeaderCell>
+      <TableHeaderCell align="end">Spread</TableHeaderCell>
+      <TableHeaderCell align="end">Commission</TableHeaderCell>
+      <TableHeaderCell align="end">Swap long</TableHeaderCell>
+      <TableHeaderCell align="end">Swap short</TableHeaderCell>
+      <TableHeaderCell align="end">Leverage</TableHeaderCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>BRKR.OQ: Bruker Corp (NASDAQ)</TableCell>
+      <TableCell numeric align="end">0.08</TableCell>
+      <TableCell numeric align="end">1200</TableCell>
+      <TableCell numeric align="end">-2.14</TableCell>
+      <TableCell numeric align="end">-0.87</TableCell>
+      <TableCell numeric align="end">1:20</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>BRO.N: Brown & Brown Inc (NYSE)</TableCell>
+      <TableCell numeric align="end">0.20</TableCell>
+      <TableCell numeric align="end">950</TableCell>
+      <TableCell numeric align="end">-1.96</TableCell>
+      <TableCell numeric align="end">-1.02</TableCell>
+      <TableCell numeric align="end">1:20</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>BSX.N: Boston Scientific Corp (NYSE)</TableCell>
+      <TableCell numeric align="end">0.23</TableCell>
+      <TableCell numeric align="end">500</TableCell>
+      <TableCell numeric align="end">-3.01</TableCell>
+      <TableCell numeric align="end">-0.44</TableCell>
+      <TableCell numeric align="end">1:10</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```