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.
See the components assembled into whole sites in the demo gallery.
import "@sdxc/ui/theme.css";
import { … } from "@sdxc/ui/docs";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 measuresProse stops at
proseMeasure(66ch); code, tables and images fillmeasure(64rem). - Reading typeWrap prose in
<Typeset preset="docs">: 18px on a 1.75 line. Opt a block out withdata-not-typeset. - Heading levels
DocsPageHeaderrenders the oneh1;AnchorHeadingandStepsfollow the ambientHeadingScope. - One treeA
DocsTreefeedsDocsNav,DocsPagerand search, so adding a page is one edit. - LayoutThe sidebar docks from
dock(48rem or 64rem) and the rail shows from 75rem; narrower, they become a drawer and a sticky bar. - MotionOnly state changes animate, 150–300ms, and they stop under
prefers-reduced-motion. - Accessibility
DocsNavmarksaria-current, copy buttons announce through a status region, andCodeTabsis a radio group. - IslandsMap
table-of-contents,docs-nav-tools,copy-button,code-tabs-syncandpage-actionsfrom@sdxc/ui/docs/*.
CSS variables
Every custom property the namespace reads or declares, with its default and what it controls.
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. |