On Book Docs Design System

Overview

On Book Docs should feel like a calm, theatrical operations manual: clear enough for a new production team member, precise enough for internal operators, and restrained enough to stay trustworthy under rehearsal pressure. The site inherits the On Book Pro product language, then softens it for documentation with a warmer public-docs canvas, approachable headings, and fewer app-like controls.

This file is the canonical visual identity source for the docs repo. Use it for VitePress styling, screenshots, diagrams, and HyperFrames walkthrough videos. For feature walkthroughs, the product should feel like a stage-management command surface, not a generic software promo: source-grounded, scannable, and quietly polished.

Colors

Amber is the cue-light accent. Use primary for the highest-priority action, focus state, selected navigation item, timeline marker, or key callout. Do not use amber as a broad background wash.

Deep navy and Prussian blue anchor the brand. Use background-dark, surface-dark, surface-dark-alt, and sidebar-dark for dark-mode docs, preview frames, video panels, and performance-oriented walkthrough moments that need low glare. Use secondary for institutional brand surfaces and stable navigation accents.

The documentation canvas uses a warm off-white scale: background, background-soft, and background-alt. These values are intentionally a little warmer than the product app canvas so prose pages feel readable and editorial while still staying close to the On Book Pro system.

Use text, text-muted, and text-subtle for light-mode hierarchy. Use text-inverse, text-inverse-muted, and text-inverse-subtle on dark surfaces. Borders should do most of the separation work; prefer border, border-muted, and border-dark before adding heavy shadows.

Use state colors sparingly: emerald for completion, red for destructive or failed states, blue for neutral information, purple only for AI or creative affordances, and orange warning only when the user needs to slow down.

Typography

Use Nunito for documentation headings, hero text, and brand moments. It gives the docs site a slightly warmer voice than the product app while preserving the On Book identity. Use Inter for body text, navigation, labels, tables, callouts, and dense feature summaries. Use JetBrains Mono for inline code, command snippets, generated routes, and API identifiers.

Keep letter spacing at 0px for generated interfaces and walkthrough videos. The existing VitePress theme uses slight negative tracking on some large headings, but generated artifacts should rely on size, weight, color, and spacing for hierarchy so text remains stable across renderers.

Inside dense panels, keep headings compact. Do not use hero-scale type in feature cards, sidebars, tables, or video overlays. In 1920x1080 walkthroughs, body text should stay at 24px or larger when it must be read from the final render; smaller text may appear as realistic UI texture but should not carry the explanation.

Layout

Use an 8px spacing rhythm with 4px only for micro-adjustments. Documentation pages should be easy to skim: strong headings, short sections, visible status callouts, predictable tables, and links that clearly explain where they go.

The site can feel more editorial than the app, but it should not become a landing page. Avoid decorative card stacks, giant marketing sections, or vague feature claims. The primary job is to help a reader understand what exists, what has concrete limits, what requires human review, and where the connected workflow continues.

For walkthrough videos, keep the same operational density. Prefer split panes, sidebars, aligned rows, highlighted route paths, and focused callout overlays. Let screenshots, UI frames, or diagram panels provide the visual proof; motion should clarify sequence and attention, not decorate the frame.

Elevation & Depth

Depth is functional. Use borders and tonal surfaces before shadows. In light mode, subtle shadows are acceptable for feature cards, callouts, and hover states. In dark mode, use border contrast and surface shifts instead of large shadows.

Glass-like navigation can appear in docs previews and HyperFrames walkthroughs when it represents a real control layer above content. Pair glass with enough dimming or contrast that text remains readable. Do not use clear glass over plain backgrounds or behind low-contrast text.

Motion should be short, purposeful, and calm. Page transitions, hover lifts, callout reveals, and video highlight sweeps should feel like production cues. Avoid playful bounce, ornamental loops, or motion that makes operational content harder to scan.

Shapes

Use softly practical shapes. Inline code uses 4px radii, compact controls use 6px, normal buttons and navigation items use 8px, cards and video panels use 12px to 16px, and pills are reserved for CTAs, status chips, filters, avatars, and compact toggles.

Do not mix very sharp corners with heavily rounded containers in the same surface. Rounded corners should support readability and touch comfort, not make operational tools feel like consumer marketing cards.

Components

Primary buttons use amber with navy text and should represent one clear next action. Secondary buttons use warm quiet surfaces or ghost styling. In docs pages, CTAs may use pill shapes; in product-like walkthrough frames, buttons should look closer to the app's 8px operational controls unless the scene is explicitly about the public docs site.

Feature cards use warm soft surfaces, quiet borders, a small amber top or icon accent, and concise text. They should help readers compare options, not overwhelm them with promotional styling.

Callouts should use a left amber rule or quiet tonal surface to indicate operational status. Status language must stay concrete: prerequisites, access requirements, human-review requirements, data-retention limits, or owner-only next steps. Do not hide caveats in tiny muted text.

Code and command snippets should use JetBrains Mono with restrained amber accents. Inline code needs enough padding to read as a token but should not interrupt prose rhythm.

For HyperFrames, use video-panel as the base for dark walkthrough sections. Add amber only for focus rings, route highlights, selected rows, or the single current action. Keep captions and labels aligned to an 8px grid.

Do's and Don'ts

• Do use this file as the visual identity source for docs pages, diagrams, and walkthrough videos.
• Do use amber as a cue-light accent for the most important action or focus state.
• Do keep documentation source-grounded, scannable, and explicit about real product limits.
• Do favor borders, rows, sidebars, callouts, and stable panels over decorative card collections.
• Do use Nunito for docs headings and Inter for dense operational text.
• Do keep generated video motion purposeful, quiet, and tied to the workflow being explained.
• Don't use amber as a full-screen background, gradient wash, or decorative glow field.
• Don't turn feature documentation into generic marketing copy.
• Don't rely on color alone for status, selection, warnings, or destructive states.
• Don't put low-contrast text on glass or dark panels.
• Don't introduce new arbitrary colors without adding them to the token set first.

OKLCH Tokens

These companion values are for perceptual color adjustments in CSS or media tooling. The frontmatter remains sRGB hex for DESIGN.md compatibility.

Token	sRGB	OKLCH
colors.primary	#ffbf00	oklch(84.03% 0.1724 84.08)
colors.primary-hover	#ffce33	oklch(87.05% 0.1656 89.70)
colors.primary-active	#cc9900	oklch(71.19% 0.1460 84.61)
colors.on-primary	#0a1128	oklch(18.57% 0.0480 268.67)
colors.secondary	#003153	oklch(30.35% 0.0779 245.92)
colors.on-secondary	#ffffff	oklch(100.00% 0.0000 89.88)
colors.background	#fafaf8	oklch(98.45% 0.0026 106.45)
colors.background-soft	#f2f0ec	oklch(95.56% 0.0057 84.57)
colors.background-alt	#eae7e0	oklch(92.84% 0.0099 87.47)
colors.background-dark	#0a1128	oklch(18.57% 0.0480 268.67)
colors.surface	#ffffff	oklch(100.00% 0.0000 89.88)
colors.surface-soft	#f2f0ec	oklch(95.56% 0.0057 84.57)
colors.surface-muted	#f3f4f6	oklch(96.70% 0.0029 264.54)
colors.surface-dark	#111d35	oklch(23.36% 0.0496 263.01)
colors.surface-dark-alt	#162240	oklch(25.83% 0.0590 265.97)
colors.sidebar-dark	#0d1730	oklch(21.07% 0.0516 265.75)
colors.text	#1a1a1a	oklch(21.78% 0.0000 89.88)
colors.text-muted	#4a4a4a	oklch(40.91% 0.0000 89.88)
colors.text-subtle	#8a8a8a	oklch(63.34% 0.0000 89.88)
colors.text-inverse	#dce6f2	oklch(92.09% 0.0196 252.88)
colors.text-inverse-muted	#9ab0cc	oklch(74.99% 0.0473 254.56)
colors.text-inverse-subtle	#6b839e	oklch(60.12% 0.0498 251.64)
colors.border	#d4d0c8	oklch(85.85% 0.0118 84.58)
colors.border-muted	#e0ddd6	oklch(89.79% 0.0100 87.48)
colors.border-dark	#1e2d3b	oklch(29.03% 0.0327 247.29)
colors.success	#059669	oklch(59.60% 0.1274 163.23)
colors.danger	#ef4444	oklch(63.68% 0.2078 25.33)
colors.info	#2563eb	oklch(54.61% 0.2152 262.88)
colors.creative	#9333ea	oklch(55.75% 0.2525 302.32)
colors.warning	#e65100	oklch(63.10% 0.1970 40.25)