@d4gger/design-system 2.7.0

package/dist/docs/rich-text-editor.md

@@ -0,0 +1,300 @@
+---
+title: RichTextEditor
+status: canonical
+category: Components
+archetype: adapter-backed
+package_path: packages/d4gger-design-system/src/components/richTextEditor/RichTextEditor.tsx
+css_path: packages/d4gger-design-system/src/styles/components/rich-text-editor.css
+props_path: packages/d4gger-design-system/src/components/richTextEditor/richTextEditor.props.ts
+test_path: packages/d4gger-design-system/src/test/components/RichTextEditor.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/forms.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - "@tiptap/react"
+  - "@tiptap/starter-kit"
+  - Button
+  - Icon
+---
+
+# RichTextEditor
+
+## 2.6 article preset
+
+`preset="basic" | "article"` retains `basic` as the default. `extensions` remains a full replacement. `createRichTextEditorExtensions({ preset, extensions })` is the supported composition helper for app-owned editor instances. The article preset uses the official Image and Table extensions, CodeBlockLowlight with package-selected Lowlight common languages, plus stable embed, callout, comparison, and poll nodes.
+
+Import the editor and its composition helper from `@d4gger/design-system/rich-text-editor`. Direct article extension exports live at `@d4gger/design-system/article-extensions`; neither Tiptap surface is re-exported by the root or `components` barrels, preserving the optional-peer boundary.
+
+Stable attributes are: image `src`, `alt`, optional `caption`; embed canonical `url`; callout `tone`, optional `title`, nested content; code language/content; comparison before/after sources, alt text, optional labels; poll persistent ID and display metadata. Embed HTML never accepts raw iframes. Applications own URL allowlists/oEmbed callbacks, uploads, polling/voting, authentication, storage, and sanitization. Matching read-side exports are `ArticleImage`, `ArticleEmbed`, `BeforeAfterComparison`, and `ArticlePoll`.
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A productized Tiptap editor shell with a formatting toolbar, a content area, and a status bar. The package owns the shell, the toolbar layout, the token bindings, and the class wiring. The adapter (`@tiptap/react` + `@tiptap/starter-kit`) owns the editor engine, the schema, and the content model. Apps own schema customization, extension policy, serialization format, and persistence.
+
+`RichTextEditor.Root` (aliased as `RichTextEditor`) is the convenience default that creates a managed Tiptap editor instance. `RichTextEditor.Shell` is the canon-aligned surface for apps that own the editor instance.
+
+## Anatomy & slots
+
+**Parent:** `RichTextEditor` (alias of `RichTextEditor.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `RichTextEditor.Root` (alias `RichTextEditor`) | `<div>` | DS shell, `dsx-rich-text-editor` | Convenience wrapper. Creates a managed Tiptap editor via `useEditor` and delegates to `RichTextEditor.Shell`. |
+| `RichTextEditor.Shell` | `<div>` | `dsx-rich-text-editor` | Canon-aligned surface. Accepts an app-supplied `editor` instance. Renders the toolbar, content area, and status bar. |
+| `RichTextEditor.Toolbar` | `<div>` | `dsx-rich-text-editor__toolbar` | Formatting toolbar with `role="toolbar"` and `aria-label="Formatting toolbar"`. Contains grouped toolbar buttons. |
+| `RichTextEditor.ToolbarButton` | `<button>` (via `Button`) | `dsx-rich-text-editor__toolbar-button` | Individual toolbar action. Wraps `Button` with `variant="ghost"` and `size="sm"`. |
+| `RichTextEditor.Content` | `<div>` | `dsx-rich-text-editor__area` | Content area wrapper. Renders the placeholder (when empty) and the `EditorContent` adapter host. |
+
+**Adapter host:**
+
+The `EditorContent` component from `@tiptap/react` renders inside `RichTextEditor.Content`. The ProseMirror element receives the `dsx-rich-text-editor__prosemirror` class and `data-slot="rich-text-editor-prosemirror"`.
+
+**Internal regions:**
+
+| Region | Element | Class | Notes |
+|---|---|---|---|
+| Toolbar group | `<div>` | `dsx-rich-text-editor__toolbar-group` | Groups related toolbar buttons. `role="group"` with `aria-label`. |
+| Toolbar label | `<span>` | `dsx-rich-text-editor__toolbar-label` | Group label ("Text", "Blocks", "Insert", "History"). |
+| Status bar | `<div>` | `dsx-rich-text-editor__status` | Shows editor status ("Editor loading", "Ready to write", or character count). `data-slot="rich-text-editor-status"`. |
+| Placeholder | `<div>` | `dsx-rich-text-editor__placeholder` | Shown when the editor is empty and a placeholder is provided. `data-slot="rich-text-editor-placeholder"`. |
+| Content host | `EditorContent` | `dsx-rich-text-editor__content` | The Tiptap adapter host. `data-slot="rich-text-editor-content"`. |
+
+## Props contract
+
+### `RichTextEditor.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Extracted from prop defs but not used by the root. The root always renders as a `<div>`. | no |
+| `disabled` | `boolean` | `false` | no | Makes the editor non-editable. Drives `data-disabled` and `aria-disabled` on the shell. The CSS file consumes `data-disabled='true'` to change the shell border, background, and text color. | no |
+| `content` | `unknown` | `''` | no | Initial or controlled editor content. Accepts `string` (HTML), `object` (JSON), or `null`. Validated by `isRichTextEditorContent`. | no |
+| `editorOptions` | `Omit<UseEditorOptions, 'content' \| 'editable' \| 'extensions' \| 'onUpdate'>` | `undefined` | no | Escape hatch for `useEditor` options. Merged with the DS-managed options. | no |
+| `extensions` | `UseEditorOptions['extensions']` | `[StarterKit]` | no | Tiptap extensions. Defaults to `StarterKit`. Apps that need custom schema or extensions pass their own array. | no |
+| `onEditorUpdate` | `(editor: Editor) => void` | `undefined` | no | Fires on every editor update with the raw `Editor` instance. App-owned escape hatch. | no |
+| `onUpdate` | `(content: string) => void` | `undefined` | no | Fires on every editor update with the serialized content string. Defaults to HTML serialization unless `serialize` is provided. | no |
+| `placeholder` | `string` | `undefined` | no | Placeholder text shown when the editor is empty. | no |
+| `serialize` | `(editor: Editor) => string` | `undefined` | no | Custom serialization function. When provided, `onUpdate` receives the output of this function instead of `editor.getHTML()`. | no |
+| `toolbar` | `RichTextEditorToolbarSlot \| null` | `undefined` | no | Controls the toolbar rendering. `undefined` renders the default `RichTextEditor.Toolbar`. A ReactNode renders that node instead. A function receives `{ disabled, editor }` and returns a ReactNode. `null` hides the toolbar. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-rich-text-editor`. | no |
+
+### `RichTextEditor.Shell` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Extracted from prop defs but not used. The shell always renders as a `<div>`. | no |
+| `disabled` | `boolean` | `false` | no | Drives `data-disabled` and `aria-disabled` on the shell. | no |
+| `editor` | `Editor \| null` | (required) | yes | The Tiptap editor instance. Apps that use `Shell` own the editor lifecycle. | no |
+| `placeholder` | `string` | `undefined` | no | Placeholder text. | no |
+| `toolbar` | `RichTextEditorToolbarSlot \| null` | `undefined` | no | Toolbar override. Same semantics as `Root`. | no |
+| `className` | `string` | `undefined` | no | Extra classes. | no |
+
+### `RichTextEditor.Toolbar` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `editor` | `Editor \| null` | (required) | yes | The Tiptap editor instance. | no |
+| `disabled` | `boolean` | `false` | no | Disables all toolbar buttons. | no |
+| `className` | `string` | `undefined` | no | Extra classes. | no |
+
+### `RichTextEditor.Content` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Extracted from prop defs but not used. The content area always renders as a `<div>`. | no |
+| `disabled` | `boolean` | `false` | no | Drives `data-disabled` on the content area. | no |
+| `mode` | `'toolbar' \| 'content'` | `'content'` | no | Extracted from prop defs but not consumed by the runtime. Reserved for future usage. | no |
+| `editor` | `Editor \| null` | (required) | yes | The Tiptap editor instance. | no |
+| `placeholder` | `string` | `undefined` | no | Placeholder text. | no |
+| `className` | `string` | `undefined` | no | Extra classes. | no |
+
+### `RichTextEditor.ToolbarButton` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the button through `Slot` from `@radix-ui/react-slot` via `Button`. | no |
+| `active` | `boolean` | `false` | no | Drives `data-active` and `aria-pressed` on the button. The CSS file consumes `data-active='true'` to change the button background and text color. | no |
+| `className` | `string` | `undefined` | no | Extra classes. | no |
+
+All other `React.ButtonHTMLAttributes<HTMLButtonElement>` are forwarded to `RichTextEditor.ToolbarButton`.
+
+## CSS class contract
+
+**Root class:** `dsx-rich-text-editor`
+
+**Modifier classes** (driven by `data-*` attributes and prop def `className` values):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-disabled` | `true` | `.dsx-rich-text-editor[data-disabled='true']` | `rich-text-editor.css` |
+| `data-active` | `true` | `.dsx-rich-text-editor__toolbar-button[data-active='true']` | `rich-text-editor.css` |
+| (prop def className) | (boolean) | `dsx-rich-text-editor-disabled`, `dsx-rich-text-editor-content-disabled`, `dsx-rich-text-editor-toolbar-button-active` | `rich-text-editor.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| Root / Shell | `dsx-rich-text-editor` | `rich-text-editor.css` |
+| Toolbar | `dsx-rich-text-editor__toolbar` | `rich-text-editor.css` |
+| Toolbar group | `dsx-rich-text-editor__toolbar-group` | `rich-text-editor.css` |
+| Toolbar label | `dsx-rich-text-editor__toolbar-label` | `rich-text-editor.css` |
+| Toolbar button | `dsx-rich-text-editor__toolbar-button` | `rich-text-editor.css` |
+| Content area | `dsx-rich-text-editor__area` | `rich-text-editor.css` |
+| Placeholder | `dsx-rich-text-editor__placeholder` | `rich-text-editor.css` |
+| Content host | `dsx-rich-text-editor__content` | `rich-text-editor.css` |
+| ProseMirror | `dsx-rich-text-editor__prosemirror` | `rich-text-editor.css` |
+| Status bar | `dsx-rich-text-editor__status` | `rich-text-editor.css` |
+
+**Data slots** (used by QA and audit tooling, not visual):
+
+| Element | `data-slot` |
+|---|---|
+| Root / Shell | `rich-text-editor` |
+| Toolbar | `rich-text-editor-toolbar` |
+| Toolbar button | `rich-text-editor-toolbar-button` |
+| Content area | `rich-text-editor-area` |
+| Placeholder | `rich-text-editor-placeholder` |
+| Content host | `rich-text-editor-content` |
+| ProseMirror | `rich-text-editor-prosemirror` |
+| Status bar | `rich-text-editor-status` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The shell and toolbar transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The CSS file does not include a `prefers-reduced-motion` gate; the global stylesheet is expected to honor the media query.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Shell radius | `var(--dsx-rounded-lg)` | Corner roundness. |
+| Shell border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Edge. |
+| Shell background | `var(--dsx-color-surface-raised)` | Resting surface. |
+| Shell text | `var(--dsx-color-on-surface)` | Primary labels. |
+| Shell shadow | `var(--dsx-shadow-elevation-2)` | Elevation. |
+| Shell hover border | `var(--dsx-color-outline-variant)` | Hover edge. |
+| Shell focus border | `var(--dsx-color-primary)` | Focus edge. |
+| Shell focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator. |
+| Shell disabled | `var(--dsx-color-disabled-border)`, `var(--dsx-color-disabled-surface)`, `var(--dsx-color-disabled-text)` | Disabled state. |
+| Toolbar gap | `var(--dsx-space-xs)` | Button spacing. |
+| Toolbar padding | `var(--dsx-space-sm)` / `var(--dsx-space-md)` | Internal gutter. |
+| Toolbar border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Bottom edge. |
+| Toolbar background | `var(--dsx-color-surface-editor-toolbar)` | Toolbar surface. |
+| Toolbar group border | `var(--dsx-border-width-sm)` + `var(--dsx-color-panel-border-translucent)` | Group edge. |
+| Toolbar group radius | `var(--dsx-rounded-md)` | Group corner roundness. |
+| Toolbar group background | `var(--dsx-effect-gray-alpha-3)` | Group surface. |
+| Toolbar label typography | `var(--dsx-typography-label-small-*)` | Group label. |
+| Toolbar button size | `var(--dsx-density-control-height-sm)` | Button tap target. |
+| Toolbar button active | `var(--dsx-color-high-contrast)` + `var(--dsx-color-on-high-contrast)` | Active background and text. |
+| Content area min-height | `var(--dsx-rich-text-editor-min-height, 220px)` | Minimum editor height. |
+| Content area background | Gradient using `var(--dsx-color-surface-raised)` and `var(--dsx-color-surface)` | Subtle gradient. |
+| Placeholder | `var(--dsx-color-on-surface-variant)` | Placeholder text. |
+| ProseMirror typography | `var(--dsx-typography-body-medium-*)` | Body text. |
+| ProseMirror heading | `var(--dsx-typography-headline-medium-*)` | H1/H2. |
+| ProseMirror H3 | `var(--dsx-typography-label-large-*)` | H3. |
+| ProseMirror blockquote | `var(--dsx-color-primary)` (border), `var(--dsx-effect-hover-primary)` (bg) | Blockquote style. |
+| ProseMirror code | `var(--dsx-color-background)` + `var(--dsx-color-primary-container)` | Inline code. |
+| ProseMirror pre | `var(--dsx-color-background)` + `var(--dsx-color-on-background)` | Code block. |
+| Status bar | `var(--dsx-color-surface-editor-subtle)` + `var(--dsx-color-on-surface-variant)` | Status surface and text. |
+| Transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover and focus transitions. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Shell border, background, shadow, color | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on hover, focus, and disabled | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Toolbar background, border | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on state change | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Content area background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Transition on disabled | Relies on the global `prefers-reduced-motion` stylesheet. |
+
+## Accessibility
+
+**Roles:**
+
+- The toolbar has `role="toolbar"` and `aria-label="Formatting toolbar"`.
+- Each toolbar group has `role="group"` with `aria-label` ("Text style", "Block style", "Insert", "History").
+- Each toolbar button has `aria-pressed` for the active state and `aria-label` for the action name.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus through the toolbar buttons and into the editor content. |
+| `Enter`, `Space` | Activates the focused toolbar button. |
+| Arrow keys | The toolbar does not implement arrow-key navigation between buttons. The ProseMirror editor handles its own keyboard shortcuts (Mod-B for bold, Mod-I for italic, etc.). |
+
+**Focus:**
+
+- Visible focus ring via `var(--dsx-shadow-focus-ring)` on the shell (on `:focus-within`) and toolbar buttons.
+
+**Reduced motion:**
+
+- Transitions on the shell, toolbar, and content area are expected to collapse under the global `prefers-reduced-motion` stylesheet.
+
+**Color and meaning:**
+
+- The active toolbar button is communicated by the `--dsx-color-high-contrast` background and `--dsx-color-on-high-contrast` text. `aria-pressed` and `data-active` provide assistive-tech semantics.
+- The disabled state is communicated by the `--dsx-color-disabled-*` tokens and `data-disabled`.
+
+**Naming:**
+
+- Each toolbar button has an `aria-label` ("Bold", "Italic", "Strikethrough", "Heading 1", "Heading", "Subheading", "Bulleted list", "Numbered list", "Quote block", "Code block", "Link", "Clear formatting", "Undo", "Redo").
+- The toolbar is auto-labeled "Formatting toolbar".
+- The toolbar groups are auto-labeled "Text style", "Block style", "Insert", and "History".
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `RichTextEditor` with `content` and `placeholder`. Asserts the root class is `dsx-rich-text-editor` and the toolbar is rendered.
+
+**Variant stories** (one per disabled state):
+
+- Renders with `disabled`. Asserts `data-disabled="true"` on the shell.
+
+**Composition story:**
+
+- Renders `RichTextEditor.Shell` with an app-supplied editor. Asserts the toolbar, content area, and status bar are rendered.
+
+**State story:**
+
+- Renders with `toolbar={null}`. Asserts the toolbar is not rendered.
+- Renders with a custom toolbar ReactNode. Asserts the custom toolbar is rendered instead of the default.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `disabled` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@tiptap/react`: the adapter engine. `useEditor` creates the editor instance. `EditorContent` renders the ProseMirror host.
+- `@tiptap/starter-kit`: the default extension set. Provides bold, italic, strike, headings, lists, blockquote, code block, and history.
+- `Button`: wraps each toolbar button with `variant="ghost"` and `size="sm"`.
+- `Icon`: renders the toolbar button glyphs (bold, italic, strikethrough, heading-1, heading-2, heading-3, list, list-ordered, quote, code, link, eraser, undo, redo).
+
+**Used by:**
+
+- No DS component currently wraps `RichTextEditor`. The pattern is the intended app-side composition.
+
+**State boundaries:**
+
+- Owned by this component: the DS shell class wiring, the toolbar layout, the token bindings, the status bar, the placeholder rendering, and the default `StarterKit` extension set.
+- Owned by the adapter: the editor engine, the content model, the schema, the ProseMirror view, and the keyboard shortcuts.
+- Owned by the consumer: the editor instance (when using `Shell`), the extension set, the serialization format, the content value, the `onUpdate` and `onEditorUpdate` handlers, and the toolbar override.
+
+**Boundary rules:**
+
+- App-owned data: the editor schema, the extension set, the serialization format, the content persistence, the `onUpdate` handler, and the toolbar override.
+- DS-owned visuals: token bindings, the `dsx-rich-text-editor` class hierarchy, the `data-disabled` and `data-active` attributes, the toolbar `aria-label` templates, the status bar text, and the placeholder rendering.

package/dist/docs/scroll-area.md

@@ -0,0 +1,297 @@
+---
+title: ScrollArea
+status: canonical
+category: Components
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/scrollArea/ScrollArea.tsx
+css_path: packages/d4gger-design-system/src/styles/components/scroll-area.css
+props_path: packages/d4gger-design-system/src/components/scrollArea/scrollArea.props.ts
+test_path: packages/d4gger-design-system/src/test/components/ScrollArea.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/layout.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - "@radix-ui/react-scroll-area"
+  - "@radix-ui/react-slot"
+---
+
+# ScrollArea
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A custom-styled scroll viewport backed by `@radix-ui/react-scroll-area`. The package owns the class wiring, the token bindings, and the size and radius attribute contract. The Radix primitive owns the scroll math, the keyboard support, the screen-reader semantics, and the scrollbar visibility logic. Apps own the scrollable content and any policy around overflow behavior.
+
+`ScrollArea` is classified as `radix-compound` in the roster (not `adapter-backed`) because every behavior the user sees comes from the Radix primitive. The compound is the right fit when a design needs a `Root + Viewport + Scrollbar + Corner` anatomy, when the content must escape its parent overflow, or when the public API needs subcomponents attached to the root.
+
+## Anatomy & slots
+
+**Parent:** `ScrollArea` (alias of `ScrollArea.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `ScrollArea.Root` (alias `ScrollArea`) | `<div>` (the `Root` from `@radix-ui/react-scroll-area`) | `dsx-scroll-area` | Hosts the size and radius attributes. Carries `data-size`, `data-radius`, and `data-slot="scroll-area"`. |
+| `ScrollArea.Viewport` | `<div>` (the `Viewport` from Radix) | `dsx-scroll-area__viewport` | The scroll container. Carries `data-slot="scroll-area-viewport"`. The root always renders one; the consumer does not need to render it manually. |
+| `ScrollArea.ScrollBar` | `<div>` (the `ScrollAreaScrollbar` from Radix) | `dsx-scroll-area__scrollbar` | The scrollbar track. Carries `data-slot="scroll-area-scrollbar"`. The root always renders one vertical and one horizontal scrollbar. |
+| `ScrollArea.Corner` | `<div>` (the `Corner` from Radix) | `dsx-scroll-area__corner` | The corner where the two scrollbars meet. Carries `data-slot="scroll-area-corner"`. The root always renders one. |
+
+The `Root` slot mounts the `Viewport`, both `ScrollBar` slots, and the `Corner` slot automatically. Consumers do not need to render the `Viewport`, `ScrollBar`, or `Corner` slots themselves unless they want to attach a `viewportAsChild` host to the viewport.
+
+**Adapter host:**
+
+`Root` wraps the `Root` from `@radix-ui/react-scroll-area`. `Viewport` is the Radix `Viewport`. `ScrollBar` is the Radix `ScrollAreaScrollbar`; the root always renders one vertical and one horizontal scrollbar. The `ScrollAreaThumb` is rendered automatically inside the scrollbar and receives `dsx-scroll-area__thumb` plus `data-slot="scroll-area-thumb"`. The `Corner` is the Radix `Corner` element. `data-state` attributes from Radix (`data-state="visible"`, `data-state="hidden"`, `data-state="hover"`) are mirrored on the scrollbar slot.
+
+## Props contract
+
+### `ScrollArea.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Extracted from prop defs but the `Root` host always renders a `<div>`. The prop is reserved for future use. | no |
+| `viewportAsChild` | `boolean` | `false` | no | When `true`, the children passed to the root are rendered directly inside the viewport via `Slot`. When `false`, the children are wrapped in a fragment. Use `true` when the scrollable content needs to be the viewport child directly so the host element's own classes do not block overflow inheritance. | no |
+| `size` | `'1' \| '2' \| '3'` | `'1'` | no | Drives `data-size` on the root. Reserved for token-driven scrollbar width variants; the default CSS does not consume the value beyond writing the attribute. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | no | Drives `data-radius` on the root. The CSS file consumes `data-radius` on `.dsx-scroll-area` to control the corner roundness inherited by the viewport. | no |
+| `viewportClassName` | `string` | `undefined` | no | Extra classes appended to the `Viewport` slot. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-scroll-area`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Scrollable content. Rendered inside the viewport. | no |
+
+The root also accepts the full `ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>` from `@radix-ui/react-scroll-area`. `type`, `dir`, `scrollHideDelay`, and the standard HTML attributes are forwarded verbatim.
+
+### `ScrollArea.Viewport` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Forwards `asChild` to the Radix `Viewport` so the viewport can render as a custom element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-scroll-area__viewport`. | no |
+
+The slot also accepts the full `ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Viewport>` and forwards `nonce` and the Radix `Viewport` props verbatim.
+
+### `ScrollArea.ScrollBar` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Extracted from prop defs but the `Scrollbar` host always renders a `<div>`. The prop is reserved for future use. | no |
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | no | Drives `data-orientation` on the scrollbar. The root always renders one of each; this prop is forwarded to the Radix `ScrollAreaScrollbar` for direct composition. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-scroll-area__scrollbar`. | no |
+
+The slot also accepts the full `ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>` and forwards `forceMount` and the Radix `ScrollAreaScrollbar` props verbatim.
+
+### `ScrollArea.Corner` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Extracted from prop defs but the `Corner` host always renders a `<div>`. The prop is reserved for future use. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-scroll-area__corner`. | no |
+
+The slot also accepts the full `ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Corner>` and forwards the Radix `Corner` props verbatim.
+
+## CSS class contract
+
+**Root class:** `dsx-scroll-area`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `1`, `2`, `3` | `.dsx-scroll-area[data-size='1']`, `.dsx-scroll-area[data-size='2']`, `.dsx-scroll-area[data-size='3']` | `scroll-area.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | `.dsx-scroll-area[data-radius='…']` | `scroll-area.css` |
+| `data-state` (Radix) | `visible`, `hidden`, `hover`, `scroll` | `.dsx-scroll-area__scrollbar[data-state='visible']` | `scroll-area.css` |
+| `data-orientation` (Radix) | `vertical`, `horizontal` | `.dsx-scroll-area__scrollbar[data-orientation='vertical']`, `.dsx-scroll-area__scrollbar[data-orientation='horizontal']` | `scroll-area.css` |
+
+The `data-size` and `data-radius` attributes are not consumed by the default CSS; they are forward-looking hooks for token-driven size and radius variants.
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| Root | `dsx-scroll-area` | `scroll-area.css` |
+| Viewport | `dsx-scroll-area__viewport` | `scroll-area.css` |
+| Scrollbar | `dsx-scroll-area__scrollbar` | `scroll-area.css` |
+| Thumb | `dsx-scroll-area__thumb` | `scroll-area.css` |
+| Corner | `dsx-scroll-area__corner` | `scroll-area.css` |
+
+**Data slots** (used by QA and audit tooling, not visual):
+
+| Element | `data-slot` |
+|---|---|
+| Root | `scroll-area` |
+| Viewport | `scroll-area-viewport` |
+| Scrollbar | `scroll-area-scrollbar` |
+| Thumb | `scroll-area-thumb` |
+| Corner | `scroll-area-corner` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The scrollbar background and thumb transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The CSS file does not include a `prefers-reduced-motion` gate; the global stylesheet is expected to honor the media query. The scroll motion itself is owned by the Radix primitive and respects the user's reduced-motion preference.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root border box | `border-box` | Predictable sizing. |
+| Root position | `relative` | Position context for the scrollbar and corner. |
+| Root overflow | `hidden` | Clamp scroll content to the root bounds. |
+| Viewport border radius | `inherit` | Inherit the root's `data-radius`. |
+| Scrollbar padding | `var(--dsx-space-0-5)` | Inner scrollbar padding. |
+| Scrollbar width (vertical) | `var(--dsx-size-scroll-thumb-size)` | Vertical scrollbar thickness. |
+| Scrollbar height (horizontal) | `var(--dsx-size-scroll-thumb-size)` | Horizontal scrollbar thickness. |
+| Scrollbar visible background | `var(--dsx-color-surface-sunken)` | Track background when visible. |
+| Scrollbar border radius | `var(--dsx-rounded-full)` | Track roundness. |
+| Thumb background | `var(--dsx-color-gray-8)` | Thumb color at rest. |
+| Thumb hover background | `var(--dsx-color-gray-10)` | Thumb color on hover. |
+| Thumb border radius | `var(--dsx-rounded-full)` | Thumb roundness. |
+| Thumb rest opacity | `0.7` | Resting opacity. |
+| Thumb hover opacity | `0.9` | Hover opacity. |
+| Corner background | `transparent` | Corner. |
+| Transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Scrollbar background and thumb transitions. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Scrollbar background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Background transition on visibility change. | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Thumb background and opacity | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Thumb color and opacity transition. | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Scroll motion | owned by Radix | The scroll motion is the user's pointer or keyboard input; the package does not add its own scroll animation. | Honored by the browser and the Radix primitive. |
+
+## Accessibility
+
+**Roles:**
+
+- The viewport and the scrollbar inherit the `role="region"` and `role="scrollbar"` semantics from `@radix-ui/react-scroll-area`. `aria-orientation` and `aria-valuenow` reflect the current scroll position and orientation.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to and from scrollable content. The scrollbar itself is not focusable by default. |
+| Arrow keys | The viewport is keyboard-scrollable when it contains focus. The browser and the Radix primitive handle arrow-key scrolling. |
+| `Page Up`, `Page Down` | Scrolls the viewport by one page. |
+| `Home`, `End` | Scrolls to the start or end of the content. |
+
+**Focus:**
+
+- Focus on the scrollable content uses the host application's focus styles. The DS does not add a custom focus ring; apps that need a custom ring can target `.dsx-scroll-area__viewport:focus-visible` from the host.
+
+**Reduced motion:**
+
+- The scrollbar transitions collapse under the global `prefers-reduced-motion` stylesheet. The scroll motion is owned by the browser and respects the user's reduced-motion preference.
+
+**Color and meaning:**
+
+- The scrollbar uses semantic tokens (`var(--dsx-color-surface-sunken)`, `var(--dsx-color-gray-8)`, `var(--dsx-color-gray-10)`) so light and dark themes are covered. The thumb is the only color communicator; the track is a sunken surface.
+
+**Naming:**
+
+- The component does not require an accessible name by default. Apps that want a richer label for the scroll region can pass `aria-label` or `aria-labelledby` to the root.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `ScrollArea` with a tall child. Asserts the root has `dsx-scroll-area`, `data-size="1"`, `data-radius="md"`, and `data-slot="scroll-area"`, and the viewport has `dsx-scroll-area__viewport` and `data-slot="scroll-area-viewport"`.
+
+**Variant stories** (one per radius and one per size):
+
+- Renders with `radius="full"`, `radius="lg"`, `radius="md"`, `radius="sm"`, and `radius="none"`. Asserts `data-radius` matches on the root.
+- Renders with `size="1"`, `size="2"`, and `size="3"`. Asserts `data-size` matches on the root.
+
+**Composition story:**
+
+- Renders `ScrollArea.Viewport`, `ScrollArea.ScrollBar`, and `ScrollArea.Corner` directly (the root still auto-mounts them, so this story asserts the named slots are reachable). Asserts each slot carries its own `data-slot` attribute.
+
+**State story:**
+
+- Renders with `viewportAsChild` and a child that is a custom element. Asserts the child receives the `dsx-scroll-area__viewport` class and is mounted as a `Slot` host.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select (`1`, `2`, `3`) | `1` |
+| `radius` | select (`none`, `sm`, `md`, `lg`, `full`) | `md` |
+| `viewportAsChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-scroll-area`: the Radix primitive. `Root`, `Viewport`, `ScrollAreaScrollbar`, `ScrollAreaThumb`, and `Corner` are imported and re-rendered under the DS slot names.
+- `classnames`: used to merge the slot classes with the caller's `className` on every slot.
+
+**Used by:**
+
+- `Select`, `Combobox`, `HoverCard`, and `DropdownMenu` use `ScrollArea` to bound long option lists and rich content panels. App code uses `ScrollArea` directly for chat surfaces, sidebars, and product lists.
+
+**State boundaries:**
+
+- Owned by this component: the DS shell class wiring, the `data-size`, `data-radius`, and `data-slot` attributes, the slot classes, the `viewportAsChild` composition, and the auto-mount of the viewport, scrollbars, and corner.
+- Owned by the Radix primitive: the scroll math, the keyboard support, the screen-reader semantics, the scrollbar visibility logic, and the `data-state` and `data-orientation` attributes.
+- Owned by the consumer: the scrollable content, the `viewportAsChild` host, the `viewportClassName`, the `ScrollArea.ScrollBar` orientation when the consumer renders a custom scrollbar, and the `aria-label` for the scroll region.
+
+**Boundary rules:**
+
+- App-owned data: the scrollable content, the scroll region label, and any custom scrollbar host.
+- DS-owned visuals: token bindings, the `dsx-scroll-area` and slot classes, the `data-size`, `data-radius`, and `data-slot` attributes, and the auto-mount contract.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. The package source is the only authority.
+
+### Root board
+
+- **Name**: `Components / ScrollArea`.
+- **Dimensions**: `240 × 200`.
+- **Layout**: `Flex` with `horizontalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: ScrollArea>
+  ├── <Viewport with scrollable content>
+  ├── <Vertical scrollbar>
+  │     └── <Thumb>
+  ├── <Horizontal scrollbar>
+  │     └── <Thumb>
+  └── <Corner>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Root | fill | `var(--dsx-color-surface)` | Color | `fills` |
+| Scrollbar visible | fill | `var(--dsx-color-surface-sunken)` | Color | `fills` |
+| Thumb | fill | `var(--dsx-color-gray-8)` | Color | `fills` |
+| Thumb (hover) | fill | `var(--dsx-color-gray-10)` | Color | `fills` |
+| Corner | fill | `transparent` | Color | `fills` |
+
+### State transformations
+
+| State | Scrollbar fill | Thumb fill | Thumb opacity |
+|---|---|---|---|
+| `default` | hidden | `var(--dsx-color-gray-8)` | `0.7` |
+| `hover` | `var(--dsx-color-surface-sunken)` | `var(--dsx-color-gray-10)` | `0.9` |
+| `visible` | `var(--dsx-color-surface-sunken)` | `var(--dsx-color-gray-8)` | `0.7` |
+
+### Variant model
+
+- `size`: `1`, `2`, `3`. Default `1`.
+- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default `md`.
+- `viewportAsChild`: `true`, `false`. Default `false`.
+- Total members: 30 (3 sizes × 5 radii × 2 `viewportAsChild` values).
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.