diff options
Diffstat (limited to '_ds/pantograph-design-system-56a1c74e-41c1-486b-ba3c-4eabdfacef31/readme.md')
| -rw-r--r-- | _ds/pantograph-design-system-56a1c74e-41c1-486b-ba3c-4eabdfacef31/readme.md | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/_ds/pantograph-design-system-56a1c74e-41c1-486b-ba3c-4eabdfacef31/readme.md b/_ds/pantograph-design-system-56a1c74e-41c1-486b-ba3c-4eabdfacef31/readme.md new file mode 100644 index 0000000..8ea0b0e --- /dev/null +++ b/_ds/pantograph-design-system-56a1c74e-41c1-486b-ba3c-4eabdfacef31/readme.md @@ -0,0 +1,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. |