# Design

## Overview

OffRouter has two designed surfaces.

- The CLI and MCP output form the primary `developer-ui` surface.
- The documentation site is a supporting `product-ui` surface.

CLI sources are under `packages/cli/src/commands/` and `packages/mcp/src/tools/`.
Site sources are `site/*.html` and `site/assets/style.css`.

Both surfaces favor explicit decisions, compact status, and visible policy
boundaries.

## Colors

The site uses semantic properties from `site/assets/style.css`.

| Role             | Token             | Value     |
| ---------------- | ----------------- | --------- |
| Canvas           | `--bg`            | `#0a0a0c` |
| Raised surface   | `--surface`       | `#0e0e12` |
| Primary text     | `--fg`            | `#ececf1` |
| Secondary text   | `--muted`         | `#a5a5ae` |
| Border           | `--border`        | `#1f1f26` |
| Strong border    | `--border-strong` | `#34343e` |
| Action and focus | `--accent`        | `#f0b429` |
| Action hover     | `--accent-hover`  | `#f5c14e` |
| Accent text      | `--accent-ink`    | `#0a0a0c` |

Reserve amber for actions, focus, prompts, and the brand mark. The CLI defines
no ANSI palette. Text must carry every status without color.

## Typography

The site uses the system sans-serif stack in `--sans`. Code, commands, and
identifiers use the system monospace stack in `--mono`.

Body text is `16px` with `1.65` line height. Site headings use weight `600` or
`700` with tight tracking.

The CLI inherits terminal typography. JSON output uses two-space indentation.
Preserve exact command, profile, provider, and policy identifiers.

## Layout

The site container has a `768px` maximum width. The body uses `1.25rem` side
padding. Card grids use two columns and a one-pixel gap.

At `640px`, grids become one column. Documentation rows stack their title and
description. The site header and action rows wrap.

CLI output uses one fact per line. Indent account and model rows by two spaces.
Use blank lines around multi-step login instructions.

## Elevation & Depth

The site stays flat. One-pixel seams separate surfaces. Notices use an amber
left border. Buttons use solid borders without shadows or gradients.

Terminal depth is not applicable. Use indentation and line order for hierarchy.

## Shapes

Site buttons, cards, code blocks, and the square wordmark use hard corners. The
favicon alone uses a six-pixel outer radius.

CLI denial lists use `-`. Warnings use `!`. Login results use `✓` and `✗` with
plain-language text.

## Components

- `.site-header` contains the wordmark and primary documentation links.
- `.btn` and `.btn-secondary` express primary and secondary actions.
- `.command` and `pre` show copyable terminal input.
- `.honesty` keeps the V1 boundary visible.
- `.grid` and `.card` group features without visual depth.
- `.doc-list` presents documentation links as scan-friendly rows.
- `writeText()` and `writeJson()` normalize CLI output and final newlines.

Keep visible focus outlines, landmarks, labels, and skip links. Let long code
and command blocks scroll horizontally.

## Do's and Don'ts

- Do reuse semantic CSS properties. Do not add a second site palette.
- Do reserve amber for focus and action. Do not use it as decoration.
- Do keep square interface geometry. Do not add ornamental rounding.
- Do state policy denials in text. Do not depend on color or symbols alone.
- Do keep text and JSON output stable. Do not mix prose into JSON mode.
- Do preserve the V1 honesty line. Do not imply primary-model replacement.
- Do retain keyboard focus. Do not remove the amber focus outline.
- Do keep pages usable at `640px` and below. Do not force two columns on mobile.