@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/bottomsheet.md

@@ -0,0 +1,404 @@
+<!-- GENERATED from bottom-sheet.contract.json. Do not edit. -->
+
+# BottomSheet
+
+A panel that rises from the bottom edge to hold a single focused task on small screens. It owns the way out, the controls ranged above it and the row that names the task; what the task looks like is the consumer's.
+
+## Use when
+
+- A task needs the screen's full width and the reader's undivided attention — a set of filters, a confirmation, an option picker
+- The choice is the whole of what the reader is doing, and the page behind it is context rather than something to work in
+
+## Do not use
+
+- The message is a passing notification the reader does not have to answer → nothing here does this
+- The viewport is wide enough for a centred modal → nothing here does this
+- The reader is choosing one answer from a set, inside a form → nothing here does this
+- A short description of the control the pointer is on → `Tooltip`
+- Desktop viewports. The sheet stops growing at size.sheet.max and centres, which keeps it readable on a tablet — but nothing in this component refuses a wide screen, there being no breakpoint in a contract and no media query in the generated stylesheet. Above that width a centred modal is the right shape, and this package has none — so a sheet on a desktop viewport is a decision the page is making on purpose rather than one this component made for it.
+- Anything the reader must be able to see the page behind while doing. The scrim dims the page and swallows every press on it, which is the point: a sheet is a task, not a panel.
+- A second sheet on top of the first. Composition forbids the nesting, and the reason is the way out: two scrims stack, the second sheet's Escape shuts only itself, and a reader who has lost track of how deep they are has no way to read it off the screen.
+- Content the sheet is expected to hide from a screen reader when shut. The sheet stays mounted so it has something to animate from, and what removes it from the reading order while closed is `visibility: hidden` in the generated stylesheet — which means it is removed by CSS and not by the markup. A page that renders this without the stylesheet has a shut sheet a screen reader will read straight through.
+- Holding the open state itself. `open` is the consumer's, always: the sheet reports that it wants to close through onOpenChange and changes nothing on its own, so a page that never answers that callback has built a sheet with no way out.
+- Deciding what the task looks like. The sheet draws a handle, a header and a scrim, and hands the rest over as one slot — there is no footer prop and no description of what belongs at the bottom, because a component that fixed the shape of a confirmation would be wrong for a filter and wrong again for a picker. Build the content and pass it as children.
+- Holding a reader in. A press outside the sheet and Escape always close it, and neither flag can turn that off — a surface that answers neither is a trap, and a keyboard reader has no third way. A task that genuinely must be finished asks for that in its content, and takes the answer it is given.
+
+## Anatomy
+
+BottomSheet renders 12 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-bottomsheet`. The layer over the page. Fixed to the viewport on all four sides, which is what makes the sheet's bottom edge the screen's bottom edge rather than the nearest scroll container's, and what gives the scrim something to fill. It is also the element that fades: the opacity and the transition live here, so the scrim and the sheet arrive as one thing rather than as two that happen to agree.
+- `scrim` — `<div>`, class `dds-bottomsheet__scrim`. The dimming layer between the page and the sheet. A part of its own rather than a background on the root, so the press that dismisses the sheet lands on an element that is not an ancestor of the sheet — a scrim drawn on the root would take every press inside the sheet too, and the handler would have to guess which was which from the event's target.
+- `frame` — `<div>`, class `dds-bottomsheet__frame`. The box the layer holds against its bottom edge, and what caps the sheet's width so it does not run full-bleed across a tablet. The panel fills it.
+  
+  Product's frame does more than this: it is what lets that package's sheet hang its back and close controls in the gap above the panel, ranged to edges the two have to share. Here both ends are inside the header, so the frame is left holding the measure and nothing else — kept rather than collapsed into the panel because the width cap and the panel's own overflow are different jobs, and a panel that clips its corners cannot also be the box something is measured against.
+- `surface` — `<div>`, class `dds-bottomsheet__surface`. The sheet: the panel that holds the task. It paints color.bg.surface-modal, the role for a surface that covers the page behind a scrim, which both packages now share. It took the raised ground for a while, back when product’s page was grey and the two read the same roles in opposite directions. A sheet sits over a dimmed page rather than floating above a live one, so the role it wants is the modal one rather than the dropdown’s. Carries the corner and the elevation — the surface step rather than the container one, so a sheet rounds to the same measure as the cards on the page behind it rather than reading as a larger kind of box than anything it covers, and stacks its parts down the block axis so the body is the only one that scrolls. Capped at the height of the box around it, so a sheet with more in it than the screen holds stops at the top of the viewport instead of running off it — and at height="tall" and height="full" it takes that whole measure rather than its contents'.
+  
+  It fills the frame's width rather than holding one of its own. The cap that keeps a sheet from going full-bleed across a tablet is the frame's, which is all the frame is left holding now that both ends are inside this panel rather than ranged to its edges from outside. The bottom corners stay square either way, because the sheet still meets the bottom of the screen — and at height="full" the top pair go square with them, each corner following the same rule: an edge that meets the page is rounded, an edge that meets the screen is not.
+  
+  It clips, which is what keeps the header's square edges inside the rounded ones. That is also why both ends are in the header rather than over the panel: anything drawn above this element's top edge from within it is cut off at that edge, so a control that floated there would have to be a sibling of the panel rather than a part of it — which is product's arrangement and not this one's. Its type is the default body step rather than the large one, and everything inside inherits it: a sheet is read on a phone at arm's length rather than scanned down a page, and the larger step is for copy with a column to run in. The description in the header sits at the same step now and stays the quieter of the two by its ink rather than by its measure — which is the argument that part already makes for itself.
+- `handle` — `<div>`, class `dds-bottomsheet__handle`. The bar that says the sheet can be pulled down. Drawn only when a drag is what dismisses it, because a grab bar on a sheet that does not answer a drag is an affordance that lies.
+  
+  It is the mark and not the target. The whole header answers the pull, so the bar can stay as small as it reads best at — nothing depends on anybody hitting it. Not the content below, which scrolls: a touch gesture beginning in a scroll container belongs to the scroller, and the browser keeps it whether or not there is anything to scroll.
+  
+  It refuses the browser's own vertical pan, so a pull here reaches the sheet. Left to itself the browser claims a downward swipe, cancels the gesture one move in, and the sheet never answers a finger — which is what it did: the drag worked with a mouse and did nothing at all on touch, the one input a sheet is for. The content keeps its native scrolling, which is why this sits on the chrome and not on the surface above it. Rendered only when `showHandle` is set.
+- `header` — `<header>`, class `dds-bottomsheet__header`. The row across the top: the title, whatever qualifies it, and a slot at each end. The ends are what decide where the title sits — with a way back at the leading end the row reads as a bar between two controls and the title centres in what they leave; with nothing there it ranges to the start, because a centred title in a row that is empty on one side floats rather than centres. That is a relationship rather than a value, so it is asked in the stylesheet and not bound here.
+  
+  It carries the space above itself and none below: the content underneath states its own distance from whatever is over it, so that measure survives this row not being drawn.
+  
+  And it is as tall as what is in it, with no floor under it. One was bound here, meaning to keep a control's worth of height whether or not a control was drawn — but it sat on the border box, so the padding nearly satisfied it and it only ever bit once the padding halved. What it bought then was slack the title floated in: a handle sheet's title dropped six pixels below where the same title sits with a button beside it. A row with nothing in it is short, which is what a row with nothing in it should be.
+  
+  It refuses the browser's own vertical pan, so a pull here reaches the sheet. Left to itself the browser claims a downward swipe, cancels the gesture one move in, and the sheet never answers a finger — which is what it did: the drag worked with a mouse and did nothing at all on touch, the one input a sheet is for. The content keeps its native scrolling, which is why this sits on the chrome and not on the surface above it.
+- `leading` — `<div>`, class `dds-bottomsheet__leading`. The leading end of the header, which holds the way back rather than the way out. A sheet reached from another sheet is a step in something, and the control that returns to the previous step belongs at the edge the reader came from — opposite the exit, not beside it. The two are different questions: back undoes one step, close abandons the task.
+  
+  Inside the panel rather than above it, which is where this package parts company with product. Product hangs both ends in the gap over the sheet, on the argument that the panel should hold the task and nothing else. A marketing sheet is read on a page it was opened from, and a control floating between the scrim and the panel reads as belonging to neither — so the header holds its own ends, and the panel is the whole of what the reader is in.
+  
+  Absent unless a back control is given, which is most sheets. It takes no inset of its own: the header pads the row, and an end that padded itself as well would sit a measure further in than the title it lines up with. Rendered only when `back` is set.
+- `heading` — `<div>`, class `dds-bottomsheet__heading`. The title and whatever qualifies it, and nothing else. It sits between the two ends of the header and grows into whatever they leave, which is the whole of the arrangement now that the title ranges to the start of it.
+  
+  That is why there is no alignment to choose. Product offers a centred title and has to: its ends hang above the panel, so the row is the title's alone and centring it is free. Here the ends are in the row, and a centred title would be centred on what is left between two controls of different widths — half a button off true, and off by a different amount on every sheet, which is worse than the decision being unavailable. Ranged to the start it lines up with the body beneath it and with every other sheet, whatever is at either end.
+- `title` — `<h2>`, class `dds-bottomsheet__title`. What the sheet is for, in the reader's words. An element of its own rather than text in the header, for two reasons that both bite: a heading needs a heading to be one, and the dialog names itself by pointing at this — pointing at the header instead would fold the close button's own name into the sheet's.
+  
+  One line, cut with an ellipsis rather than wrapped. A wrapped title cannot line up with the controls beside it: a line box is half the height of a control, so the first line of two sits above the middle of the button facing it, and no token can close that gap — what is needed is half the difference between two other measures, which is arithmetic rather than a decision. Every reference this component was drawn from keeps the title to one line, which is the same thing said from the other side. The full words are still the sheet's accessible name, so nothing is lost to a screen reader. It is set in the title role, which this package gained for it: bold at the smallest heading step, and a step under h5 so the name of a sheet does not arrive at the scale of a section of the page behind it. Product has the same role and sets it semibold; this package’s headings run heavier throughout, so bold here is it being itself rather than a disagreement.
+- `trailing` — `<div>`, class `dds-bottomsheet__trailing`. The trailing end of the header, and where a reader looks for the way out of anything. The close button is last in it and so outermost — nearest the corner, which is the one place it is worth being unable to miss — and whatever the screen adds sits before it, between the action and the title.
+  
+  That order is the whole point of the part. A close button that moved to make room for an action would be a way out that is somewhere else on every screen, and a reader who has learnt one sheet would be wrong about the next. So the exit is pinned to the end and everything else is inserted before it.
+  
+  Inside the panel rather than above it, for the reason the leading end gives, and it takes no inset of its own for the same one. It takes the width of what is in it and no more. It once declared a minimum, which it needed while the ends hung above the panel and had to reserve a measure there — inside the header that minimum only showed when the end held a single control, holding the exit eight pixels off the edge on those rows and flush on the rest. Two alignments for the one thing a reader is meant to find in the same place every time. Rendered when any of `showClose`, `action` is set, and not otherwise.
+- `description` — `<p>`, class `dds-bottomsheet__description`. The line under the title that qualifies it — what the task applies to, or what it still needs before it can be done. Helper text, and set at the step this package keeps for it: it qualifies what the title already said — what an action will do, what a choice costs — rather than adding anything the title left out. Muted as well as small, because it is read after the title rather than instead of it, and it is what the dialog points at with aria-describedby so it is announced with the sheet rather than found later.
+  
+  One line, cut with an ellipsis, for the reason the title above it is: the controls either side centre against this block, so every line it gains moves them further from the words they belong to and grows the row by a line's worth. Held to one, the header is as tall as what is in it rather than as tall as what somebody typed.
+  
+  The full words still reach a screen reader, which is what makes the cut a visual one.
+  
+  It takes no colour of its own, so it comes out the same ink as the title above it. Neither binds a default colour — both inherit — which is what makes the pair agree on any ground rather than only on the one they were drawn against. Size is what separates them, and size is enough: a title at font.title over a description at body-sm is already a hierarchy, and setting the second one a step lighter as well says it is an aside. A description is not an aside — it is the half of the pair that says what the thing actually is. Rendered only when `description` is set.
+- `body` — `<div>`, class `dds-bottomsheet__body`. The slot. Everything below the header is the consumer's — a form, a list, a summary, an action row — and the sheet has no opinion about it beyond where it starts and that it is the only part that scrolls.
+  
+  It carries its own inset on all four sides, which is what makes it independent of the row above it. The space between the header and the content used to be the header's bottom padding, so the content's distance from the top of the sheet was a fact held by a part that might not be there — and with the header hidden the content would have met the sheet's edge. Stated here, it is the same measure whether something sits above it or nothing does.
+  
+  It is also allowed to shrink below its content so the sheet's cap actually bites: without the floor removed, a flex item refuses to go under its content's height and the overflow moves to the sheet, taking the header off the screen with it. Its inset is the compact step rather than the container one, and so is the header's above it, so the sheet pads uniformly on every side. A sheet is a phone surface pinned to the screen's own edges, where the wider step a card takes would spend a quarter of the width on air — a card sits on a page with room around it and can afford that, and a sheet is the page. The role naming that step is described for a row of a list rather than for a container, which is the closest this package has to a compact inset and is worth knowing before somebody reads the binding as a mistake. Its top inset is two steps under its other three, and it is the only thing between the title and the first line of the task: the header pads above its row and not below it, so the air under the name of the sheet is the body's to set. A full step there read as a gap rather than as a join, the two being one thing a reader takes in at once — and a step under that still did, the line-height either side of the join contributing air no padding token can take back.
+
+Apply these classes from the generated `bottomSheetParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Can contain: any content
+- Never contains: `BottomSheet` — in children or in any prop that takes a node
+
+## Props
+
+### open — `boolean` (default `false`)
+
+Use when: The sheet is showing. The consumer owns this outright — the sheet never sets it, and asks to be closed through onOpenChange instead.
+
+Flipping it is the whole animation. The layer fades from opacity.hidden and the sheet scales up from motion.scale.enter about its own bottom edge, over motion.duration.slow on motion.easing.enter, so it reads as rising from the screen's edge rather than appearing over the middle of it. Shutting is not animated: transition-duration is motion.duration.instant while closed, because the reader has already asked to be somewhere else. Do not write a transition of your own — the stylesheet declares transition-property from what this axis changes, and a second declaration would both override that list and escape the prefers-reduced-motion guard generated with it.
+Never for: Keeping a sheet on screen the reader has asked to leave. Refusing to answer onOpenChange does not make the sheet modal, it makes it stuck: Escape, the scrim and the close button all report and none of them acts.
+
+### height — `hug` | `tall` | `full` (default `hug`)
+
+- `hug` — The sheet is as tall as what is in it, up to the screen. The default, and right for anything bounded — a handful of choices, a confirmation, a summary. A sheet taller than its contents is a band of empty white the reader has to look past to reach the thing they came for
+- `tall` — The sheet takes the screen, less a strip of page at the top. For a form, a long list, or content that grows as it arrives: each of those would otherwise resize the sheet while the reader is using it, and a surface that moves under a finger is worse than one that is taller than it needs to be
+- `full` — The sheet is the screen: no strip of page and square corners, with the header's row of controls meeting the top of it. For the task that is briefly the whole of the phone — a payment form, a profile step — opened from a page the reader returns to when it closes.
+
+It asks to be left visibly: the way out is a button the type insists on (`showClose`, which retires the handle through the pair rule), because everything else that says 'sheet' has gone — there is no scrim left to press and no strip of page to say a page is waiting, and Escape works but cannot be seen. A sheet that is a step in a sequence draws `back` at the leading end as well; the exit keeps the corner either way. The title keeps the full width; the bar above it holds the same line the strip held at tall, at the same measures.
+
+It is also the one height that releases the sheet's width cap. hug and tall stop at size.sheet.max and centre, because a sheet is a layer over a page; full is the screen itself, and a screen has no edges to centre between. That makes it a phone presentation outright — on anything wide enough for a centred modal the same task wants one, which this package does not yet have
+Never for: A middle height — half the screen for a list, say. There is no step for it and the omission is deliberate rather than pending: a fraction of the viewport is not something the token layer can hold, its dimensions being pixel steps that resolve to a Figma FLOAT, and inventing a pixel height for it would be a number that is right on one handset and wrong on the next. A list that outgrows `hug` takes `tall` and scrolls.
+
+### title — `string` **Required.**
+
+Use when: Always. It is the sheet's accessible name as well as its heading, so a sheet without one is announced as a dialog and nothing else. A noun phrase naming the task, in sentence case: "Filter results", not "Would you like to filter these results?"
+Never for: A sentence of explanation. That is the description, which sits under this and is announced after it — a title that runs to a sentence is read out in full every time the sheet opens, and is cut with an ellipsis here rather than wrapping. It has the full width of the sheet now that no control shares its row, so what the one line buys is no longer alignment with the buttons beside it: it is a header that is as tall as a header rather than as tall as what somebody typed, on a surface whose whole purpose is to be shorter than the page behind it.
+
+### showTitle — `boolean` (default `true`)
+
+Use when: The default, and almost always right. Turn it off where the content immediately under the header already names the task and a second visible name would say it twice — a picker whose first row is the heading, a sheet that is one photograph. The title is still rendered and still announced either way; only its pixels go.
+Never for: A sheet whose purpose is merely obvious to whoever built the screen. What is obvious beside the thing it opens from is not obvious to a reader hearing the page one control at a time, and turning this off hides the name from everyone who can see and nobody who cannot. It is also not a way to reach a header with nothing in it: the row still holds whatever controls it was given, and a sheet needing neither takes neither.
+
+### description — `string`
+
+Use when: The title needs qualifying — what the task applies to, or what it still needs before it can be done. "Date and both airports required", or the account a transfer is coming from. It sits directly under the title and is announced with it.
+Never for: A sentence, and anything longer than one. It has the sheet's full width, the controls being above the panel rather than either side of it — but it is cut rather than wrapped, so a sentence does not arrive shorter, it arrives with its end missing.
+
+Anything the reader operates, scrolls, or reads at length belongs in the content, which is the part that scrolls and has the whole height to do it in; this stays on screen above it.
+
+### showClose — `boolean` (default `false`)
+
+Use when: The way out has to be visible — a sheet over a task the reader may not realise they can leave, or one whose content reaches the top of the screen so there is little scrim left to press. It draws the close button above the sheet's top edge, at the trailing corner, outermost: nothing the screen adds goes outside it, so the exit is in the same place on every sheet that draws one.
+
+Turn the handle off to reach it: the two are alternatives, so this is `showClose showHandle={false}`. Off by default, because a sheet that can be flicked away rarely needs a button as well.
+Never for: Deciding whether the sheet can be left. It cannot stop that and does not try, which is what the name is for — it used to be `dismissible`, which read as the permission rather than the button: a press outside the sheet and Escape always close it, whatever this says. What it decides is whether the exit is a control the reader can see and press.
+
+Nor for drawing a second way out beside the handle. They are one decision, and the type refuses the pair rather than leaving it to be noticed in review.
+
+### back — `node`
+
+Accepts: ButtonIcon
+Use when: The sheet is a step rather than the whole task — one of a sequence, or a panel reached from another panel — and the reader needs the step before it. One control, icon-only, at the leading edge above the sheet, opposite the way out.
+
+It is your ButtonIcon, so the glyph and the variant are yours; secondary is what sits level with the close button. The size is not — see below.
+
+It does not close the sheet and is not reported through onOpenChange: going back is the consumer's own navigation between whatever the sheet is showing, and a sheet that treated it as a way out would throw the task away on the one press that meant "not this bit".
+Never for: The way out. That is showClose, at the other end, and the two must not be confused by putting a dismiss glyph here — a reader who takes one for the other loses the task. Back undoes a step; close abandons the sheet.
+
+A size other than md, which is the rule the action takes and for the same reasons: it is one line with the close button, and a larger control beside a size.control.md one is two controls that were meant to match and do not. The line also has a ceiling — at height="tall" it sits in the strip size.sheet.peek leaves at the top, and md with its gap comes to 48 of those 56.
+
+### action — `node`
+
+Accepts: ButtonIcon
+Use when: The screen needs one more control above the sheet — a confirm for a form the sheet is collecting, help for a task that needs explaining. One control, icon-only, at the trailing end beside the way out and immediately before it: the close button keeps the corner, and this sits inside it.
+
+It is your ButtonIcon, so its variant is yours: primary for a confirm that has to carry weight, destructive for one that removes something, secondary to sit level with the close. The size is not — see below.
+
+It asks for `showClose`, and the reason is the corner: an action alone at the trailing end sits exactly where a reader reaches for the exit, and is pressed by somebody who meant to leave. Where the sheet is a step in a sequence, the control that goes back belongs at the other end — that is `back`, not this.
+Never for: A size other than md. It no longer takes the title off the centre line — out of the row, nothing it does moves the words below it — but it shares a line with the close button, and a larger control beside a size.control.md one is two controls that were meant to match and do not. The line also has a ceiling: it sits above the sheet's top edge, which at height="tall" is inside the strip size.sheet.peek leaves at the top. md and its gap come to 48 of those 56; lg comes to 56, which is the whole of it. Nothing refuses either, so this is the only place it is said.
+
+Nor for the action that finishes the task. That belongs in the content, where it can carry words: an icon alone cannot say “Send 250 USD”, and the top of a sheet is where a reader looks for the way out rather than the way on.
+
+### showHandle — `boolean` (default `true`)
+
+Use when: On by default. It draws the handle at the top of the sheet — the bar that says the surface can be moved, which is the cheapest way to say so.
+
+It does not decide whether the pull works. That is the sheet's whatever this says, the same way a press outside it is: a reader pulls a sheet down because it is a sheet, not because a bar was painted at the top. Where the pull is answered is the header, drawn or bare — the content scrolls instead. What turning this off buys is a header with the exit as a button instead.
+Never for: Turning the gesture off. It draws the handle and nothing more — a pull is answered on a sheet with a close button and on one with neither, the same way a press outside it is. The name says that now; it used to be `dragToDismiss`, which claimed a power over the gesture it never had.
+
+Nor for a sheet that also draws a close button: the two affordances are alternatives and the type refuses the pair.
+
+It also needs no turning off to protect what is inside. The pull is answered on the header and the handle only — the content is the scroller's, on every input — and it never begins on a control that answers a pointer itself, so a Slider in the content moves its own thumb rather than the sheet.
+
+### onOpenChange — `callback` **Required.**
+
+Use when: Always. The sheet does not close itself, so this is the only way out — write the first argument straight back to `open`. Named the way DropdownMenu names its own, because a reader who has wired one controlled disclosure in this package should not have to learn a second word for the same job.
+
+The second argument is which of the four ways out the reader took, for a page that treats an abandoned task differently from a finished one. It is only ever called with false today — a sheet is opened by whatever opens it, never by itself — and the boolean is first anyway, so the shape does not have to change if that ever stops being true.
+Never for: Doing the task. This fires when the sheet is being left, including when it is being left unanswered — commit from the actions in the footer, where the reader pressed something that says what it does.
+
+Also accepts everything from `HTMLAttributes<HTMLDivElement>`.
+
+## Accessibility
+
+Guaranteed by the component. Write none of it by hand: the ids these attributes point at are generated per instance, so an attribute set from outside either says the same thing twice or points at nothing.
+
+- Announced as: `dialog`
+- `Escape` — close, which reports through onOpenChange with reason "escape". Always, and not conditioned on anything the sheet draws: a reader on a keyboard can use neither the handle nor a press outside, so a sheet that took Escape away from them would be one they could not leave. Reported rather than done, like every other way out — the sheet does not own whether it is open
+- `Tab` — move to the next control inside the sheet, wrapping at the last one back to the first. Focus does not leave while the sheet is open — a reader who tabs past the end and lands on the page behind is operating something the scrim says they cannot
+- `Shift+Tab` — the same, backwards, wrapping at the first control to the last
+- an accessible name, taken from the title, so the sheet is announced as the task it holds rather than as a dialog
+- the description announced with the sheet, through aria-describedby pointing at the element carrying it
+- aria-modal on the sheet, so a screen reader confines its reading to what is inside it rather than reading the page the scrim has covered
+- focus moved into the sheet when it opens, and returned to whatever opened it when it closes. Focus left on the page behind is a reader operating controls the scrim already refuses the pointer
+- focus held inside the sheet while it is open, wrapping at both ends rather than escaping to the page
+
+## 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
+
+❌ BottomSheet for: The message is a passing notification the reader does not have to answer
+   A sheet covers the page and waits to be dismissed, which is the opposite of what a notification asks for. Nothing in this system does this yet, so the honest answer is that there is no component to reach for rather than a nearest one that would be wrong
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ BottomSheet for: The viewport is wide enough for a centred modal
+   A sheet is a small-screen pattern: pinned to one edge and full-bleed across it. On a desktop viewport that reads as a page element that has come loose rather than as a layer over the page
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ BottomSheet for: The reader is choosing one answer from a set, inside a form
+   A set of answers belongs to the control it answers, and a list pinned to that control keeps the question on screen beside it. A sheet covers the question with the answers
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ BottomSheet for: A short description of the control the pointer is on
+   A sheet has to be dismissed; a tooltip goes away by itself. Covering the page to explain a control is a cost the explanation does not earn
+   → use `Tooltip` instead.
+
+❌ showHandle=true + showClose=true
+   A sheet says how to leave it once. The handle is a bar to pull and the close button is a control to press, and drawn together they stack two answers to one question at the top of the sheet — the reader reads both before finding out they do the same thing
+
+❌ height=full + showClose=false
+   A full sheet has taken away every other visible way out: the scrim is entirely covered, and there is no strip of page above the surface to say a page is still there. Escape still works and cannot be seen; the close button is the one exit a reader can find by looking, so a full sheet must draw it. The handle follows without a rule of its own — close and handle are already forbidden together, so requiring the button retires the bar. The pull itself still works, answered on the header as always; what full retires is the bar that advertised it
+
+## Example
+
+```tsx
+import { BottomSheet } from '@deriv-com/dds-marketing'
+
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open title="Filter results">Markets, date range and contract type</BottomSheet>
+```
+
+## In use
+
+### Ways out
+
+A sheet says how to leave it once: a handle to pull, or a close button to press. The handle is the default and the two cannot both be drawn. Turn both off only when the task has to be finished.
+
+```tsx
+import { BottomSheet, ButtonIcon } from '@deriv-com/dds-marketing'
+import { PenSolidIcon } from '@deriv-com/quill-icons-web'
+
+// The handle alone, which is the default
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open title="Filter results">Markets, date range and contract type</BottomSheet>
+
+// A close button instead, at the end of the row
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose title="Filter results" showHandle={false}>Markets, date range and contract type</BottomSheet>
+
+// An action sits inside the exit, never outside it
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose action={<ButtonIcon variant="plain" size="sm" label="Edit saved filters" icon={<PenSolidIcon />} />} title="Filter results" showHandle={false}>Markets, date range and contract type</BottomSheet>
+
+// Neither: the task is finished from the content
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose={false} showHandle={false} title="Confirm your withdrawal" description="Cannot be reversed once sent">To Nadia Rahman, ending 4417 — with Go back and Send below it</BottomSheet>
+```
+
+### The title and the ends
+
+It ranges to the start and stays there, whatever is at either end of the row. That is why there is no alignment to choose: centring would move with the controls.
+
+```tsx
+import { BottomSheet, ButtonIcon } from '@deriv-com/dds-marketing'
+import { PenSolidIcon } from '@deriv-com/quill-icons-web'
+
+// The title alone
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose={false} showHandle={false} title="Filter results">Markets, date range and contract type</BottomSheet>
+
+// With the way out at the end
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose showHandle={false} title="Filter results">Markets, date range and contract type</BottomSheet>
+
+// And an action before it — the title has not moved
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose showHandle={false} title="Filter results" action={<ButtonIcon variant="plain" size="sm" label="Edit saved filters" icon={<PenSolidIcon />} />}>Markets, date range and contract type</BottomSheet>
+```
+
+### A step in a sequence
+
+A sheet reached from another sheet needs the step before it. Back takes the leading end and the exit keeps the trailing corner: back undoes one step, close abandons the task.
+
+```tsx
+import { BottomSheet, ButtonIcon } from '@deriv-com/dds-marketing'
+import { ArrowLeftRegularIcon, PenSolidIcon } from '@deriv-com/quill-icons-web'
+
+// The way back, opposite the way out
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose showHandle={false} back={<ButtonIcon variant="plain" size="sm" label="Back to filters" icon={<ArrowLeftRegularIcon />} />} title="Choose markets">Forex, Commodities, Stock indices, Cryptocurrencies</BottomSheet>
+
+// And with an action, which stays inside the exit
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open showClose showHandle={false} back={<ButtonIcon variant="plain" size="sm" label="Back to filters" icon={<ArrowLeftRegularIcon />} />} action={<ButtonIcon variant="plain" size="sm" label="Edit saved filters" icon={<PenSolidIcon />} />} title="Choose markets">Forex, Commodities, Stock indices, Cryptocurrencies</BottomSheet>
+```
+
+### What the sheet says
+
+A title alone, or a title with the sentence it left out. Add a description when the reader would otherwise have to guess what the task costs them.
+
+```tsx
+import { BottomSheet } from '@deriv-com/dds-marketing'
+
+// Title alone, where the task explains itself
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open title="Choose a currency">US Dollar, Euro, Pound sterling, Swiss franc</BottomSheet>
+
+// With the sentence the title had no room for
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open title="Close this position" description="Closes at the market price">EUR/USD, 0.5 lots, opened 14 March</BottomSheet>
+```
+
+### How tall it opens
+
+A sheet is as tall as its contents unless you say otherwise. Choose by whether the contents settle: anything that grows while the reader is in it should start at its full height instead.
+
+```tsx
+import { BottomSheet } from '@deriv-com/dds-marketing'
+
+// Hug, which is the default
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open title="Close this position">EUR/USD, 0.5 lots, opened 14 March</BottomSheet>
+
+// Tall, for a form or a long list
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open height="tall" title="Add a payment method">Card number · Expiry · Security code · Name on card · Billing address · City · Postcode · Country · Save this card for next time</BottomSheet>
+
+// Tall, with the exit in the strip above
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open height="tall" showClose showHandle={false} title="Add a payment method">Card number · Expiry · Security code · Name on card · Billing address</BottomSheet>
+
+// Full: the sheet is the screen, the title below its exit
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open height="full" showClose showHandle={false} title="Deposit" description="To your USD account">Amount · Payment method · Card number · Expiry · Security code · Name on card · Billing address · Deposit 250 USD</BottomSheet>
+```
+
+### What goes inside
+
+Everything under the header is one slot the sheet has no opinion about. It sets the inset so content lines up with the title, and scrolls when there is more than fits.
+
+```tsx
+import { BottomSheet } from '@deriv-com/dds-marketing'
+
+// A short summary
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open title="Your order">1.00 USD deposit — we are processing it</BottomSheet>
+
+// A list long enough to scroll
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} open title="Choose a currency">US Dollar, Euro, Pound sterling, Swiss franc, Australian dollar, Canadian dollar, Japanese yen, Singapore dollar</BottomSheet>
+```
+
+### Shut
+
+What a closed sheet is: still mounted, still in the markup, and taken out of the reading order by the stylesheet rather than by the component.
+
+```tsx
+import { BottomSheet } from '@deriv-com/dds-marketing'
+
+// Closed, which is the default
+<BottomSheet onOpenChange={(open, reason) => { /* your handler */ }} title="Filter results">Markets, date range and contract type</BottomSheet>
+```