# Docs Shell (Moonarc)

A documentation layout: a sticky sidebar with the current page marked, a reading-progress hairline bound to the scroll, the header and content revealed in two beats, and previous/next links. Content is the default slot.

- Pro block. Install: `npx shadcn@latest add @moonarc-pro/docs-shell` (license key required)
- Tier B · category section · trigger scroll
- Readout: `<DocsShell groups={[…]} title="…"> <Content />`
- Browser support: limited (Chrome 115 · not Firefox · Safari 26); elsewhere: no progress hairline (Firefox); everything else unchanged
- Measured cost: 0 B JS of its own · uses Reveal + runtime (with dependencies 3.0 kB raw; CSS 10.8 kB raw)
- Page: https://moonarc.dev/components/docs-shell/

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `level` | `1 | 2` | `1` | Heading level of the headline: 1 on a page's own hero, 2 under another h1 (a demo, or a block further down). At 1 the content column is the page's <main>; at 2 a div, because a page has one main and it is the one around the shell. |
| `groups` | `{ title, links: { href, label, current? }[] }[]` | none | Sidebar groups. |
| `title` | `string` | none | Page title. |
| `description` | `string` | none | Lead under the title. |
| `prev` | `{ href, label }` | none | Previous page. |
| `next` | `{ href, label }` | none | Next page. |
| `tone` | `'surface' | 'muted' | 'ink' | 'brand'` | `unset (paints nothing)` | The ground: the page surface, a muted band, an always-dark ink panel, or a deep brand panel. Each paints --background, --ma-tone-muted (over --muted, with a --border hairline), --ma-tone-ink or --ma-tone-brand (over --primary) with the matching text. With theme.css, a painted tone also re-declares --card, --border, --input and --ring inside the section, so cards and fields follow the ground. Decoration is strongest on brand. |
| `density` | `'compact' | 'cozy' | 'roomy'` | `'cozy'` | Block padding ×0.8 / ×1 / ×1.25 through --ma-density. |
| `label` | `string` | `'Docs'` | Accessible name of the sidebar's nav. Make it unique per page. |
| `pagerLabel` | `string` | `'Pagination'` | Accessible name of the previous and next links' nav. |
| `prevLabel` | `string` | `'Previous'` | Small text over the previous link. |
| `nextLabel` | `string` | `'Next'` | Small text over the next link. |

## Usage

```astro
---
import DocsShell from '@/components/moonarc/pro/DocsShell.astro';
---
<DocsShell
  title="Installation"
  description="One command."
  groups={[{ title: 'Start', links: [{ href: '/docs/installation/', label: 'Installation', current: true }, { href: '/docs/runtime/', label: 'Runtime' }] }]}
  next={{ href: '/docs/runtime/', label: 'Runtime' }}
>
  <Content />
</DocsShell>
```

## Reduced motion

Header and content fade in; the progress hairline stays (it is information).

## With ClientRouter

Inherits Reveal and ScrollProgress; the sidebar is plain links.

## Craft

- Header first, content 100 ms later: two beats, so the title is read before the prose arrives.
- The sidebar is sticky with its own scroll, so a long table of contents never pushes the content down.
- Content is capped at 44 rem to keep a docs line under 80 characters.

## Replaces

- Starlight-style shells
- Docs layouts (Tailwind Plus)

## Source

Pro block. The source is served by the license-gated registry: `npx shadcn@latest add @moonarc-pro/docs-shell` with a key in components.json (https://moonarc.dev/account/). Everything it composes is free: scroll-progress, reveal.