The Docs

The page, section by section

1. 01

   Docs sidebar

   Chapter Rail

   Pages grouped into chapters, each filling as you read it, with a filter on / : the spine of the docs and how far through you are.

2. 02

   Phone navigation

   Docket Nav

   On phones the sidebar gives way to a bar whose Menu names the chapter in view and opens into a numbered list of chapters.

3. 03

   Where you are

   Pleat Crumbs

   Product, version and section; each level unfolds its siblings in place, so switching version is one move.

4. 04

   Search

   Shortcut Palette

   ⌘K searches every page by title and chapter, and jumps there.

5. 05

   Install

   Install Snippet

   Tabs per package manager, numbered steps and a copy button on every block: install and sign-in in one place.

6. 06

   Concept page

   Stretchtext

   One explanation at three depths. Beginners read the gist, people debugging read the full mechanism, from the same page.

7. 07

   Definitions

   Gloss Term

   Terms like checksum and manifest open a short definition in place, so the sentence keeps going.

8. 08

   Warnings

   Alert Callout

   The one destructive flag gets a warning beside its reference, with what to do first.

Change first

The first things to replace to make this page yours.

1. Replace the install tabs with your real package managers and the exact commands, including how CI signs in.
2. Rebuild the sidebar from your real page tree, in the order a new user needs the pages, not the order you built the features.
3. Write the concept page at three depths from your actual design, and define the terms people trip on.
4. Make the reference match the binary: every flag, its default and what it does, generated from the CLI's own help if you can.

Paste it into Claude, Cursor or ChatGPT with the component files, and ask for your own version: your name, your work, your product. It names each component and where to copy it from.

# Build brief: The Docs

Documentation for a developer tool: install to first command fast, then a reference people come back to.
For: Teams documenting a CLI, SDK or API who want docs that teach first and stay useful as a reference.

Scenario: Docs for a CLI that syncs local folders to cloud storage: get someone from install to a working first sync in two minutes, explain how syncing decides what to send, and list every flag.

## Direction
- Cool and quiet: near-black (#0f1013) with raised panels (#15171b), cool grey text and one blue accent (#8fb5ff) for where you are and what you can press.
- Geist for everything you read, Geist Mono for everything you type. Code is copyable and shows real output, not just the command.
- Every component shares one palette through its own colour tokens; the sidebar's night values are the reference. The one override beyond tokens: the phone menu's display serif becomes the docs' sans.
- Desktop is two columns, sidebar and article. On phones the sidebar goes away and the navbar's menu names the chapter you're in.
- Real commands, real flags, real output. A reader should be able to copy the first-sync block and have it work.


## What to leave out
- No second table of contents. The sidebar already marks the section you're reading; an 'On this page' column of the same headings is the same information twice.
- No hero, no illustrations in the reading column. The first thing on the page is what the tool does, then the install command.
- Use Stretchtext for concepts only. Reference pages should be flat: every option visible, nothing to expand.
- One warning per page at most; if everything is a callout, nothing is.

## Page map
1. Docs sidebar: Chapter Rail. Pages grouped into chapters, each filling as you read it, with a filter on / : the spine of the docs and how far through you are.
2. Phone navigation: Docket Nav. On phones the sidebar gives way to a bar whose Menu names the chapter in view and opens into a numbered list of chapters.
3. Where you are: Pleat Crumbs. Product, version and section; each level unfolds its siblings in place, so switching version is one move.
4. Search: Shortcut Palette. ⌘K searches every page by title and chapter, and jumps there.
5. Install: Install Snippet. Tabs per package manager, numbered steps and a copy button on every block: install and sign-in in one place.
6. Concept page: Stretchtext. One explanation at three depths. Beginners read the gist, people debugging read the full mechanism, from the same page.
7. Definitions: Gloss Term. Terms like checksum and manifest open a short definition in place, so the sentence keeps going.
8. Warnings: Alert Callout. The one destructive flag gets a warning beside its reference, with what to do first.

## Change first
- Replace the install tabs with your real package managers and the exact commands, including how CI signs in.
- Rebuild the sidebar from your real page tree, in the order a new user needs the pages, not the order you built the features.
- Write the concept page at three depths from your actual design, and define the terms people trip on.
- Make the reference match the binary: every flag, its default and what it does, generated from the CLI's own help if you can.

## Components
Copy each component's files from its page (Code tab) into your project before you start, and use them as given: change props and content, not internals.
- Chapter Rail: https://tryvitrine.dev/components/chapter-rail (A docs sidebar that knows where you are: the page you're reading lights up and a rail beside the pages fills as you scroll, so every chapter shows how far through it you are, with a ring round its icon.)
- Docket Nav: https://tryvitrine.dev/components/docket-nav (A product navbar that knows where you are: a hairline under the links slides to the section in view, and on a narrow bar the links fold into a Menu that still names the current section and opens into a numbered docket.)
- Pleat Crumbs: https://tryvitrine.dev/components/pleat-crumbs (A breadcrumb where every level is a fold.)
- Shortcut Palette: https://tryvitrine.dev/components/shortcut-palette (A command palette that teaches: type a few letters, run the command, and if it has a keyboard shortcut a quiet line tells you once the action has happened.)
- Install Snippet: https://tryvitrine.dev/components/install-snippet (The install-and-connect block of a developer page: client tabs, numbered steps, hard-edged dark code blocks, and a copy button that only says Copied when the clipboard really took it.)
- Stretchtext: https://tryvitrine.dev/components/stretchtext (One article at three depths.)
- Gloss Term: https://tryvitrine.dev/components/gloss-term (Inline definitions for running text: a dotted word opens a small card on hover, focus or tap.)
- Alert Callout: https://tryvitrine.dev/components/alert-callout (Inline alerts in four tones (information, success, warning, danger), each with its own mark, a short title, a sentence, the actions that resolve it and a close button that folds the message away smoothly.)

## Build
- Next.js (App Router), TypeScript, Tailwind CSS. No extra UI libraries.
- Write real content for this site: real names, dates, numbers and sentences. No lorem ipsum, no "Feature one".
- Compose the sections in the order of the page map. Keep each component's own spacing; add page rhythm with consistent section padding.
- Mobile first: every section must work at 375px wide without horizontal scrolling.
- Respect prefers-reduced-motion everywhere; every Vitrine component already does.

## Before you ship
- Run `/content-structure-auditor` (https://tryvitrine.dev/workshop/skills/content-structure-auditor): Docs fail on order: install, first success, concepts, then reference, in the order questions are asked.
- Run `/interface-copy` (https://tryvitrine.dev/workshop/skills/interface-copy): Commands, flags, warnings and error output are copy too; this keeps them exact and consistent.
- Run `/responsive-art-direction` (https://tryvitrine.dev/workshop/skills/responsive-art-direction): The sidebar becomes the navbar's menu on phones; this designs that hand-off rather than squeezing the rail.
- Run `/search-optimization` (https://tryvitrine.dev/workshop/skills/search-optimization): ⌘K search is how returning readers navigate; its results should match what they type.
- Run `/responsive-audit` (https://tryvitrine.dev/workshop/skills/responsive-audit): Code blocks and option tables are where docs scroll sideways on a phone.
- Run `/accessibility-pass` (https://tryvitrine.dev/workshop/skills/accessibility-pass): The sidebar, breadcrumb menus, install tabs, definitions and search all need to work by keyboard.

Direction

• Cool and quiet: near-black (#0f1013) with raised panels (#15171b), cool grey text and one blue accent (#8fb5ff) for where you are and what you can press.
• Geist for everything you read, Geist Mono for everything you type. Code is copyable and shows real output, not just the command.
• Every component shares one palette through its own colour tokens; the sidebar's night values are the reference. The one override beyond tokens: the phone menu's display serif becomes the docs' sans.
• Desktop is two columns, sidebar and article. On phones the sidebar goes away and the navbar's menu names the chapter you're in.
• Real commands, real flags, real output. A reader should be able to copy the first-sync block and have it work.

What to leave out

• No second table of contents. The sidebar already marks the section you're reading; an 'On this page' column of the same headings is the same information twice.
• No hero, no illustrations in the reading column. The first thing on the page is what the tool does, then the install command.
• Use Stretchtext for concepts only. Reference pages should be flat: every option visible, nothing to expand.
• One warning per page at most; if everything is a callout, nothing is.