01

CANON: DESIGN

Design tokens from philosophy

Aesthetic coherence across the monorepo

02

The Principle

Tailwind for structure, Canon for aesthetics.

  • Tailwind handles composition and layout
  • Canon handles color, typography, motion
  • Coherence emerges through tokens, not through mixing utility classes

Design tokens are design philosophy made visible.

03

The Subtractive Triad

Every design decision passes through three filters:

  • DRY (Implementation) — Eliminate duplication in code
  • Rams (Artifact) — Eliminate excess in design
  • Heidegger (System) — Eliminate disconnection in meaning

Creation is the discipline of removing what obscures.

04
"Weniger, aber besser."
— Dieter Rams

Fewer things, but better things.
This is the essence of Canon design.

05

Token Categories

Design tokens organize into five categories:

  • Colors — Foreground, background, semantic, data
  • Typography — Display, heading, body, caption
  • Spacing — Golden ratio proportions
  • Radius — Border radius scale
  • Motion — Duration, easing, timing
06

Color Hierarchy

Background

pure
elevated
surface
subtle

Foreground

primary
secondary
tertiary
muted (AA)

Border

default
emphasis
strong

Live tokens — when Canon changes, this presentation updates automatically.

07

Semantic Colors

Beyond neutral grays, semantic colors carry meaning:

success (7.08:1)
error (4.97:1)
warning (6.31:1)
info (5.23:1)

All WCAG AA compliant on pure black. Each includes muted and border variants.

08

Spacing — Golden Ratio φ = 1.618

Spacing tokens follow the golden ratio, creating harmonic proportions:

  • --space-xs = 0.5rem
  • --space-sm = 1rem
  • --space-md = 1.618rem
  • --space-lg = 2.618rem
  • --space-xl = 4.236rem
  • --space-2xl = 6.854rem

Natural proportions create visual rhythm without thinking about it.

09 
TYPOGRAPHY SCALE

Display (Large)
├── --text-display-xl: clamp(3.5rem, 5vw + 2rem, 7rem)
└── --text-display: clamp(2.5rem, 4vw + 1.5rem, 5rem)

Heading
├── --text-h1: clamp(2rem, 3vw + 1rem, 3.5rem)
├── --text-h2: clamp(1.5rem, 2vw + 0.75rem, 2.25rem)
└── --text-h3: clamp(1.25rem, 1.5vw + 0.5rem, 1.75rem)

Body (Reading)
├── --text-body-lg: 1.125rem
├── --text-body: 1rem
└── --text-body-sm: 0.875rem

Small
└── --text-caption: 0.75rem
10

Motion — Purposeful, Not Decorative

Motion should reveal state changes, not seek attention:

  • --duration-micro = 200ms — Hover states, toggles
  • --duration-standard = 300ms — Page transitions, modals
  • --duration-complex = 500ms — Orchestrated sequences

--ease-standard: cubic-bezier(0.4, 0.0, 0.2, 1) for all animations.

11

Motion Anti-Patterns

What NOT to do:

  • ❌ Animation for decoration (bouncing icons, pulsing elements)
  • ❌ Duration > 500ms (feels sluggish)
  • ❌ Custom easing curves (breaks coherence)
  • ❌ Animating layout properties (use transform instead)
  • ❌ Auto-playing animations without user trigger

When in doubt, don't animate. The tool recedes when it's transparent.

12 
DECISION TREE

Is the value dynamic/computed at runtime?
├── Yes → Use inline style with CSS custom property
│         style="--value: {computed}"
│
└── No → Is it a layout/structure concern?
         ├── Yes → Use Tailwind utility
         │         class="flex items-center gap-4"
         │
         └── No → Is it a design/aesthetic concern?
                  ├── Yes → Use Canon token in scoped styles
                  │         color: var(--color-fg-primary)
                  │
                  └── No → Reconsider if needed at all
13

The Hybrid Pattern

Most components use all three approaches together:

  • Tailwind for composition: flex items-center gap-4 p-6
  • Canon for design: background: var(--color-bg-surface)
  • Inline styles for dynamic values: style="--delay: {index * 100}ms"

Structure, aesthetics, and dynamics in harmony.

14

Common Violations

What breaks Canon coherence:

  • ❌ Hardcoded colors: bg-white/10 instead of var(--color-bg-surface)
  • ❌ Inline styles for static values: style="border-radius: 12px"
  • ❌ Arbitrary typography: text-3xl instead of var(--text-h2)
  • ❌ Utility classes for motion: transition: all 0.2s instead of Canon tokens

Use the /audit-canon skill to detect violations automatically.

15

The Audit Skill: /audit-canon

Before merging, run the Canon audit:

  • /audit-canon packages/io/src/routes/experiment
  • Detects hardcoded colors, improper typography, missing tokens
  • Ensures "Tailwind for structure, Canon for aesthetics" principle
  • Returns structured feedback on violations

Design tokens are philosophy made executable.
The audit ensures philosophy persists through implementation.

← → navigate f fullscreen 📝 script