Cathryn Lavery
ba3062c5ba
Why: the default skin was too warm/neutral and the pyramid + venn never quite read the way they should. Also prepping for public sharing, so the example diagrams needed to drop the littlemight-specific copy. Changes: - New five-color palette: jet-black ink, atomic-tangerine accent, white-smoke paper, blue-slate muted, silver hairlines. Replaces warm-stone + rust across every variant + dark-mode tokens. - Default background is clean paper; dot grid + framed container are now opt-in variants (uncomment in template to enable). - New consultant-special quadrant variant (example-quadrant-consultant.html) — 2×2 scenario matrix with named cells, double-ended axes, one focal quadrant; house skin, not a separate visual language. - Pyramid redrawn as a true triangular silhouette with shared edges on one slope (stacked polygons on a single triangle outline, no kinks). - Venn redesigned: dark-fill triple-intersection with white text, circle labels moved inside non-overlap lobes, pair-overlap labels removed, legend dropped. - Example content genericized (content site / product timeline / content platform instead of littlemight-branded copy). - Screenshots regenerated at 2× DPI; added quadrant-consultant.png (14th diagram in the gallery). - README: hero-first opener, preserved Why-I-built-it section, UTM tags on littlemight + bestself links, palette description updated.
108 lines
6.1 KiB
Markdown
108 lines
6.1 KiB
Markdown
# Style Guide
|
||
|
||
**The single source of truth for colors, typography, and tokens.** Every diagram draws from this — not from hex values inlined in other reference files. If you want to change the visual skin of Schematic, change this file.
|
||
|
||
Default skin is a cool editorial palette — white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted. It's designed to look good out of the box; swap these values (or run [`onboarding.md`](onboarding.md)) and every new diagram inherits the new skin without touching any type-specific logic.
|
||
|
||
To generate your own from a website URL, see [`onboarding.md`](onboarding.md).
|
||
|
||
---
|
||
|
||
## Tokens
|
||
|
||
### Semantic roles
|
||
|
||
Every token is referred to by **semantic role**, not by its hex value. Type references (`type-*.md`) and SKILL.md say `accent`, not `#f7591f`.
|
||
|
||
| Role | Purpose | Default (light) | Default (dark) |
|
||
|---|---|---|---|
|
||
| `paper` | Page background, default node fill | `#f5f5f5` (white-smoke) | `#2d3142` (jet-black) |
|
||
| `paper-2` | Diagram container bg, secondary fill | `#ececec` | `#393e53` |
|
||
| `ink` | Primary text, primary stroke | `#2d3142` (jet-black) | `#f5f5f5` (white-smoke) |
|
||
| `muted` | Secondary text, default arrow stroke | `#4f5d75` (blue-slate) | `#bfc0c0` (silver) |
|
||
| `soft` | Sublabels, boundary labels | `#7a8399` | `#8e98ac` |
|
||
| `rule` | Hairline borders | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
|
||
| `rule-solid` | Stronger borders, baselines | `#bfc0c0` (silver) | `rgba(191,192,192,0.25)` |
|
||
| `accent` | Focal / 1–2 max per diagram | `#eb6c36` (atomic-tangerine) | `#f08a59` |
|
||
| `accent-tint` | Fill for accent-bordered boxes | `rgba(235,108,54,0.08)` | `rgba(240,138,89,0.10)` |
|
||
| `link` | HTTP/API calls, external arrows | `#2e5aa8` | `#6a95d8` |
|
||
|
||
> **Brand palette source:** this skin maps to a five-color brand palette — `jet-black #2d3142`, `silver #bfc0c0`, `white-smoke #f5f5f5`, `atomic-tangerine #eb6c36`, `blue-slate #4f5d75`. The `soft`, `rule`, and `link` tokens are derived (lighter slate, ink-at-opacity, and a saturated variant in the blue-slate hue family) to cover roles the brand palette doesn't name directly.
|
||
|
||
> **Note:** The pre-baked example HTML files in `assets/` were built under an earlier skin. Regenerating them against the current `style-guide.md` is a v5.1 task. New diagrams the skill produces will use the tokens above.
|
||
|
||
### Inversion rule (light → dark)
|
||
|
||
Any `rgba(28,25,23, X)` in light becomes `rgba(250,247,242, X)` in dark. Same opacities, RGB flipped. The accent gets a slight hue-shift brighter to read on dark paper.
|
||
|
||
---
|
||
|
||
## Typography
|
||
|
||
| Role | Family | Size | Weight | Usage |
|
||
|---|---|---|---|---|
|
||
| `title` | Instrument Serif | 1.75rem | 400 | Page H1 |
|
||
| `node-name` | Geist (sans) | 12px | 600 | Human-readable labels |
|
||
| `sublabel` | Geist Mono | 9px | 400 | Port, protocol, URL, field type |
|
||
| `eyebrow` | Geist Mono | 7–8px | 500, tracked 0.18em, uppercase | Type tags, axis labels |
|
||
| `arrow-label` | Geist Mono | 8px | 400, tracked 0.06em | Arrow annotations |
|
||
| `callout` | Instrument Serif *italic* | 14px | 400 | Editorial asides only |
|
||
|
||
### Font stack
|
||
|
||
```html
|
||
<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
||
```
|
||
|
||
**Load-bearing rule:** Mono is for *technical* content (ports, commands, URLs, field types). Names go in Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts (see [primitive-annotation.md](primitive-annotation.md)). **Never JetBrains Mono** as a blanket "dev" font.
|
||
|
||
---
|
||
|
||
## Stroke, radius, spacing
|
||
|
||
| Token | Value | Use |
|
||
|---|---|---|
|
||
| `stroke-thin` | `0.8` | Tag-box outlines, leaf nodes |
|
||
| `stroke-default` | `1` | Most strokes |
|
||
| `stroke-strong` | `1.2` | Emphasis strokes |
|
||
| `radius-sm` | `4` | Small tags |
|
||
| `radius-md` | `6` | Node boxes |
|
||
| `radius-lg` | `8` | Containers, rings |
|
||
| `grid` | `4` | Every coord, size, and gap is divisible by 4 (hard rule) |
|
||
|
||
---
|
||
|
||
## Node type → treatment
|
||
|
||
Semantic role combinations — reference these by name in type specs.
|
||
|
||
| Type | Fill | Stroke |
|
||
|---|---|---|
|
||
| `focal` (1–2 max) | `accent-tint` | `accent` |
|
||
| `backend` | `#ffffff` (white) | `ink` |
|
||
| `store` | `ink @ 0.05` | `muted` |
|
||
| `external` | `ink @ 0.03` | `ink @ 0.30` |
|
||
| `input` | `muted @ 0.10` | `soft` |
|
||
| `optional` | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` |
|
||
| `security` | `accent @ 0.05` | `accent @ 0.50` dashed `4,4` |
|
||
|
||
---
|
||
|
||
## Customizing the skin
|
||
|
||
Three options:
|
||
|
||
1. **Run onboarding** — see [`onboarding.md`](onboarding.md). Drop a URL; the skill extracts the palette + fonts and rewrites this file.
|
||
2. **Edit by hand** — change the hex values in the tables above. Run the pre-output taste gate afterward to verify the accent still reads as "focal" against the new paper color.
|
||
3. **Brand handoff** — paste your existing design-token JSON into a new section here and map its tokens to the semantic roles above.
|
||
|
||
### Constraints (don't break these)
|
||
|
||
- **Contrast**: `ink` must hit WCAG AA on `paper`. `muted` must hit AA on `paper` for 11px+ text.
|
||
- **One accent**: pick one color for `accent`. Two accents erases the focal signal.
|
||
- **No rainbow palette**: if your brand ships 8 colors, pick 3 (paper, ink, accent). The rest become `muted` variants.
|
||
- **Serif + sans + mono**: three families, not more. If brand typography is all sans, keep Instrument Serif for `title` and `callout` anyway — the contrast is load-bearing.
|
||
- **Paper is warm-neutral, not pure white**: pure white turns the design sterile. Pick a cream, bone, or light grey with a hint of warmth.
|
||
- **Dot pattern is optional, not default**: the 22×22 dot pattern is an opt-in "dotted paper" variant (good for long-form editorial hero diagrams). The default background is a clean `paper` fill, no pattern. When the pattern is enabled, it should sit at ~10% opacity of `ink` on `paper` — visible but quiet.
|
||
- **Container is clean by default**: the diagram sits directly on the page paper, no secondary container background or border. A framed variant (`paper-2` bg + `rule` border + 8px radius + padding) is available as an opt-in for card-heavy layouts, but don't reach for it by default — the extra chrome fights the figure.
|