Visual Design System

Visual Design Skill — Principled Design for the Web

This project's visual design is grounded in perceptual science, mathematical proportion, and composable spatial primitives. It produces work that is distinctive, fluid, and formally rigorous — not another Bootstrap clone. The six guides below encode the system; this skill teaches you how to use them.

Core stance: Design decisions are engineering problems — constrained, measurable, and composable. The best design systems are algebraic structures, not collections of components.

What Each Guide Does For You

Load the right guide for your task. Each one gives you a different superpower.

Document Selection by Task

The Seven Principles (from design.md)

Memorize these. They resolve almost every design trade-off.

The Layout Primitives (from layout.md)

Every layout is a composition of these. No bespoke CSS layouts — compose from primitives.

Composition example: A card = Box (padding) containing a Stack (vertical flow). A page header = Cover containing a Center containing a Stack. A navigation = Cluster inside a Box.

The Colour Architecture (from colour.md)

Three-Tier Tokens

Primitive:    --brand-700, --neutral-200, --books-500
                    ↓
Semantic:     --interactive-primary, --surface-secondary, --text-brand
                    ↓
Component:    --button-primary-bg (future layer)

Rule: Components reference semantic tokens, never primitives.

The Palette

• Brand browns: Hue ~50° (warm amber), 11 steps (950→50), OKLCH lightness 15→95
• Warm neutrals: Hue 55°, chroma 0.01, 11 steps — reads grey but carries warm undertone
• Per-site accents (5 steps each):
  • books.cnbb.pub → Ink blue, hue 255°
  • art.cnbb.pub → Sage green, hue 155°
  • cnbb.pub → Terracotta, hue 35°

Semantic Tokens

The Type System (from type.md)

Three Voices

The Scale

Perfect fourth (4:3 = 1.333). Fluid: tightens to major third (1.25) at 360px, opens to full 4:3 at 1440px.

Per-Site Axis Tuning

Same typefaces, different personality via axis settings:

Fluid Responsive System (from layout.md + type.md)

The Two Design Decisions

Everything derives from these:

• @min: 360px viewport, 16px base, ratio 1.200 (minor third)
• @max: 1440px viewport, 20px base, ratio 1.333 (perfect fourth)

Utopia Tokens

Type, space, and grid are one unified mathematical system. The base space token equals the base type size. Space pairs (e.g., --space-s-l) interpolate steeply for component padding.

/* Type scale */
--step-0: clamp(1rem, 0.9015rem + 0.4924vi, 1.3337rem);
--step-1: clamp(1.2rem, 1.0534rem + 0.7331vi, 1.7783rem);

/* Space scale (derived from type) */
--space-s: var(--step-0);
--space-m: clamp(1.5rem, 1.3523rem + 0.7385vi, 2.0006rem);

/* Space pairs (steeper interpolation) */
--space-s-l: clamp(1rem, 0.5038rem + 2.4808vi, 2.6674rem);

Zero Breakpoints

No media queries for layout. Primitives + fluid tokens handle all responsiveness. The test: if you removed every media query, would the layout still work?

Breaking Templates (from breaking-the-layout-monoculture.md)

Why It Matters

Web design has homogenised 30% over 16 years (CHI 2021). Users develop banner blindness to template patterns. The antidote is stronger principles, not weaker ones.

Seven Strategies

Wayfinding (Lynch's Five Elements)

When designing navigation-heavy pages, think in spatial terms:

• Paths: How users move through the site (navigation, links, scroll)
• Landmarks: Visually distinctive elements that orient (hero images, brand marks)
• Regions: Distinct areas with their own visual identity (colour-coded sections)
• Edges: Boundaries between regions (transitions, borders, whitespace shifts)
• Nodes: Decision points where paths converge (homepages, hub pages)

The Six Developer Design Mistakes (from foundations-of-design.md)

Check every design output against these. They account for the majority of the quality gap between developer-built and designer-built interfaces.

Workflows

Designing a New Page

1. Start with layout.md: Identify which primitives compose this page (Container → Stack → Sidebar → Grid, etc.)
2. Load colour.md: Map semantic tokens to surfaces, text, borders, interactive elements
3. Load type.md: Assign scale steps to headings, body, captions, metadata
4. Check against the six mistakes: Hierarchy? Consistent spacing? Constrained colour? Type scale? Task-driven? Button hierarchy?
5. Check against the seven principles: Every value from a scale? Semantic token names? Proximity encoding meaning? Constraint-based?

Reviewing Visual Quality

1. Squint test: Does hierarchy survive? Can you tell primary from secondary content?
2. Spacing audit: Is intra-group < inter-group everywhere? Any arbitrary pixel values?
3. Colour audit: Only semantic tokens? No raw primitives in components? Accessible contrast?
4. Type audit: Every size from --step-*? Correct typeface per role? Fluid via clamp()?
5. Breakpoint test: Remove all media queries mentally — does it still work?
6. Template test: Does this page look like it could have come from a generic template? If yes, load breaking-the-layout-monoculture.md.

Making a Page Distinctive

1. Load breaking-the-layout-monoculture.md first
2. Choose 2-3 strategies from the seven (spatial zoning + editorial pacing + scroll-driven reveal, for example)
3. Apply wayfinding thinking: What are the landmarks? The regions? The paths?
4. Use asymmetry: 2fr 5fr 3fr instead of 1fr 1fr 1fr. Tschichold, not Bootstrap.
5. Verify it's still principled: Distinctive ≠ arbitrary. Every choice should trace back to a principle.

Quick Reference: CSS Patterns

Fluid Type Step

h2 { font-size: var(--step-3); }

Fluid Spacing

.section + .section { margin-block-start: var(--space-l-xl); }
.card { padding: var(--space-s-m); }

Stack Primitive

.stack { display: flex; flex-direction: column; gap: var(--space-s); }

Sidebar Primitive

.with-sidebar {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-l);
}
.with-sidebar > .sidebar { flex-basis: 20rem; flex-grow: 1; }
.with-sidebar > .main { flex-basis: 0; flex-grow: 999; min-inline-size: 55%; }

Intrinsic Grid (no column count)

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 250px), 1fr));
  gap: var(--space-s-m);
}

Measure Axiom

* { max-inline-size: 60ch; }
html, body, div, header, nav, main, footer { max-inline-size: none; }

Semantic Colour Usage

/* Correct: semantic token */
.button { background: var(--interactive-primary); }
.button:hover { background: var(--interactive-hover); }

/* Wrong: primitive token in component */
.button { background: var(--brand-700); }

Per-Site Theming via Accent Override

/* books.cnbb.pub */
:root { --accent-500: var(--books-500); --accent-700: var(--books-700); }

/* art.cnbb.pub */
:root { --accent-500: var(--art-500); --accent-700: var(--art-700); }

The Deeper Structure (for reasoning about trade-offs)

When principles seem to conflict, these foundational insights resolve them:

• Human perception is logarithmic (Weber-Fechner). Every quantitative scale must be geometric. This is not preference — it is neuroscience.
• Proximity is processed before all other cues (Gestalt). Spacing is not decoration; it is syntax.
• Regular patterns are metabolically cheap to process (neural efficiency). "It just looks off" = the viewer detected a mathematical irregularity they can't name.
• Musical intervals and type ratios use the same mathematics (rigorous, not metaphor). Perfect fourth in music = perfect fourth in type = 4:3 ratio.
• Colour space conversions are 3×3 matrix multiplications (linear algebra). OKLCH's perceptual uniformity is analogous to equal temperament in music — both uniformise inherently non-uniform perceptual spaces.
• "Composition over inheritance" applies to CSS exactly as to software (Every Layout explicitly argues this). Compose from primitives; don't build monolithic components.
• The token architecture IS the separation of concerns — primitives are type definitions, semantic tokens are interfaces, component tokens are implementations.