@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/.llm/components/textarea.md

@@ -0,0 +1,362 @@
+<!-- GENERATED from text-area.contract.json. Do not edit. -->
+
+# TextArea
+
+A field for what a visitor wants to say in their own words — the message on a contact form, the 'tell us about your project' on an enquiry, the reason someone is applying to partner. One value still, like TextInput, but a value with no shape the page can guess at.
+
+That is the whole reason it is not TextInput with a taller box. A single line shows a reader a sliver of what they wrote and no way to read it back, and the one place they most want to check themselves is the paragraph they are about to send a stranger. So it grows as they type, up to a limit, and past that limit it scrolls rather than pushing the submit button off the screen.
+
+It is the most expensive thing a marketing form can ask for. Every other field is a fact the reader already knows — a name, an address; this one asks them to compose something, which is why a form that opens with it converts worse than one that earns it. Ask for it last, ask for it once, and say what it is for.
+
+## Use when
+
+- A contact form asks what the reader actually wants — the message, the enquiry, the question
+- An application or partner form asks someone to describe what they do in their own words
+- Feedback, where the value of the answer is precisely the part no set of options would have caught
+
+## Do not use
+
+- The value is one line — a name, an address, a company → nothing here does this
+- The reader is choosing from a set rather than composing → nothing here does this
+- The page is presenting text rather than collecting it → nothing here does this
+- Opening a form with it. The reader has not decided to spend that much on the page yet, and a large empty box is what tells them how much is being asked
+- Sensitive data. A landing page has no account and no session, and a field big enough for a paragraph is big enough for something that belongs behind a sign-in
+- Anything the page will parse. If the answer has a shape, ask for its shape
+
+## Anatomy
+
+TextArea renders 13 elements. A token binding names the part it applies to.
+
+- `root` — `<div>`, class `dds-textarea`. Stacks three things: the label row, the box holding the field, and the row beneath it. None of the three is the field itself — which is the shape this arrived at rather than started with, once a tooltip needed to sit beside the label and an icon inside the box. Carries the size and status attributes, which is what lets every part below respond to them.
+- `label-row` — `<div>`, class `dds-textarea__label-row`. Holds the label and, when there is one, the button that explains it. A row exists because the trigger cannot sit inside the <label>: a label forwards its clicks to the field, so a button in there is an ambiguous target and the no-nested-interactive rule refuses it. Always rendered, so the markup has one shape whether the field carries an explanation or not.
+- `label` — `<label>`, class `dds-textarea__label`. Names the field. Always rendered — a field whose label is optional is a field that ships unlabelled.
+  
+  Its height is reserved at size.target.min whether or not the explanation is there. The trigger beside it is a target before it is a mark, so it is at least that tall — and a row taking its height from its contents was two different heights depending on a prop: passing labelTooltip pushed the field, the helper and everything under them down by six pixels. The reserve goes here rather than on the row because a label clipped for a screen reader is out of flow, and a row reserving height for something out of flow is a gap over nothing.
+- `required-mark` — `<span>`, class `dds-textarea__required-mark`. Marks the field as one the user must fill — the word "required", or an asterisk when requiredMark says so. Lowercase and close to the label, so the two read as one phrase rather than as a label with a badge beside it. Hidden from screen readers either way, because aria-required on the field already says it and hearing both says it twice. Which is also what keeps the asterisk usable at all: the glyph carries nothing on its own, so a form using it needs a legend, and a screen reader is told by the attribute rather than by a star. Rendered only when `required` is set.
+- `optional-mark` — `<span>`, class `dds-textarea__optional-mark`. Says "optional" beside the label, lowercase like its counterpart. Not hidden from screen readers: there is no ARIA attribute for optional, so this text is the only thing that carries it — which means it becomes part of the field's accessible name, read as "Label optional". Rendered only when `optional` is set.
+- `label-tooltip` — `<button>`, class `dds-textarea__label-tooltip`. Reveals the explanation, on hover and on focus. A button rather than a bare mark because it is a tab stop by intent: an explanation only a pointer can reach is one half the people using the form never see. Its box is wider than its mark on purpose — the glyph is sized to read beside the label and a target is sized to be hit, which are two decisions. It sits above the field rather than in it, which is the only place it could: the field is a block of lines with no trailing edge to speak of, and a second tab stop inside a prose field would come between the writing and whatever follows it.
+  
+  It paints a background on hover, which is the only thing that shows where the target is. The mark is sixteen pixels and the target is twenty-four, and those are separate decisions by this system’s own rule — so a mark that only changes colour leaves the eight pixels around it invisible until a press either lands or does not. The fill is the same one ButtonIcon uses for a button with no fill of its own, because it is the same button.
+  
+  A press darkens the fill further, and nothing moves. A scale would be the other way to say it, and on a mark this size it moves an edge by a pixel — cost without payoff. The fill also says something a one-shot animation cannot: it holds for as long as the button is held, which is what a stepper repeating ten times a second needs to show. The same two fills ButtonIcon uses, because it is the same button. Rendered only when `labelTooltip` is set.
+- `control` — `<div>`, class `dds-textarea__control`. The box the user sees: the border, the fill, the corner and the inset. The textarea drew all of that itself until a leading icon needed somewhere to sit — a <textarea> can hold text and nothing else, so nothing could ever be inside the box while the textarea was the box. Aligned to the start rather than centred, which is the whole difference from TextInput: there the icon and the value share one line, here the value is a block of lines and an icon centred against it would float in the middle of a paragraph and drift down as the field grew.
+- `field` — `<textarea>`, class `dds-textarea__field`. The control the user types into. Transparent and borderless inside the box, which the control part draws — so the text, the placeholder and the caret are all this element has left to be about. Its height starts at rows and follows the text up to maxRows, after which it scrolls; the browser’s own drag handle is suppressed, because two mechanisms for one height is one too many and only one of them has to be found.
+- `footer` — `<div>`, class `dds-textarea__footer`. The row under the field, holding whatever is being said about it on the left and the count on the right. A row rather than two stacked lines, because a message and a count are one thought about the same field. Its presence follows its contents rather than any one prop: a helper, a status message or a limit each brings it, and with none of them it is absent rather than empty — an empty row in a column with a gap would cost a gap and hold nothing. Rendered when any of `helperText`, `status`, `maxLength` is set, and not otherwise.
+- `helper` — `<span>`, class `dds-textarea__helper`. Guidance the user needs before they type — a format, a constraint, why the field is being asked for. Hidden once the field has a status, because that slot belongs to the status message: guidance shown beside a field reporting something would read as though nothing were wrong. A span rather than a paragraph so it has the same box as the error that replaces it — a <p> carries the browser's own margin, which no token can reach, and the two swapping would shift the layout they exist to keep still. Rendered only when `helperText` is set.
+- `message` — `<span>`, class `dds-textarea__message`. The glyph for the status and what the status means, in the colour of the status. The glyph takes that colour from the text beside it rather than binding one, and is decorative to a screen reader because the words say the same thing — its shape is what separates an error from a warning for a reader who cannot tell those two colours apart. Takes the helper text's place rather than stacking beneath it, so the layout does not shift and the user is never told two things at once. A success status may be silent — it is the one status the contract does not require a message for, an error, a warning and a pending check each needing one — in which case only the border reports it. Rendered only when `status` is set.
+- `message-icon` — `<span>`, class `dds-textarea__message-icon`. The box the status glyph sits in, one line of the message tall with the glyph centred in it.
+  
+  Aligned to the start of the block axis a glyph is as tall as itself, so its middle sits above the first line's and the words beside it read as pushed down. The height is the message's font size times its line height, computed in text-area-impl.css because a binding carries one token and not an expression over two. Absent for a pending check, which has no glyph — marketing has no Spinner to turn. Rendered only when `status` is set.
+- `counter` — `<span>`, class `dds-textarea__counter`. How much of the limit is left, shown only where there is a limit. A maxLength without this refuses a keystroke and says nothing, which is the fault it exists to prevent — so the two arrive together rather than being two decisions a form can get half right. Read out when the field takes focus and not on every keystroke: a count that announces itself as it changes talks over the person typing. Rendered only when `maxLength` is set.
+
+Apply these classes from the generated `textAreaParts` constant rather than writing the strings by hand.
+
+## Composition
+
+- Takes no children. Everything it renders comes from props
+- Never contains: `Button`, `TextInput` — in children or in any prop that takes a node
+
+## Props
+
+### size — `sm` | `md` | `lg` (default `md`)
+
+- `sm` — A note field in a dense form, where the box sits among other controls rather than being what the section is for. The height is unchanged — only the corner tightens
+- `md` — The default, and nearly every form on a page — a contact form in a section, an enquiry beside the copy that prompted it
+- `lg` — A form that is the reason the section exists, matched to the fields around it
+
+Use when: Choosing the type and the inset, which is all size means here. It does not set a height — that comes from rows and from the text, so a size and a height are two separate things to decide
+
+### status — `none` | `error` | `warning` | `success` | `pending` (default `none`)
+
+- `none` — Nothing has been checked yet, or the value passed and saying so would be noise
+- `error` — The value cannot be accepted and the user has to change it
+- `warning` — The value is accepted but likely wrong — an address that failed a lookup, a name that does not match the account. The user may continue
+- `success` — The value was checked against something and passed, and confirming that is worth the space — an available username, a verified code
+- `pending` — A check is in flight and its outcome is not known yet — a description going through moderation, an address being looked up, a note being scanned before it is filed. The text stays editable throughout, and the border does not change: pending is not a verdict, so nothing about the box should read as one
+
+Use when: The outcome of a check, and whether one is running. A prose field is judged after it is written rather than while it is being written, so pending is about a check the page started and not about the typing — moderation, a lookup, anything the reader has to wait on. Where nothing is waiting and nothing has been checked, none is the answer
+Never for: Decoration, or a permanent state. A status is the result of checking a value, so a field that always looks like a warning is telling the user nothing
+
+### label — `string` **Required.**
+
+Use when: Always — an input without a label is unusable by screen readers. A noun phrase naming the value, in sentence case: "Email address", not "Enter your email address"
+Never for: The format or the rule, which belong in helperText — a label that explains has stopped naming. And it is a string rather than a node because what joins a label here is the component's own: the required and optional marks render inside it already, so markup passed in would be competing with parts that are declared
+
+### labelTooltip — `string`
+
+Use when: A short explanation the label has no room for and the field does not always need on screen — why a description is asked for, what a reviewer will do with it, what counts as enough detail. Revealed on hover and on focus, so it costs no vertical space above a field that is already the tallest thing on the form
+Never for: Anything the user needs before they start writing, which is helperText and belongs on screen. A tooltip is for the reader who stops to ask, and a prose field is exactly where somebody will not stop — they are already typing. And never for the format or the limit: a rule nobody reads is a rule nobody follows, and maxLength has a count of its own for that
+
+### placeholder — `string`
+
+Use when: Showing an example of the value's shape, alongside helperText that states the rule
+Never for: The label, or the only place the format is stated. Placeholder text disappears the moment the user types and is not an accessible name
+
+### helperText — `string`
+
+Use when: The user needs to know something before they type — a format, a limit, or why this is being asked
+Never for: Validation results, which belong in statusMessage and appear only once validation has run. Note what happens when both are set: any status other than none hides this and shows statusMessage in its place, so guidance and a verdict are never on screen together and the layout does not shift between them
+
+### rows — `number` (default `3`)
+
+Use when: The height the field starts at, in lines, which is also the shortest it ever gets. Three says a sentence or two is expected; ten asks for an essay before anybody has read the label, so the number is a statement about the answer wanted
+
+### maxRows — `number` (default `10`)
+
+Use when: Where the growing stops and the scrolling starts. Needed rather than optional: a field that grows without limit pushes whatever follows it off the screen, and a submit button nobody can reach is worse than a paragraph nobody can see all of. This and rows are the whole of the height decision, and it is made per placement rather than per person: a reply box a support agent lives in gets a larger number than a one-line-or-two field on a sign-up form. There is deliberately no prop offering the browser’s drag handle as an alternative. A handle is reachable by mouse and by nothing else, so choosing it for a placement hands touch and keyboard users a fixed box with no way past it — and whoever picked it, on a desktop, never feels that. A number here works for everyone
+Never for: A number below rows. The two are a floor and a ceiling, and the contract cannot say so — illegalCombinations compares a prop to a value, never a prop to a prop — so the field takes the larger of the two as its ceiling and opens at the height rows asked for.
+
+### maxLength — `number`
+
+Use when: The most the field will accept, which also brings the count that shows it. Give it where the limit is real — a message a system will truncate, a field a database will refuse — and leave it out where prose is simply prose
+Never for: A limit the page enforces later. A field that accepts 400 characters and a form that rejects them is a field that lied, and the count would have been counting toward the wrong number
+
+### statusMessage — `string` **Required when status=error, or when status=warning, or when status=pending.**
+
+Use when: Saying what the status means: what is wrong and how to fix it, what to look at, or what was confirmed. Required for an error, a warning and a pending check — the first two because neither is actionable without it, and the third because a wait with nothing said is a field that has stopped responding. The contract refuses all three combinations. Optional for a success, which the border may report on its own
+Never for: Restating the status. "Error" beside a red field says nothing the colour has not already said, and the colour is the part a colour-blind user may not get
+
+### required — `boolean` (default `false`)
+
+Use when: The form cannot be submitted without this field, and the user should know before they reach the end
+Never for: Validation. It marks and announces the field as required and nothing more — whether the value is acceptable is still decided by the consumer and said through status and statusMessage, so the browser never raises a message of its own that this system cannot style
+
+### requiredMark — `text` | `asterisk` (default `text`)
+
+- `text` — Short forms, public ones, and anywhere the label row has room. The safer default: it needs nothing looked up, it still means something read out of context, and the asterisk convention is learned rather than obvious — which a sign-up or a verification flow cannot assume of everyone using it
+- `asterisk` — Long or dense forms, where the word repeats down the page and one legend can say it once instead — and forms whose labels are too tight for a translated word, since "Required" becomes "Erforderlich" and an asterisk is the same width in every language. Only where a legend is visible from the fields it governs: across steps or a long scroll it is not, and the glyph then says nothing
+
+Use when: Choosing how a required field says so. Decide which state is the exception first — mark the required fields or the optional ones, whichever are fewer — and only then how to mark it
+Never for: Varying within one form. Whichever is chosen is a decision for the whole form: a page marking some labels with a word and others with a glyph reads as two conventions and teaches neither
+
+### optional — `boolean` (default `false`)
+
+Use when: Most fields on the form are required, so the few that are not are worth marking instead
+Never for: Marking every optional field on a form where most are optional — a marker on almost every label is noise, and the useful signal is whichever state is the exception
+
+Also accepts everything from `TextareaHTMLAttributes<HTMLTextAreaElement>`.
+
+## States
+
+States you set. Everything else is driven by the browser.
+
+- `disabled` — The field is unavailable and the user cannot make it available here
+  Avoid when: The field is merely empty — that is what validation is for
+- `readonly` — written `readOnly` in JSX — The value is fixed but still worth reading — a pre-filled account number, a computed total, something awaiting verification. The field stays focusable and its text selectable, which is what separates it from disabled
+  Avoid when: The field is unavailable rather than fixed. That is disabled, and it recedes
+
+## 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: `textbox`
+- `Tab` — move focus
+- programmatic label association
+- aria-invalid when the status is an error
+- aria-describedby pointing at statusMessage
+- aria-describedby pointing at helperText when no status is showing
+- aria-required when required
+- the count is described rather than announced — read when the field takes focus, and not again on every keystroke, because a number that talks as it changes talks over the typing
+- aria-busy while a check is in flight, and a spinner beside the message that says what is being waited on
+
+## 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
+
+❌ TextArea for: The value is one line — a name, an address, a company
+   TextInput. A box three lines tall asks for three lines, and a reader who gives one has been shown a form that misjudged what it wanted from them.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ TextArea for: The reader is choosing from a set rather than composing
+   Nothing here does this yet. Free text where a choice was meant has to be parsed, corrected and matched, and every mismatch is a submission the page silently loses.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ TextArea for: The page is presenting text rather than collecting it
+   That is copy. A read-only field holding a paragraph is a paragraph in a box, with a scrollbar the reader did not ask for and none of the typography the page sets for prose.
+   → nothing in this system does this. Not a gap waiting to be filled — the case belongs outside it.
+
+❌ required=true + optional=true
+   A field is one or the other, and marking it both says nothing
+
+❌ status=error + statusMessage missing or empty
+   An error with no explanation leaves the user stuck
+
+❌ status=warning + statusMessage missing or empty
+   A warning with no explanation is a field the user cannot act on
+
+❌ status=pending + statusMessage missing or empty
+   A wait with nothing said is a field that has stopped responding. TextInput allows this and puts a spinner at the trailing edge of its box instead — a one-line field has room beside the value. The same position here is the bottom-right corner of a block, which is the counter and, past maxRows, the scrollbar. So there is nowhere inside the field for a mark to go, and the words in the footer are the only thing that can carry it
+
+## Example
+
+```tsx
+import { TextArea } from '@deriv-com/dds-marketing'
+
+<TextArea label="Your message" placeholder="What can we help with?" helperText="We reply to every enquiry within two working days." rows={4} maxLength={500} />
+```
+
+```tsx
+import { useState } from 'react'
+import { TextArea } from '@deriv-com/dds-marketing'
+
+// Controlled: TextArea reports the DOM event, so the value is read off it.
+// Unlike AmountInput and SearchInput, which declare an onChange that hands back the
+// value itself — the two shapes look the same at the call site and are not.
+const [value, setValue] = useState('')
+<TextArea label="Your message" placeholder="What can we help with?" helperText="We reply to every enquiry within two working days." rows={4} maxLength={500} value={value} onChange={(event) => setValue(event.target.value)} />
+```
+
+## In use
+
+### Three sizes, three jobs
+
+The small one only tightens the corner — rows set the height. The default sits in a section's contact form. The large one matches a form the section is built around.
+
+```tsx
+import { TextArea } from '@deriv-com/dds-marketing'
+
+// sm — only the corner; rows still set the height
+<TextArea label="Your message" placeholder="What can we help with?" size="sm" />
+
+// md — a contact form inside a section
+<TextArea label="Your message" placeholder="What can we help with?" size="md" />
+
+// lg — the form a whole band is built around
+<TextArea label="Your message" placeholder="What can we help with?" size="lg" />
+```
+
+### It grows with what is typed
+
+rows is the floor and maxRows the ceiling. Past the ceiling the box stops growing and scrolls, so a long message never pushes the submit button off the screen.
+
+```tsx
+import { TextArea } from '@deriv-com/dds-marketing'
+
+// The default — three lines, room for ten
+<TextArea label="Your message" placeholder="What can we help with?" />
+
+// A short box that still grows to ten
+<TextArea label="Your message" placeholder="What can we help with?" rows={2} />
+
+// A box that never grows: floor meets ceiling
+<TextArea label="Your message" placeholder="What can we help with?" rows={4} maxRows={4} />
+```
+
+### Saying how much room there is
+
+maxLength draws a count beside the helper. The limit is the one the page will honour — a field that accepts 500 and a form that rejects them is a field that lied.
+
+```tsx
+import { TextArea } from '@deriv-com/dds-marketing'
+
+// A limit, and the count that goes with it
+<TextArea label="Your message" placeholder="What can we help with?" maxLength={500} />
+
+// A limit beside a helper, sharing the footer
+<TextArea label="Your message" placeholder="What can we help with?" maxLength={500} helperText="Tell us roughly what you need — detail helps us route it." />
+```
+
+### The four verdicts a check can return
+
+Each carries a message. The colour is the part a colour-blind reader may miss and the shape beside it is the part that survives.
+
+```tsx
+import { TextArea } from '@deriv-com/dds-marketing'
+
+// error — the message has to change
+<TextArea label="Your message" placeholder="What can we help with?" status="error" statusMessage="Tell us a little about what you need before sending." />
+
+// warning — it will send, but it is thin
+<TextArea label="Your message" placeholder="What can we help with?" status="warning" statusMessage="A sentence or two helps us route this to the right person." />
+
+// success — a check ran and passed
+<TextArea label="Your message" placeholder="What can we help with?" status="success" statusMessage="Thanks — we have everything we need." />
+
+// pending — no spinner; the words are all
+<TextArea label="Your message" placeholder="What can we help with?" status="pending" statusMessage="Sending your message…" />
+```
+
+### Marking what the form expects
+
+Mark the exception, not the rule. A form where every field carries a mark has said the same as one where none does.
+
+```tsx
+import { TextArea } from '@deriv-com/dds-marketing'
+
+// required — the word, which needs no key
+<TextArea label="Your message" placeholder="What can we help with?" required requiredMark="text" />
+
+// requiredMark asterisk — for a dense form
+<TextArea label="Your message" placeholder="What can we help with?" required requiredMark="asterisk" />
+
+// optional — the one field that may be skipped
+<TextArea label="Your message" placeholder="What can we help with?" optional />
+
+// labelTooltip — a sentence the label has no room for
+<TextArea label="Your message" placeholder="What can we help with?" labelTooltip="We use this to route your enquiry, and nothing else." />
+```