prime-ui-kit 0.0.1

package/src/components/tabs/examples/examples.module.css

@@ -0,0 +1,79 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.body {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.settingsRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-l);
+  align-items: flex-start;
+}
+
+.settingsContent {
+  flex: 1 1 0;
+  min-width: min(100%, 20rem);
+}
+
+.surface {
+  width: 100%;
+  max-width: min(100%, 36rem);
+  padding: var(--prime-sys-spacing-m);
+  border-radius: var(--prime-sys-shape-radius-m);
+  border: var(--prime-sys-unit-1px) solid var(--prime-sys-color-border-subtle);
+}
+
+.fullWidthRoot {
+  width: 100%;
+  min-width: 0;
+}
+
+.fullWidthList {
+  width: 100%;
+  min-width: 0;
+}
+
+.flexTab {
+  flex: 1 1 0;
+  min-width: 0;
+  justify-content: center;
+}
+
+.narrowShell {
+  width: 100%;
+  max-width: 12rem;
+  min-width: 0;
+}
+
+.controlledCaption {
+  margin: var(--prime-sys-spacing-s) 0 0;
+  color: var(--prime-sys-color-content-muted);
+  font-size: var(--prime-sys-typography-role-bodySmall-fontSize);
+}
+
+.sizesRow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x6);
+  align-items: stretch;
+  width: 100%;
+}
+
+.sizesGroup {
+  width: 100%;
+  min-width: 0;
+}
+
+.sizesLabel {
+  margin: 0 0 var(--prime-sys-spacing-x2);
+  font-size: var(--prime-sys-size-control-s-supportText);
+  font-weight: var(--prime-sys-typography-weight-medium);
+  line-height: var(--prime-sys-typography-body-lineHeight);
+  color: var(--prime-sys-color-content-secondary);
+}

package/src/components/tag/COMPONENT.md

@@ -0,0 +1,97 @@
+# Tag
+
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+
+## About
+
+A compact chip-style label: optional leading icon (`Tag.Icon`), optional removable close control when `onRemove` is set. Root is a `span` with `data-size` / `data-disabled`; the inner body wraps children in `ControlSizeProvider` so nested icons pick up the same control size tier.
+
+**When to use**
+
+- Filter chips and applied facets where each selection should be dismissible in one click.
+- Selected values (recipients, skills, topics) with optional removal.
+- Tight metadata labels (environment, version, channel) when a pill shape reads better than body text; add `Tag.Icon` when a small glyph clarifies meaning.
+
+**When not to use**
+
+- As a toggle or single-choice control — prefer [Checkbox](../checkbox/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), or [Select](../select/COMPONENT.md).
+- When the whole chip must navigate or submit a primary action — prefer [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md).
+- Expecting localized copy for the remove control without wrapping — the built-in remove `aria-label` is fixed to `"Remove"` in source; name the surrounding group (`aria-label` / `aria-labelledby`) for context.
+- As a numeric or status **badge** — prefer [Badge](../badge/COMPONENT.md) when the UI is count-only or notification-style.
+
+## Composition
+
+- **`Tag.Root`** — outer `span`; holds a **`span`** body with **`ControlSizeProvider`** around **`children`**, then an optional remove **`button`** when **`onRemove`** is defined. Put plain text, **`Tag.Icon`**, or other nodes inside **`Tag.Root`**; place **`Tag.Icon`** before text when both are used so the icon sits on the left.
+- **`Tag.Icon`** — wrapper **`span`** for the icon node; inherits size from the surrounding **`Tag.Root`** context.
+
+### Canonical example
+
+```tsx
+import { Tag } from "prime-ui-kit";
+
+export function Example() {
+  return <Tag.Root>Design systems</Tag.Root>;
+}
+```
+
+### Scenarios (playground + `examples/`)
+
+Live demos use **`playground/snippets/tag/*.tsx`** (see **`playground/sections/TagSection.tsx`**). The table lists the same scenarios with package-oriented copies under **`examples/`** (aligned with those snippets; playground uses `@/` imports and shared `playground.css` layout classes).
+
+| Scenario | Snippet | Package example |
+|----------|---------|-----------------|
+| Sizes | [`playground/snippets/tag/sizes.tsx`](../../../playground/snippets/tag/sizes.tsx) | [`examples/sizes.tsx`](./examples/sizes.tsx) |
+| States | [`playground/snippets/tag/states.tsx`](../../../playground/snippets/tag/states.tsx) | [`examples/states.tsx`](./examples/states.tsx) |
+| Composition | [`playground/snippets/tag/composition.tsx`](../../../playground/snippets/tag/composition.tsx) | [`examples/composition.tsx`](./examples/composition.tsx) |
+| Basic | [`playground/snippets/tag/basic.tsx`](../../../playground/snippets/tag/basic.tsx) | [`examples/basic.tsx`](./examples/basic.tsx) |
+| Removable (dismiss + restore) | [`playground/snippets/tag/removable.tsx`](../../../playground/snippets/tag/removable.tsx) | [`examples/removable.tsx`](./examples/removable.tsx) |
+| With icon | [`playground/snippets/tag/with-icon.tsx`](../../../playground/snippets/tag/with-icon.tsx) | [`examples/with-icon.tsx`](./examples/with-icon.tsx) |
+| Controlled list | [`playground/snippets/tag/controlled.tsx`](../../../playground/snippets/tag/controlled.tsx) | [`examples/controlled.tsx`](./examples/controlled.tsx) |
+| Disabled | [`playground/snippets/tag/disabled.tsx`](../../../playground/snippets/tag/disabled.tsx) | [`examples/disabled.tsx`](./examples/disabled.tsx) |
+| Context `size` | [`playground/snippets/tag/context-size.tsx`](../../../playground/snippets/tag/context-size.tsx) | [`examples/context-size.tsx`](./examples/context-size.tsx) |
+
+**Additional extended examples** (richer layout / copy, same building blocks):
+
+- [`./examples/01-filter-chips.tsx`](./examples/01-filter-chips.tsx) — Catalog filters: applied facets as removable chips backed by a `Set` in state (`fieldset` + `legend`).
+- [`./examples/02-removable-selected-values.tsx`](./examples/02-removable-selected-values.tsx) — Selected skills: removable tags in a named group for remove-button context.
+- [`./examples/03-status-metadata.tsx`](./examples/03-status-metadata.tsx) — Release-style metadata: read-only chips with `Tag.Icon` + text, no `onRemove`.
+
+**LLM note:** Prefer reading runnable files under `./examples/*.tsx` and matching `playground/snippets/tag/*.tsx` for prop combinations; this page keeps the contract (rules + API tables) authoritative.
+
+## Rules
+
+- Omit **`size`** to follow the nearest ancestor **`ControlSizeProvider`**; context **`xs`** maps to tag size **`s`**. With no provider and no **`size`**, the effective size is **`m`**.
+- **`onRemove`** is optional; when present, a **`type="button"`** remove control is rendered with **`aria-label="Remove"`** and **`aria-hidden`** on the cross SVG. **`disabled`** sets **`aria-disabled`** on the root and disables the remove button.
+- Without **`onRemove`**, there is no focusable control inside the tag; the root is not a button or link.
+- For lists of removable tags, name the group so “Remove” has context — e.g. **`fieldset`** + **`legend`** (as in `./examples`) or **`aria-label`** / **`aria-labelledby`** on a suitable wrapper.
+- **`Tag.Icon`** does not force **`aria-hidden`** on icons; if the icon is decorative, rely on adjacent text or set **`aria-hidden`** on the icon content yourself.
+- There is no **`variant`** prop; appearance follows **`size`** and whether removal is enabled.
+
+## API
+
+### Tag.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` or from `ControlSizeProvider` | No | Visual tier for height, radius, text, and nested icon scale |
+| onRemove | `() => void` | — | No | When set, renders the remove button on the right |
+| disabled | `boolean` | — | No | Disables removal and sets `aria-disabled` on the root |
+| children | `React.ReactNode` | — | No | Text, `Tag.Icon`, or other nodes |
+| className | `string` | — | No | Extra class on the root `span` |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other root attributes (`data-*`, `aria-*`, etc.) |
+
+### Tag.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon or other content |
+| className | `string` | — | No | Extra class on the wrapper |
+
+## Related
+
+- [Badge](../badge/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/tag/examples/01-filter-chips.tsx

@@ -0,0 +1,36 @@
+import { Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FILTER_IDS = ["In stock", "Ships today", "4+ stars", "Under $50"] as const;
+
+/**
+ * Catalog-style active filters: each chip removes itself from the applied set via `onRemove`.
+ */
+export default function TagExampleFilterChips() {
+  const [applied, setApplied] = React.useState<Set<string>>(
+    () => new Set(["In stock", "4+ stars"]),
+  );
+
+  const remove = (id: string) => {
+    setApplied((prev) => {
+      const next = new Set(prev);
+      next.delete(id);
+      return next;
+    });
+  };
+
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Active filters</legend>
+      <div className={styles.chipRow}>
+        {FILTER_IDS.filter((id) => applied.has(id)).map((id) => (
+          <Tag.Root key={id} onRemove={() => remove(id)}>
+            {id}
+          </Tag.Root>
+        ))}
+      </div>
+    </fieldset>
+  );
+}

package/src/components/tag/examples/02-removable-selected-values.tsx

@@ -0,0 +1,33 @@
+import { Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Selected values (skills, recipients): removable chips in a named group so the fixed
+ * remove control `aria-label` has context from the page.
+ */
+export default function TagExampleRemovableSelectedValues() {
+  const [skills, setSkills] = React.useState<string[]>([
+    "Design systems",
+    "React",
+    "Accessibility",
+  ]);
+
+  const removeSkill = (label: string) => {
+    setSkills((prev) => prev.filter((s) => s !== label));
+  };
+
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Required skills</legend>
+      <div className={styles.chipRow}>
+        {skills.map((label) => (
+          <Tag.Root key={label} onRemove={() => removeSkill(label)}>
+            {label}
+          </Tag.Root>
+        ))}
+      </div>
+    </fieldset>
+  );
+}

package/src/components/tag/examples/03-status-metadata.tsx

@@ -0,0 +1,24 @@
+import { Icon, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Read-only metadata and status: no `onRemove`, optional leading icon via `Tag.Icon`.
+ */
+export default function TagExampleStatusMetadata() {
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Release</legend>
+      <div className={styles.chipRow}>
+        <Tag.Root>
+          <Tag.Icon>
+            <Icon name="status.locked" aria-hidden />
+          </Tag.Icon>
+          <span>Production</span>
+        </Tag.Root>
+        <Tag.Root>v2.4.1</Tag.Root>
+        <Tag.Root>Stable</Tag.Root>
+      </div>
+    </fieldset>
+  );
+}

package/src/components/tag/examples/basic.tsx

@@ -0,0 +1,14 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Static labels without icon or `onRemove` — typical tech stack or category chips. */
+export default function TagExampleBasic() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>React</Tag.Root>
+      <Tag.Root>TypeScript</Tag.Root>
+      <Tag.Root>prime-ui-kit</Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/composition.tsx

@@ -0,0 +1,19 @@
+import { Icon, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Leading `Tag.Icon`, label-only, and label with `onRemove`; icon scale follows `size` via context. */
+export default function TagExampleComposition() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>
+        <Tag.Icon>
+          <Icon name="field.email" />
+        </Tag.Icon>
+        <span>Newsletter</span>
+      </Tag.Root>
+      <Tag.Root>Label only</Tag.Root>
+      <Tag.Root onRemove={() => undefined}>Removable</Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/context-size.tsx

@@ -0,0 +1,17 @@
+import { ControlSizeProvider, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Omit `size` on `Tag.Root` to inherit from `ControlSizeProvider`. */
+export default function TagExampleContextSize() {
+  return (
+    <div className={styles.chipRow}>
+      <ControlSizeProvider value="s">
+        <Tag.Root>No size — from context s</Tag.Root>
+      </ControlSizeProvider>
+      <ControlSizeProvider value="l">
+        <Tag.Root>No size — from context l</Tag.Root>
+      </ControlSizeProvider>
+    </div>
+  );
+}

package/src/components/tag/examples/controlled.tsx

@@ -0,0 +1,26 @@
+import { Button, Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const INITIAL = ["Photo", "Video", "Documents"] as const;
+
+/** Removable tags driven by array state; empty state shows a reset button. */
+export default function TagExampleControlled() {
+  const [active, setActive] = React.useState<string[]>([...INITIAL]);
+
+  return (
+    <div className={styles.chipRow}>
+      {active.map((label) => (
+        <Tag.Root key={label} onRemove={() => setActive((prev) => prev.filter((x) => x !== label))}>
+          {label}
+        </Tag.Root>
+      ))}
+      {active.length === 0 ? (
+        <Button.Root variant="neutral" mode="stroke" onClick={() => setActive([...INITIAL])}>
+          Reset filters
+        </Button.Root>
+      ) : null}
+    </div>
+  );
+}

package/src/components/tag/examples/disabled.tsx

@@ -0,0 +1,15 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** `disabled` alone and with `onRemove` (remove control is not actionable). */
+export default function TagExampleDisabled() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root disabled>Read-only</Tag.Root>
+      <Tag.Root disabled onRemove={() => undefined}>
+        Cannot remove
+      </Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/examples.module.css

@@ -0,0 +1,20 @@
+.fieldsetPlain {
+  margin: 0;
+  padding: 0;
+  border: none;
+  min-width: 0;
+}
+
+.legend {
+  margin: 0 0 var(--prime-sys-spacing-s);
+  padding: 0;
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.chipRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-s);
+  align-items: center;
+}

package/src/components/tag/examples/removable.tsx

@@ -0,0 +1,22 @@
+import { Button, Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** One tag dismisses from state; a stroke button restores it; second row shows static remove UI. */
+export default function TagExampleRemovable() {
+  const [withRemove, setWithRemove] = React.useState(true);
+
+  return (
+    <div className={styles.chipRow}>
+      {withRemove ? (
+        <Tag.Root onRemove={() => setWithRemove(false)}>Dismiss me</Tag.Root>
+      ) : (
+        <Button.Root variant="neutral" mode="stroke" onClick={() => setWithRemove(true)}>
+          Show tag again
+        </Button.Root>
+      )}
+      <Tag.Root onRemove={() => undefined}>Static remove UI</Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/sizes.tsx

@@ -0,0 +1,15 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Size ladder `s` → `xl`; height, radius, type, and icon tier follow control tokens. */
+export default function TagExampleSizes() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root size="s">Tag s</Tag.Root>
+      <Tag.Root size="m">Tag m</Tag.Root>
+      <Tag.Root size="l">Tag l</Tag.Root>
+      <Tag.Root size="xl">Tag xl</Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/states.tsx

@@ -0,0 +1,17 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Default, removable (`onRemove`), `disabled`, and disabled with remove (inactive close control). */
+export default function TagExampleStates() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>Default</Tag.Root>
+      <Tag.Root onRemove={() => undefined}>With remove</Tag.Root>
+      <Tag.Root disabled>Disabled</Tag.Root>
+      <Tag.Root disabled onRemove={() => undefined}>
+        Disabled, remove inactive
+      </Tag.Root>
+    </div>
+  );
+}

package/src/components/tag/examples/with-icon.tsx

@@ -0,0 +1,23 @@
+import { Icon, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Two tags with leading icons and text. */
+export default function TagExampleWithIcon() {
+  return (
+    <div className={styles.chipRow}>
+      <Tag.Root>
+        <Tag.Icon>
+          <Icon name="status.locked" />
+        </Tag.Icon>
+        <span>Secured</span>
+      </Tag.Root>
+      <Tag.Root>
+        <Tag.Icon>
+          <Icon name="field.email" />
+        </Tag.Icon>
+        <span>Newsletter</span>
+      </Tag.Root>
+    </div>
+  );
+}

package/src/components/textarea/COMPONENT.md

@@ -0,0 +1,132 @@
+# Textarea
+
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+
+## Canonical
+
+- **Purpose:** multiline text with optional in-control **character counter**, and optional **hint** or **error** below, wired through **`aria-describedby`** on the native **`textarea`**.
+- **Skeleton vs Input:** unlike [Input](../input/COMPONENT.md) (`Root` → `Wrapper` → **`Field`**), **Textarea** uses a single **`Textarea.Root`**: an outer **`.field`** stack wraps a bordered **`label`** (the field chrome) that owns the native **`<textarea>`**—there is **no** separate `Textarea.Field` export; pass standard textarea attributes on **`Root`**.
+- **Children:** **`Textarea.CharCounter`** only as a **direct** child of **`Root`** (footer inside the chrome). **`Textarea.Hint`** / **`Textarea.Error`** as direct children **after** that chrome (siblings of the inner `label`, not wrapped around `CharCounter`).
+- **Size:** `size` ∈ `s | m | l | xl` only on **`Textarea.Root`**; the HTML **`size`** attribute is omitted from the public typing (reserved).
+- **Scenario grid:** see [**Scenarios (playground + `examples/`)**](#scenarios-playground--examples) below — order matches **`playground/sections/TextareaSection.tsx`** and **`playground/snippets/textarea/*.tsx`**.
+
+```tsx
+import { Textarea } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Textarea.Root placeholder="Notes" name="notes">
+      <Textarea.Hint>Optional hint below the field.</Textarea.Hint>
+    </Textarea.Root>
+  );
+}
+```
+
+## Extended
+
+### About
+
+A composite multiline field: native `textarea` inside bordered field chrome, optional footer for a character counter, and optional hint or error lines below wired through `aria-describedby`.
+
+**When to use**
+
+- Long or growing text in forms, feedback, notes, descriptions, and comments where a single line is not enough.
+- Flows that need a built-in counter, hint, or error message aligned with the same sizing scale as other controls.
+- Layouts where auto-growing height (`autoResize`) should track content without manual `rows` tuning.
+
+**When not to use**
+
+- Single-line values — use [Input](../input/COMPONENT.md).
+- Rich text or embedded formatting — use a dedicated editor component.
+- When the visible label must sit only above the chrome — pair [Label](../label/COMPONENT.md) with a stable **`id`** on **`Textarea.Root`** (see [`./examples/02-comment.tsx`](./examples/02-comment.tsx)); do not nest a second `label` around the control.
+
+### Composition
+
+- **`Textarea.Root`** — outer `div` (`.field`) with `data-size`, `TextareaProvider`, and `ControlSizeProvider`. The native `textarea` sits inside a `label` (`htmlFor` → input id) with bordered `.control` styling; when `autoResize` is true, the textarea is wrapped so `data-value` can drive height.
+- **`Textarea.CharCounter`** — must be a **direct** child of `Root`; implementation partitions children by reference equality to `Textarea.CharCounter` and renders matching nodes in the control footer.
+- **`Textarea.Hint`** / **`Textarea.Error`** — direct children of `Root`, **not** passed as `CharCounter`; they render after the `label` and register ids merged into the textarea’s `aria-describedby`.
+
+### Scenarios (playground + `examples/`)
+
+Live demos use **`playground/snippets/textarea/*.tsx`** (see **`playground/sections/TextareaSection.tsx`**). The table lists the same scenarios with package-oriented copies under **`examples/`** (aligned with those snippets; order matches the playground section).
+
+| Scenario | What it shows | `examples/` |
+|----------|---------------|-------------|
+| Sizes | Four **`size`** values (`s`–`xl`), each field with a **`Textarea.Hint`** naming the tier. | [`examples/sizes.tsx`](examples/sizes.tsx) |
+| Variants | **`variant="default"`** vs **`variant="error"`** with **`Textarea.Error`** (`aria-describedby`, invalid styling). | [`examples/variants.tsx`](examples/variants.tsx) |
+| States | Hint, **`disabled`**, **`readOnly`**, and native **`required`** on the textarea. | [`examples/states.tsx`](examples/states.tsx) |
+| Controlled | Parent **`value`** / **`onChange`**; live length in **`Textarea.Hint`**. | [`examples/controlled.tsx`](examples/controlled.tsx) |
+| Composition | **`Typography`** section title, counter + hint, second root with **`Textarea.Error`**. | [`examples/composition.tsx`](examples/composition.tsx) |
+| Full width | Narrow card-style parent; root spans the track (**`width: 100%`**, **`min-width: 0`** on `.field`). | [`examples/full-width.tsx`](examples/full-width.tsx) |
+| Features | Default **`autoResize`**, **`autoResize={false}`**, **`CharCounter`**, **`data-overflow`**, **`maxLength`** + counter. | [`examples/features.tsx`](examples/features.tsx) |
+
+### Additional narrative examples
+
+- [`./examples/01-support-ticket.tsx`](./examples/01-support-ticket.tsx) — Support form: long description with counter, hint, and **`maxLength`** cap.
+- [`./examples/02-comment.tsx`](./examples/02-comment.tsx) — Order comment: **Label** + **`Textarea.Root`** with shared **`id`**, counter, and logistics hint.
+
+**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and composition patterns; this page keeps the contract (rules + API tables) authoritative.
+
+### Rules
+
+- **Controlled vs uncontrolled:** pass **`value`** with **`onChange`** / **`onInput`** as needed for controlled text; omit **`value`** and optionally set **`defaultValue`** for uncontrolled usage.
+- **`autoResize`** defaults to **`true`**: input events update a wrapper `data-value` mirror; set **`autoResize={false}`** to rely on fixed height / native resize behavior.
+- **`variant="error"`** or mounting **`Textarea.Error`** sets invalid styling; **`aria-invalid`** defaults from that unless overridden.
+- **`aria-describedby`** you pass is **merged** with auto-added hint and error ids (your ids first, then hint and error when those parts mount).
+- **`disabled`** / **`readOnly`** on `Root` flow to the native textarea; **`Textarea.Hint`** switches to a disabled visual variant when either is true.
+- Do not pass **`size`** as a DOM attribute on the textarea — it is omitted from the element API and reserved for **`Textarea.Root`** (`"s"` \| `"m"` \| `"l"` \| `"xl"`).
+- **`Textarea.CharCounter`** is only recognized as an immediate child of **`Root`**; arbitrary wrappers around it will not land in the footer.
+- Counter overflow (**`current` > `max`**) sets **`data-overflow="true"`** on the counter for styling; it does not block typing by itself (pair with **`maxLength`** if you need a hard cap).
+- The counter uses **`aria-live="polite"`** so count updates do not interrupt typing.
+- **Full width:** the `.field` root uses **`width: 100%`** and **`min-width: 0`** (same idea as Input). Place **`Textarea.Root`** inside a parent that spans the desired column or card width.
+- There is no **`asChild`** or polymorphic root — structure is fixed.
+
+### API
+
+#### Textarea.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `"default" \| "error"` | `"default"` | no | Visual invalid emphasis; combines with `aria-invalid` and `Textarea.Error` registration. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Control scale (padding, type, min height). |
+| autoResize | `boolean` | `true` | no | When true, height follows content via wrapper `data-value`; when false, no auto-grow wrapper. |
+| id | `string` | `useId()` | no | Stable id for the textarea; outer `label` uses `htmlFor` pointing here. |
+| className | `string` | — | no | Extra class on the visible field shell: bordered **`label`** (`.control`) with state **`data-*`** attributes. |
+| disabled | `boolean` | — | no | Native disabled state. |
+| readOnly | `boolean` | — | no | Native read-only state. |
+| value | `string` | — | no | Controlled value. |
+| defaultValue | `string` | — | no | Uncontrolled initial value. |
+| onInput | `React.FormEventHandler<HTMLTextAreaElement>` | — | no | Fires after internal `data-value` sync when `autoResize` is on. |
+| aria-describedby | `string` | — | no | Merged with hint/error ids when those parts mount. |
+| aria-invalid | `Booleanish` | from variant / error | no | Explicit invalidity over heuristics. |
+| children | `React.ReactNode` | — | no | `CharCounter` in the footer; `Hint` / `Error` after the `label`. |
+| …rest | `Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size">` | — | no | Standard textarea attributes (`placeholder`, `rows`, `maxLength`, `required`, `onChange`, `onInput`, `name`, `autoComplete`, etc.). |
+
+#### Textarea.CharCounter
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| current | `number` | — | yes | Current character count. |
+| max | `number` | — | yes | Displayed limit; overflow when `current > max` sets `data-overflow="true"`. |
+
+#### Textarea.Hint
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Hint copy. |
+| className | `string` | — | no | Extra class on the underlying `Hint.Root`. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` comes from context. |
+
+#### Textarea.Error
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Error copy. |
+| className | `string` | — | no | Extra class on the underlying `Hint.Root`. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` comes from context. |
+
+## Related
+
+- [Input](../input/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)

package/src/components/textarea/examples/01-support-ticket.tsx

@@ -0,0 +1,34 @@
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const MAX = 2000;
+
+/**
+ * Support ticket: long description with counter, hint, and a hard cap via maxLength.
+ */
+export default function TextareaExampleSupportTicket() {
+  const [text, setText] = React.useState("");
+
+  return (
+    <div className={styles.stack}>
+      <Textarea.Root
+        id="support-description"
+        name="description"
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        maxLength={MAX}
+        placeholder="Describe what happened, steps to reproduce, and what you expected instead."
+        rows={4}
+        required
+        aria-label="Support ticket description"
+      >
+        <Textarea.CharCounter current={text.length} max={MAX} />
+        <Textarea.Hint>
+          We typically reply within one business day. Avoid sharing passwords or full card numbers.
+        </Textarea.Hint>
+      </Textarea.Root>
+    </div>
+  );
+}