# Pantograph Design System The design system for **pantograph** — an open-source project comprising: - **libpanto** — an LLM provider SDK, imported as `panto` in each language. It gives one provider-agnostic call signature, faithfully reproduced across its (currently three, "and counting") language bindings: **Python, Rust, TypeScript**. - **panto** — a terminal coding agent built on top of libpanto. A minimal system prompt and a small, swappable tool set. libpanto and the panto CLI are written in **Zig** (native binaries — maximally fast and resource-efficient); the CLI embeds a **Lua** interpreter for extensions (about as fast as a dynamic scripting language gets). This system dresses the project's **web resources**: the libpanto SDK reference docs and the panto CLI docs, plus the marketing homepage. > **The metaphor.** A *pantograph* is an old drafting instrument: a linkage of hinged arms that reproduces a small drawing at a larger scale. One small motion in, one faithful enlargement out. That is exactly what libpanto does for language models — write the motion once, scale it to any provider. > **The reference object.** The visual language is taken from a **1970s Post Versalog slide rule**: an eggshell, bamboo-bodied precision instrument printed in black, red, and green. So: **no pure white and no pure black** anywhere — warm eggshell "paper" surfaces, deep blue-black "ink" marks, and two engraved accents (instrument red, instrument green). --- ## Sources This is a **greenfield** system — no codebase, Figma file, or prior brand was supplied. Everything here is derived from the written brief (the pantograph concept + the Post Versalog slide rule as a physical reference). If a repository or design file exists, link it here so future work can cross-reference: - Repository: _(none provided — add the GitHub URL here)_ - Design file: _(none provided)_ - Reference object: Post Versalog slide rule (c. 1970s), eggshell over bamboo, black/red/green markings. --- ## CONTENT FUNDAMENTALS How pantograph writes. The voice is that of a **well-made instrument manual**: plainspoken, precise, and quietly confident. It never oversells. The throughline is **minimalism** — pantograph is light, straightforward, and fast. *Everything you specify, nothing you don't.* - **Tone:** Calm, technical, exact. We describe what the tool *does*, in the order it does it. The pantograph metaphor is used sparingly and only when it clarifies ("write the motion once, scale it to any provider") — never as decoration. - **Lead with minimalism, not magic.** The product is small on purpose: a minimal system prompt, a small tool set, swap any of it out. It is fast and lean because it is written in Zig (native binaries) and extended in Lua. Say *what isn't there* as a feature. - **Don't claim gates it doesn't have.** panto has **no permission prompts** — that would be more, not less. So avoid "waits for yes / waits for approval." And avoid "install with one line" as a headline; the story is restraint, not convenience tricks. - **Person:** Address the reader as **you**; the project refers to itself by name (**panto**, **libpanto**, **pantograph**) or as **we** in prose. Avoid "I". - **Casing:** The product names are **always lowercase** in body and wordmark: `pantograph`, `panto`, `libpanto`. Sentence case for headings and UI ("Same call, every language"). Engraved labels/eyebrows are **UPPERCASE** with wide tracking (the slide-rule scale-label voice): `SDK REFERENCE`, `GETTING STARTED`. - **Commands read like commands.** CLI examples use the imperative, lowercase, quoted: `panto run "add rate limiting to the login route"`. - **Numbers & specifics over adjectives.** "Returns a typed Response — text, usage, stop reason" beats "powerful, flexible responses". Cite versions (`since v2.0`), diffs (`+24 −3`), counts ("3 and counting"). - **No hype, no emoji.** Never "🚀 unlock the power of next-gen AI". Emoji are **not** used in the brand. (See `guidelines/brand-voice.card.html` for the say/don't-say pairs.) - **Status is stated, not implied:** `Stable`, `Beta`, `Deprecated`, `since v2.0`, `removed in v3`. **Specimen copy** - Headline: *"Scale one prompt to every provider."* - Lead: *"libpanto is a single, small set of motions — faithfully reproduced across OpenAI, Anthropic, and your local models."* - Positioning line: *"Everything you specify, nothing you don't."* - Callout: *"A minimal prompt and tool set — swap any piece for your own. Written in Zig, extended in Lua."* --- ## VISUAL FOUNDATIONS The whole system is an eggshell instrument printed in ink. Restraint is the point. ### Color - **Two ramps, two accents, nothing else.** Warm **paper** (eggshell, `#F6F0E2 → #BFAE8A`) for surfaces; deep blue-black **ink** (`#161B27 → #8C8470`) for marks. The darkest ink is a *blue*-black, never `#000`; the lightest paper is eggshell, never `#fff`. - **Instrument red** (`#B23A2E`) = the cursor line, danger, and the single primary accent. **Instrument green** (`#2F6B4A`) = success, the "folded" scales, focus rings. Used like a draftsman: *sparingly, for meaning, never as fields.* A page should read black-on-eggshell with red/green appearing only at points of emphasis. - **Brass** (`#9A7B3F`) is a rare hardware accent (the cursor slide, warning admonitions). - Tokens in `tokens/colors.css`; always reference the **semantic aliases** (`--surface-card`, `--text-body`, `--accent`, `--status-*`) rather than the raw ramp. ### Type Two voices — minimal, like the product (see `tokens/typography.css`): - **Saira Condensed** — **THE primary face**, used everywhere: display headlines, headings, UI, buttons, tables, body, long-form prose, eyebrows, and scale numerals. Tall and narrow with engraved-instrument character; it carries running body copy as well as display. Set in caps with `0.14em` tracking for labels. The `--font-display`, `--font-sans`, and `--font-serif` tokens all alias the primary face, so role tokens and existing components keep working. - **IBM Plex Mono** — code, terminals, the CLI, tags, tabular numerals — the machine voice. - Scale is a 1.250 major third rooted at 16px (`--text-xs … --text-5xl`). ### Backgrounds & texture - Flat eggshell paper — **no photographic backgrounds, no gradients as fields, no glassmorphism.** The one recurring graphic device is the **engraved tick rule** (`--tick-gradient`, `.panto-tick-rule`) — the **standard separator between sections**: short ticks every `--tick-pitch` (8px) with **every 5th tick at double height**, all centered on a common axis. The homepage hero also carries a slide-rule **ruler strip**: a literal printed scale. - The terminal is the **only** dark surface in the system — the one place ink becomes a background. ### Shape, borders, radius - **Machined, minimal corners.** `--radius-xs:2px` (inputs), `sm:3px` (buttons/badges), `md:5px` (cards), `lg:8px` (dialogs). `pill` is reserved for tags and the switch, used deliberately. - **Hairline rules** (`--border-hairline`) divide; **engraved top rules** (a thick ink or red bar on a `ruled` Card) mark importance. Borders are warm paper/ink tones, never cool gray. ### Shadow - Warm, low, **ink-tinted** (never neutral or blue): `--shadow-xs … --shadow-lg`, plus `--shadow-inset` for sunken fields. Like an object resting on a drafting table. Cards sit on a shallow `sm`; they lift to `md` on hover. ### Cards - Raised eggshell (`--surface-card`, lighter than the page), hairline border, `--radius-md`, shallow shadow. `sunken` variant inverts to an inset secondary surface. `ruled` adds the engraved top scale-rule (ink, or red for `accent`). ### Motion - **Mechanical, precise, no bounce** — like a sliding cursor. `--ease-slide` / `--ease-out`; durations `120 / 200 / 320ms`. Tabs slide their red underline; switches glide; buttons press *down 1px* with the shadow collapsing. The terminal cursor blinks (respecting `prefers-reduced-motion`). No floaty fades, no spring overshoot. ### States - **Hover:** darker fill (primary → `ink-0`), or a paper-2 wash for low-emphasis controls; links shift red and underline. - **Press:** `translateY(1px)` with shadow removed. - **Focus:** a 2px **instrument-green** outline (`--focus-ring`) at 2px offset, or a green ring + tinted glow on inputs. - **Invalid:** instrument red border + red wash glow. - **Disabled:** ~45% opacity, no shadow, `not-allowed`. ### Layout - Reading column `--container-prose: 720px`; app/marketing `--container-wide: 1140px`; docs sidebar `264px`. Sticky header + sticky sidebar/TOC; content stays in a measured column. Generous vertical rhythm on the 4px grid. ### Transparency & blur - Used **once**: the sticky docs header is `color-mix` paper at ~88% with an 8px backdrop blur, so content scrolls under it. Otherwise surfaces are opaque. --- ## ICONOGRAPHY - **System set: [Lucide](https://lucide.dev)** — clean line icons, 2px stroke, 24px grid, rounded caps and joins. Their precision and uniform weight suit a drafting instrument. - **Substitution flag:** because this is greenfield with no supplied icon assets, Lucide is a *chosen* set, not a recreation of an existing one. The UI kits inline a curated subset of Lucide-derived paths in `Icons.jsx` (Lucide is ISC-licensed). If the project later ships its own icons, replace `Icons.jsx` and document here. - **Icons inherit `currentColor`** and ride the ink ramp; they pick up red/green only inside an accented context (feature tiles, active states). - **The logo mark is the one bespoke glyph** (`assets/logo-mark.svg`): a pantograph parallelogram linkage — anchored fulcrum, dashed scaling axis, **red pen tip**. `logo-mark-mono.svg` is the single-color variant. Arms inherit `currentColor`. - **No emoji.** No decorative illustration. No multi-color icons. Status uses the engraved `Badge`, not an icon. --- ## INDEX — what's in this system **Foundations / global CSS** - `styles.css` — entry point (consumers link this one file); `@import`s only. - `tokens/fonts.css` — webfonts (Google Fonts; see substitution note below). - `tokens/colors.css` · `tokens/typography.css` · `tokens/spacing.css` — the token ramps + semantic aliases. - `tokens/base.css` — base element styling + helpers (`.panto-prose`, `.panto-eyebrow`, `.panto-tick-rule`). **Specimen cards** (Design System tab) — in `guidelines/` - Colors: paper, ink, accents, status & surfaces. - Type: display, sans, prose, mono, scale, eyebrow. - Spacing: scale, radius, shadows, borders & ticks. - Brand: logo, logo variants, voice & tone. **Components** — in `components/` (React, reference tokens via CSS vars) - `core/` — **Button, IconButton, Badge, Tag, Card** - `forms/` — **Input, Select, Switch** - `navigation/` — **Tabs** (underline + pill) - `code/` — **CodeBlock, Terminal, Callout** Each directory has `.jsx` + `.d.ts` + `.prompt.md` and one `@dsCard` showcase HTML. **UI kits** — in `ui_kits/` - `docs/` — the **libpanto SDK reference site** (header, nav tree, language-switching reference page, TOC). - `home/` — the **pantograph project homepage** (hero + live terminal, install switcher, feature grid, footer). **Brand assets** — in `assets/` - `logo-mark.svg` (red pen tip) · `logo-mark-mono.svg` (single color). **Other** - `SKILL.md` — makes this folder usable as a downloadable Agent Skill. --- ## Font note — self-host when ready Both typefaces load from **Google Fonts** via `@import` in `tokens/fonts.css` (so the compiler reports **0 `@font-face` rules** — fonts come from Google's network CSS, not self-hosted binaries). The system deliberately runs on just two: **Saira Condensed** (the single primary face) and **IBM Plex Mono**. If you want self-hosted fonts (offline, no Google dependency) or have specific licensed faces in mind, send the font files and I'll wire real `@font-face` rules. The mono could become JetBrains Mono or Berkeley Mono; if Saira Condensed ever feels too narrow for long-form docs, a slightly wider engineering gothic is the natural fallback — but the brief is one primary face, used everywhere.