# Docs foundations
> What @sdxc/ui/docs is for, the reading, heading and island rules its parts share, and every variable it reads.

A documentation site's shell and the blocks around its prose: sidebar, On this page rail, page header, code, steps, callouts, props tables, pager, hub and a 404 that searches.

Pages are server HTML; a few small islands add copying, sidebar filtering, the rail's marker and synced tabs.

Import the components from `@sdxc/ui/docs` and the theme once from `@sdxc/ui/theme.css`.

## When to reach for it

- A guide, tutorial or reference site for developers, such as a library's docs or an API reference.
- Product help docs: task pages, troubleshooting and a hub that routes a reader by what they want to do.
- Any long-form page read in a sidebar-and-article shell rather than as a landing.

## Shared ideas

- **Two measures.** Prose stops at `proseMeasure` (66ch); code, tables and images fill `measure` (64rem).
- **Reading type.** Wrap prose in `<Typeset preset="docs">`: 18px on a 1.75 line. Opt a block out with `data-not-typeset`.
- **Heading levels.** `DocsPageHeader` renders the one `h1`; `AnchorHeading` and `Steps` follow the ambient `HeadingScope`.
- **One tree.** A `DocsTree` feeds `DocsNav`, `DocsPager` and search, so adding a page is one edit.
- **Layout.** The sidebar docks from `dock` (48rem or 64rem) and the rail shows from 75rem; narrower, they become a drawer and a sticky bar.
- **Motion.** Only state changes animate, 150–300ms, and they stop under `prefers-reduced-motion`.
- **Accessibility.** `DocsNav` marks `aria-current`, copy buttons announce through a status region, and `CodeTabs` is a radio group.
- **Islands.** Map `table-of-contents`, `docs-nav-tools`, `copy-button`, `code-tabs-sync` and `page-actions` from `@sdxc/ui/docs/*`.

## CSS variables

Every custom property the namespace reads or declares. Reads the neutral and brand roles, plus success, warning and danger for Callout kinds, diff lines and required props. The roles are documented on Theming.

### Reading and scrolling

The docs variables are set through `DocsLayout`'s props and `Typeset`'s preset; override one on a single block where it needs a different value.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-docs-prose-measure` | `set by DocsLayout from proseMeasure (66ch)` | Widest line of running text; paragraphs, lists, headings and callouts stop at it. |
| `--ui-docs-scroll-margin` | `5rem; DocsLayout sets it from stickyTop` | Space a jumped-to heading leaves above itself to clear the sticky chrome. |
| `--ui-typeset-size` | `1.125rem in the docs preset` | Body size; prose headings scale from it. |
| `--ui-typeset-leading` | `1.75 in the docs preset` | Line height of running text. |
| `--ui-typeset-flow` | `1.25em in the docs preset` | Space between blocks of prose. |
| `--highlight-<token>` | `a light-dark() pair per token, such as #6a737d / #8b949e for comment` | Color of one syntax token in `CodeBlock`: keyword, string, comment and the rest. |

### Shape and elevation

Read through `@sdxc/u`'s `rounded()` and `shadow()`; `theme.css` declares none of them, so each default is the fallback an app overrides by declaring the variable.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-radius-sm` | `0.25rem` | Corners of `AnchorHeading`'s link and `FileTree` rows. |
| `--ui-radius-md` | `0.375rem` | Corners of `Callout`, `PlanNotice`, `CopyButton` and `PageActions`. |
| `--ui-radius-lg` | `0.5rem` | Corners of `CodeBlock`, `FileTree`, sidebar groups and hub, pager and next-step cards. |
| `--ui-radius-full` | `9999px` | Pills: the rail's marker, step numbers, feedback buttons and hub chips. |
| `--ui-shadow-float` | `none` | Elevation of the sticky bar's heading list. |

### Set by the components

Written by `DocsLayout`, the tocSpy mixin, `Typeset` or `PageActions` and read back by their own parts. Leave them unset.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--docs-sticky-top` | `set by DocsLayout from stickyTop (0px)` | Where the sidebar, bar and rail stick. |
| `--docs-gutter` | `1rem, 1.5rem from 48rem, 2rem from 64rem` | Inline padding of the shell, which the sticky bar bleeds through. |
| `--toc-marker-start, --toc-marker-size` | `0px, written by tocSpy()` | Offset and length of the marker over the sections on screen. |
| `--toc-progress` | `0, written by tocSpy()` | How full the sticky bar's progress ring is. |
| `--ui-typeset-table-fade-direction` | `right; left in right-to-left text` | Side a wide table's scroll fade sits on. |
| `--ui-button-radius` | `set by PageActions` | Squares the inner corners of the split Copy page button. |