# shuttering

> design system documentation

Reference documentation for the shuttering design system: installation, theming, and every component with its props, variants, and accessibility notes. Every page is deep-linkable at /<page>, and the docs dogfood the always-on agent surfaces the system ships.

## Principles

This is the reference documentation for a design system whose components emit their machine-readable surfaces structurally — a copy-as-API affordance, a shareable deep link, and inline JSON-LD — rather than behind a mode a caller switches on. The documentation itself is addressable one page per path, and its own machine surfaces are the manifest, this file, and the sitemap.

## Deep-link grammar

Application state is fully addressable from `/`. A malformed link degrades to defaults rather than erroring — the deep-link grammar is the app's state machine. Parameters:

- `page` — path segment; one of introduction | installation | theming | conventions | customizing | buttons | forms | overlays | navigation | feedback | data-display | layout | motion | charts | agent | ai | signature | icons | typeset; default `introduction`; the documentation page to open

Examples:

- [Introduction](/introduction): What shuttering is and the packages it ships.
- [Installation](/installation): Authenticate the registry, install, and load the stylesheets in order.
- [Theming](/theming): Tokens, the swappable palettes, and light/dark.
- [Conventions](/conventions): The authoring rules the packages hold to.
- [Customizing per app](/customizing): Fonts, a custom palette, and the token override protocol.
- [Buttons & badges](/buttons): Button, Badge, and StatusChip.
- [Forms & inputs](/forms): Inputs, selection controls, and the zod-validated form layer.
- [Overlays](/overlays): Dialog, Drawer, Tooltip, Spotlight, and the imperative confirm.
- [Navigation](/navigation): SegmentedNav, MegaMenu, the command palette, tabs, and accordion.
- [Feedback](/feedback): Callouts, toasts, empty states, and the stepper.
- [Data & surfaces](/data-display): DataTable, StatCard, Avatar, Separator, and the Card surface.
- [Layout & structure](/layout): The composable Footer, PageHeader, AppShell, and the spacing primitives.
- [Motion](/motion): Reduced-motion-aware primitives and effects.
- [Charts](/charts): ECharts wrapped and themed from live tokens.
- [Agent surfaces](/agent): The always-on machine-readable layer.
- [AI](/ai): Chat, streaming, tool calls, and the chatbot widget.
- [Signature](/signature): Domain identity, the house "hand", voice, and user acknowledgment.
- [Icons](/icons): The glyph contract for bespoke domain icons, and where the vendored set stops.
- [Typeset](/typeset): Prose typography for rendered markdown, wired to the tokens.

## Copy as API

The affordance is documented at /agent, and rendered live over a chart at /charts: a panel that exposes runnable client snippets (curl, python, TypeScript), the rows behind the visualization, and a shareable deep link.

## Machine-readable

- [Manifest](/.well-known/shuttering.json): the capability declaration for this surface
- [llms.txt](/llms.txt): this file
- [Sitemap](/sitemap.xml): every addressable path, including these two