1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
# 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 `<Name>.jsx` + `<Name>.d.ts` + `<Name>.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.
|
