jb-website/docs/design-system/README.md
2026-06-01 19:35:56 +10:00

238 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Josh Bairstow — Brand System
A quiet-luxury personal brand system for **joshbairstow.com**. Warm browns and
ink; contemporary Nordic, "modern James Bond"; built on restraint, with a
*contained* street-art / calligraffiti "hand" that surfaces as an accent so
returning visitors notice craft the first visit never gave away.
> **The governing idea.** There is one base aesthetic and one accent, and they
> are not equal partners. **Base (~90% of the surface):** quiet luxury — muted
> warm-brown inks, generous negative space, chiaroscuro, precise typography,
> near-silent texture. **Accent (contained, occasional):** a gestural ink
> stroke / signature mark on dividers, hover states, transitions and the
> watermark only. It is the signature in the corner of the painting, never the
> painting.
>
> **Litmus test for every decision:** *Would a visitor barely register this on
> visit one, but feel a small delight noticing it on visit three?* Too loud on
> visit one → cut it. Invisible forever → not worth building.
---
## Sources
This system was built **from a written brand & styling brief**, not from an
existing codebase or Figma file. There is no upstream design source to link.
All palette hex, type pairings, marks, and templates in this folder are
proposals authored against the brief and are meant to be tuned with the owner.
---
## Context — what this brand is
Josh Bairstow is an individual: software engineer, runner/marathoner, ocean
person (freediving / surfing, Manly + WA roots), coffee, AFL — and, centrally
to the *aesthetic*, a follower of street art / calligraffiti (123Klan lineage),
manga and typography. **The interests inform flavour, not content.** Only the
art/design interest directly shapes the look (the accent layer + the signature
hand). Everything else stays as faint, optional nods on individual subdomain
pages later — never literal motifs in the core system.
**The site is a launchpad.** Home is a minimal hub that links out to a growing,
uneven set of subdomains:
| Subdomain | Purpose | Status |
|---|---|---|
| `blog` | Written content — home features its **latest post** as one line | live |
| `signage` | Chalk-on-easel signage side hustle (mechanical jotter) | side-project |
| `keycaps` | Custom keycaps for mechanical keyboards | side-project |
| `code` | Personal & public software experiments and utilities | live |
| `art` | Generative and physical art display | live |
| `social` | Links out — no presence yet | *coming online later* |
The navigation pattern must **read as an index** (not a button farm), tolerate a
growing/uneven number of items, and let a "not yet live" item exist without
looking broken.
---
## Content fundamentals — how copy is written
The voice is **editorial, sparse, and confident** — a gallery wall label, not a
marketing site. Restraint in words mirrors restraint in the visuals.
- **Person:** First person, understated ("I make things." / "Currently:
running, reading, shipping."). Never hype-y "we"-speak; this is one person.
- **Casing:** Sentence case for prose. **Small caps / uppercase tracking** for
eyebrows, labels and the subdomain index (e.g. `BLOG`, `CODE`, `ART`). The
wordmark is set in the display serif, title-styled.
- **Length:** Short. A latest-writing line is *one* line — title + a hairline
link, no panel, no thumbnail. Bait, not a billboard.
- **Punctuation:** The em-dash carries rhythm — used as a considered pause. True
small caps and old-style figures are deliberate "visit-three" details.
- **Emoji:** **None.** Not part of the brand. No exclamation-heavy energy.
- **Tone examples:**
- Eyebrow: `SELECTED WRITING`
- Latest line: `Notes on warm light and cold water — Mar 2026 →`
- Subdomain index item: `CODE — experiments & small tools`
- Coming-soon item: `SOCIAL — soon` (quiet, not "🚧 Under construction")
- Footer: `© Josh Bairstow — Sydney`
What to **avoid in copy:** exclamation marks, growth-marketing verbs ("Unlock",
"Supercharge"), feature lists, anything that shouts. If a line doesn't pass the
visit-one/visit-three test, cut it.
---
## Visual foundations
**Color.** Warm browns + cream, ink-forward, muted — tobacco, sepia, bone,
espresso. The whole system rides a **single warm tonal ramp** (`--bone-50`
`--ink-900`) plus one **muted ochre accent** used rarely. *Chiaroscuro is
achieved through value, not cool grey — shadows stay warm.* No more than **three
tones at once** on any view. Saturated color is essentially **banned** in
chrome/navigation; if color appears, it's a deliberate, rare event. See
`colors_and_type.css` for the full ramp + roles.
**Typography.** Editorial precision carries most of the "quiet luxury."
- **Display / name — Bodoni Moda.** High-contrast didone; fashion-editorial,
"modern Bond." Used large, sparing, confident. (Optical-size axis on; tight
negative tracking at display sizes.)
- **Body / UI — Hanken Grotesk.** Clean humanist grotesque, generous
line-height (1.62), comfortable measure (~66ch). Old-style figures enabled.
- **Mono — JetBrains Mono.** Reserved for the `code` subdomain nod / metadata.
- **The accent marks — `assets/accent-*.svg`.** Simple, crisp geometric glyphs
(ring-and-dots, a pipe cluster, a dot row, concentric rings) sprinkled with
**loose, non-rigid placement** throughout a view. Quiet but present — less
formal than the type, never a brush or a blob. Never a body typeface.
- **Visit-three type details:** true small caps (`--feat-smallcaps`), old-style
figures (`--feat-oldstyle`), refined wordmark kerning, em-dash rhythm.
**Default theme is the dark / ink ground** (`--ground-dark` #17130E) — deep,
warm, moody ("modern Bond"), light bone text. The bone ground is the alternate,
not the default. Same ramp, same rules either way.
**Backgrounds & texture (greebling).** Grounds are warm (ink or bone), never
flat. Fine, near-invisible surface detail rewards close/repeat inspection —
film grain plus **simple, crisp accent marks** (rings, dots, pipes) placed with
**loose, non-rigid positioning** throughout the view. **There is no
repeating/tiled pattern** — the marks are scattered and informal, not a
fashion-house tessellation, and not brushy blobs. **Hard guardrails
(enforced):** texture renders at **38% opacity**, watermarks at **410%**;
greebling sits **26% luminance** from its background; **no hard
edges** in the base layer — texture bleeds, it doesn't outline. The *delight*
version **lifts on interaction** (e.g. a pattern 4% → 8% on hover). Movement is
felt, not seen. Apply to: large empty grounds, dividers, card/panel
backgrounds, footer. **Keep greebling out of text areas** — legibility wins.
Assets: `texture-grain.svg`, `accent-ringdots.svg`, `accent-pipes.svg`,
`accent-dots.svg`, `accent-concentric.svg` (sprinkled, never tiled).
**Imagery.** Strong directional light, deep warm shadow — the black-and-white
architecture/fashion/automotive Instagram aesthetic, but warm-toned (sepia /
duotone toward espresso, not cold). Images are **clipped to a rounded,
asymmetric cut-out** (`--radius-cutout` — one big soft corner), **never a plain
rectangle**, and may carry the rings watermark per the opacity rules.
**Motion.** Slow, eased, short-travel — nothing bouncy or fast. Transitions
**200400ms** with generous easing (`--ease-out`). **One signature motion
moment max per view.** Examples: the greebling lift on hover, a hairline that
draws in along a divider, the ink stroke settling. Respect
`prefers-reduced-motion` — degrade to static (tokens collapse to 0ms).
**Interaction states.**
- *Hover:* texture/watermark lifts (4%→8%); a hairline draws/extends; link gets
a thin ochre tick or underline that grows from the start. No color floods.
- *Press:* a small value shift (text → `--ink-900`, surface → `--bone-200`); a
~1px nudge, never a bounce or scale-pop.
- *Focus:* warm 2px ochre outline at low opacity, offset — visible but quiet.
**Borders, radii, elevation.** Corners barely soften (`--radius-sm` 4px to
`--radius-lg` 14px); much of the chrome is **square-edged** with hairline rules.
Shadows are **warm** (espresso-tinted, low): `--shadow-1/2/3`. Cards are bone
panels with a hairline + a faint greeble, not heavy drop-shadow boxes. Avoid
rounded-corner + colored-left-border cards entirely.
**Layout.** Negative space is a feature. Editorial grid, generous margins, a
narrow measure for prose. The home page **fuses** its three jobs (hero +
latest-writing line + subdomain index) into one composition rather than stacking
three sections.
---
## Iconography
This brand is **near-iconless by design** — quiet luxury favors type and space
over UI furniture. The few marks that exist are **brand glyphs**, not a UI icon
set:
- **The brand marks** (`assets/mark-rings.svg`, `accent-ringdots.svg`,
`accent-pipes.svg`, `accent-dots.svg`, `accent-concentric.svg`) — authored
for this system; see § *Brand marks* below. None are initials; all are rings,
circles, dots and pipes.
- **Affordances** (links, "latest" line, nav) use **typographic** cues: a
trailing `→` (U+2192), a hairline underline that grows on hover, a thin ochre
tick. No filled UI icons, no icon font in the base brand.
- **Emoji / unicode:** emoji are **not used**. The em-dash (—), arrow (→), and
middot (·) are the only unicode "icons", used sparingly as typographic glue.
- **If a subdomain genuinely needs a UI icon set** (e.g. the `code`/tools pages),
use **Lucide** (https://lucide.dev) via CDN — 1.5px stroke, rounded caps,
set in `--fg-2` — as the closest match to the system's thin, warm,
unobtrusive line language. This is a documented substitution, not part of the
core brand. Keep icons out of the home page and marketing surfaces.
---
## Brand marks (not locked)
No initials. The watermark is a **rings-and-circles constellation** in the same
rounded language as the cut-out — circles of varied size at varied heights, not a
rigid row. The accents are **simple geometric marks** (rings, dots, pipes)
sprinkled with loose placement at a *visit-three* whisper. Three watermark
constellations are offered (not locked); the share template lets you switch live.
- **Orbit** (`mark-rings.svg`) — **primary watermark**. A larger open ring with
small circles orbiting at varied radii and heights (off the shared midline).
- **Drift** (`mark-rings-drift.svg`) / **Cascade** (`mark-rings-cascade.svg`) —
alternates: a loose ring-plus-satellites scatter, and graduated descending
circles anchored by a ring. All three are constellations, not a straight row.
- **Concentric** (`accent-concentric.svg`) — two concentric rings + a center dot.
- **Rounded cut-out** — imagery is clipped with `--radius-cutout`
(`6px 92px 6px 6px`: one big soft corner), never a plain rectangle.
- **Accent marks** — `accent-ringdots.svg` (· ○ ·), `accent-pipes.svg` (a small
pipe cluster), `accent-dots.svg` (a dot row). Crisp shapes, **loose/informal
placement**, kept at a true *visit-three* whisper (~1018% in a muted tone) so
they read as craft, not grid-fill.
---
## Index — what's in this folder
| Path | What it is |
|---|---|
| `colors_and_type.css` | **Start here.** Color ramp, semantic roles, type families + scale, greebling/motion/spacing/elevation tokens, semantic type classes. |
| `assets/mark-rings.svg` | **Primary** watermark — "Orbit" ring constellation. |
| `assets/mark-rings-drift.svg` | Alternate watermark — "Drift". |
| `assets/mark-rings-cascade.svg` | Alternate watermark — "Cascade". |
| `assets/accent-concentric.svg` | Concentric-rings accent / alternate watermark. |
| `assets/accent-ringdots.svg` | Accent mark — ring with flanking dots. |
| `assets/accent-pipes.svg` | Accent mark — pipe cluster. |
| `assets/accent-dots.svg` | Accent mark — dot row. |
| `assets/texture-grain.svg` | Warm film-grain greebling tile. |
| `preview/` | Design-system cards (color, type, texture, marks, components) shown in the Design System tab. |
| `ui_kits/home/` | UI kit — the home page: fused hero + latest-writing line + subdomain index, with greebling in situ. |
| `Posted Graphic.html` | Reusable share/post template — image clipped to the cut-out + watermark + type system. Drop a photo into the slot. (At project root so the image-slot's drop persists.) |
| `templates/image-slot.js` | Drag-and-drop image component used by the posted-graphic template. |
| `SKILL.md` | Agent-Skill manifest for using this system in Claude Code / as a downloadable skill. |
---
## Caveats
- **Fonts are loaded from Google Fonts CDN**, not bundled into `fonts/`. Bodoni
Moda + Hanken Grotesk + JetBrains Mono are all Google-hosted. If you need an
offline/self-hosted build, drop the `.woff2` files into `fonts/` and swap the
`@import` for `@font-face`. (No font substitution was needed — these are the
intended families, not stand-ins.)
- The **brand marks are authored proposals.** Per the brief, the watermark is
deliberately *not* locked — the rings glyph is my recommended primary; pick
it or the concentric variant (or commission a refined draw) with the owner.