DESIGN.md@website · git:20261025.522b1c0 · 2026-10-25 · sha256 59ae22360596522e
DESIGN.md@website git:20261025.522b1c0A
Immutable. This exact content never changes and is served at /api/v1/blob/59ae22360596522e.
# Orbit Website — Design
The design contract for `orbit-cli.com`: what the site is for, how it looks, how it is organized and how its pages are written. Read it before changing the site's look, navigation or homepage.
---
## 1. Purpose & Audience
The Orbit website is a **documentation site**, not a marketing site. It exists to host:
- Reference documentation (CLI commands, activity/job YAML schemas, policy formats)
- How-to guides (task lifecycle, delivery windows, recurring work, task publication)
- Conceptual explainers (activity/job model, task lifecycle, agent runtimes)
**Primary audience:** engineers evaluating or actively using Orbit. They arrive via search, know roughly what they want, and leave as soon as they have it. The site optimizes for that path.
**Non-goals:**
- Lead generation, conversion funnels, email capture
- Blog, changelog-as-narrative, release announcements (those live in `CHANGELOG.md` and git)
- Interactive playgrounds or live demos (revisit if Orbit grows a hosted offering)
---
## 2. Design Principles
1. **Reference-heavy, search-first.** Users land via `⌘K` or Google. Every page must be findable and self-contained.
2. **Minimalism as a feature.** Restraint is the aesthetic. One accent color, one type family per role, no decorative motion in docs content.
3. **Legibility over personality.** The orbit metaphor shows up structurally (logo, section glyphs) — never at the cost of reading comfort.
4. **Static and fast.** Content is rendered at build time. Small browser scripts
support search, the theme toggle, and the homepage's narrow-viewport Menu;
they should not delay the page's readable state.
5. **Dark-default, light-available.** First-time visitors see dark whatever their OS prefers; the theme toggle persists an explicit choice, and a stored light choice wins. Neither mode is an afterthought.
Visual reference: the Radix Primitives docs. Density reference: the Tailwind docs.
---
## 3. Visual System
### 3.1 Palette (dark, default)
| Role | Value | Notes |
|-------------------|-------------|--------------------------------------------|
| Background | `#0A0A0A` | Reading surface; avoids pure-black eye strain |
| Surface | `#17171A` | Cards, code blocks, sidebar hover |
| Border | `#26262B` | Structural only; never decorative |
| Body text | `#EDEDF0` | High contrast on the reading surface |
| Muted text | `#9B9BA3` | Metadata, captions, inactive nav |
| Accent | `#6E9FFF` | Links, active nav, focus |
| Accent (hover) | `#8AB3FF` | One step brighter |
Light mode keeps the same roles on a `#FFFFFF` background with `#17171A` body
text and a darker `#2F67D8` accent for AA contrast. `:root` in `custom.css`
carries the dark tokens, so a page renders dark even without JavaScript;
`:root[data-theme='light']` overrides them. The inline script in
`ThemeProvider.astro` sets `data-theme` before first paint: light only when the
visitor's stored choice (`orbit-theme-choice`) is `light`, dark otherwise,
regardless of `prefers-color-scheme`. A plain page load does not save a theme
preference; the toggle saves an explicit light or dark choice.
### 3.2 Typography
| Role | Family | Size / Line-height |
|-------------------|--------------------------------|--------------------------|
| Body | Geist (self-hosted) | 16px / 1.65 |
| Headings | Same sans, tighter tracking | h1 2rem · h2 1.5rem · h3 1.25rem |
| Code (inline/block) | Geist Mono (self-hosted) | 14px / 1.6 |
| UI (nav, search) | Same sans as body | 14px |
No display font. No serif anywhere. Both families ship as npm packages
(`@fontsource-variable/geist`, `@fontsource-variable/geist-mono`) listed in
`customCss`, so the site loads no fonts from other domains.
### 3.3 Orbit motif (sparing use)
- **Logo:** a single thin ring with an offset dot. Must be legible at 16px favicon size.
- **Section dividers** in long pages: 1px rule with a small ring glyph centered.
- **Landing page:** the hero carries one demo video, a tour of the real dashboard (see 3.5), not an orbit diagram. It is the only motion on the site and stops for readers who ask for reduced motion.
- No starfields, parallax, planet illustrations, or animation anywhere inside docs content.
### 3.4 Layout
Three-column, fixed:
```
┌──────────────────────────────────────────────────────┐
│ Logo Search (⌘K) ☾ │
├──────────┬───────────────────────────┬───────────────┤
│ Nav │ Content (max ~720px) │ On this page │
│ (left) │ │ (right) │
│ │ │ │
└──────────┴───────────────────────────┴───────────────┘
```
- Left nav: collapsible sections. Active page marked with a 2px accent bar on the left edge.
- Content column: max-width ~720px, measure 65–75ch for prose.
- Right rail: sticky "On this page" TOC. Muted until the corresponding section is in view.
- Top bar: logo, latest-release badge (read from `CHANGELOG.md` at build time),
section links including Changelog (from 50rem), search, theme toggle. Below 50rem the
splash header keeps search and exposes section links plus theme through a Menu
disclosure; documentation pages keep Starlight's sidebar Menu.
### 3.5 Landing page
The homepage replaces Starlight's auto-rendered title with an in-content hero;
a CSS rule scoped to the homepage hides the title. Other pages keep Starlight's
default chrome (auto title, sidebar, TOC).
- **Hero:** a release chip linking to the changelog, the headline, a lede that
says what Orbit is, the CTAs, a requirements note and the shipped CLI
executors as a plain list. A legacy executor is footnoted, never implied
current.
- **Hero video:** the site's only motion, a muted, looping tour of the real
dashboard. It stays on its poster frame under
`prefers-reduced-motion: reduce`, its caption dates the capture so its counts
read as a snapshot, and its `aria-label` narrates it. The source lives in
`marketing/media/video/orbit-dashboard-tour-v3`; the site serves a web re-encode
from `public/media/`. Public cuts omit production task, friction and run
identifiers, including those in source screenshots, address bars and
diagnostic prose. Sanitize before camera pans and encoding; inspect decoded
frames across every chapter and transition before publishing.
- **Below the hero:** short sections that take a reader from what Orbit
promises, to how it works and runs unattended, to where to go next. Each
opens on a two-column head: a mono eyebrow and one-sentence heading, then a
short lede. The page ends on a Quickstart whose copy buttons copy exactly
the command shown. The footer, not the page, carries the full docs index.
Rules for the page:
- Commands shown match current CLI behaviour, and illustrative output says it
is illustrative.
- Advertise no unlanded feature and publish no live metric; captured numbers
carry their capture date.
- Scripts stay small and serve only the page's documented interactions: the
shared theme script, the Menu's Escape and breakpoint close, the copy
buttons, and pausing the hero video under reduced motion. Nothing delays the
readable state.
---
## 4. Information Architecture
Top-level sections (left nav, in order), following the reader from setup to
lookup:
1. **Get started** — what Orbit is, quickstart, install, connect your agent
(MCP), first task, delivery workflows
2. **Concepts** — tasks, agents and crews, activities and jobs, routines and
auto-tasks, policies
3. **Guides** — task-oriented recipes for everyday use, including backup and
restore and multi-machine drains
4. **Reference** — CLI, configuration, YAML schemas, policy format, scoping
5. **Project** — changelog, contributing (collapsed), privacy
Sidebar labels match page titles (section indexes read "Overview"). Moving a page between groups never moves
its URL.
Each section has an index page that lists its children with one-line descriptions. No "coming soon" placeholders — sections appear only when populated.
---
## 5. Tech Stack
- **Framework:** [Astro Starlight](https://starlight.astro.build)
- **Search:** Pagefind (built into Starlight, static, offline, no third-party account)
- **Content:** Markdown (`.md`) in `src/content/docs/`
- **Styling:** Starlight's CSS custom properties, overridden in a single `custom.css`
- **Hosting:** The public edge and DNS are on Cloudflare. Daniel manually
publishes the static output; the `orbit-cli.com` DNS remains externally
managed, and this repository neither provisions hosting nor edits DNS.
Cloudflare Pages applies the repository-owned `public/_headers` policy to
HTTPS responses; the externally managed Cloudflare zone owns HTTP-to-HTTPS
redirection.
- **Repo layout:** `website/`, independent of the Rust workspace
---
## 6. Content Conventions
- **Page frontmatter:** `title`, `description` required; `sidebar.order` optional.
- **Headings:** start at `h2` within content (Starlight renders `h1` from frontmatter).
- **Code blocks:** always language-tagged. Long examples collapsible.
- **Cross-links:** relative paths only; no hardcoded domains.
- **Internal references:** do not publish repository-internal artifact identifiers in docs pages. The one exception is the changelog page: it renders `CHANGELOG.md` as-is, and its bracketed task IDs stay because they are the pointer from a release note to the pull request that delivered it.
- **Voice:** terse, declarative, second-person ("you run", not "the user runs"). No marketing adjectives.
---
## 7. Out of Scope
- Interactive code playgrounds
- Authenticated / gated content
- Localization (revisit if Orbit gains non-English contributors at scale)
- Comments, discussions, or embedded social
- A blog
- Analytics, unless there is a decision to measure something specific
- Versioned docs, until release-specific documentation is needed
- Crate boundaries and dependency direction: contributor material that lives in the repository's `ARCHITECTURE.md`