Design system v0.1

Design system for the Coalbird app.

A working system for the app: color roles, surface hierarchy, motion rules, mascot restraint, and proof-first product patterns we can actually build.

The bird earns the frame.
Principles

Useful, odd, and operational.

The brand can be funny, but the product surfaces should help teams scan failures, compare evidence, and decide what to fix next.

  1. Canary is a signal, not wallpaper.
  2. Moss carries pricing, conversion, passed proof, and healthy state.
  3. Soot is structural: type, borders, shadows, tool chrome.
  4. Frames are tools, reports, modals, or repeated items.
  5. Motion must explain proof, state, progress, or failure.
  6. The bird is a mascot or cameo, not the default hero payload.
Surface hierarchy

Every color earns its job.

Page field

Use Paper with wide breathing room.

Avoid Full-page yellow or black sections.

Tool surface

Use Paper 2, hard line, short shadow.

Avoid Cards inside cards or ornamental frames.

Conversion

Use Moss fills, moss outlines, clear action labels.

Avoid Every CTA shouting in canary.

Signal

Use Canary for active, selected, or lamp-lit moments.

Avoid Yellow section backgrounds by default.

Failure

Use Ember on the exact proof gap.

Avoid Painting whole layouts red or black.

Mascot

Use Small canonical Bird moments near proof or brand context.

Avoid Using the bird to solve weak product storytelling.

Foundations

Tokens with a job.

Canary

--canary

Signal only: primary CTA, active nav, selected proof, mascot body

Moss

--moss

Conversion and healthy states: recommended plan, passed proof, live runs

Ember

--ember

Failures and warnings: blocked traces, stopped states, beak and feet

Lamp

--lamp

Soft emphasis: lamp glow, uncertain proof, selected-but-unproven state

Soot

--soot

Structure: type, borders, shadows, tool chrome, not large wallpaper

Paper

--paper

Page field and quiet sections

Paper 2

--paper-2

Tools, reports, modals, and raised repeated items

Scale

Five radii, three weights, one shadow.

Every frame on the site is drawn from this set. If the value you want isn't here, the answer is almost always the nearest token — not a new one. These swatches render the live variables, so this page goes wrong the moment the tokens do.

Radius

Chips and stamps take xs. Controls take sm. Panels take md. Cards and modals take lg.

  • --r-xs 4px
  • --r-sm 10px
  • --r-md 14px
  • --r-lg 18px
  • --r-pill 999px
Border

Two weights carry every frame. The accent is the bar that marks a quote or a proof gap.

  • --bd 2px
  • --bd-thick 3px
  • --bd-accent 4px
Shadow

One offset at rest. Lift on hover, press on active. There is no third resting depth.

  • --shadow 4px 4px 0
  • --shadow-lift 6px 6px 0
  • --shadow-press 1px 1px 0
Motion

Motion proves state.

4-6s ease

Scan

A beam or sweep over the target being inspected.

120-220ms step

Trace reveal

Sequential log entries proving what happened.

1.6-2.8s

State pulse

Live dot, selected variant, or active proof state.

2.4-5.6s

Mascot idle

Subtle bob, blink, wing, or lamp pulse only.

Components

Small pieces, clear roles.

Buttons
Primary Start trial
Secondary Read report
Small Replay
Status chips
Passed Needs proof Blocked Queued
Mascot rules
Mark
Positive
Failure
App mockup 01

Agent operations dashboard.

Coalbird Ops Weekly agent runs
Missions Findings Fixes
Trials started 14
Stores watched 100
Agent stalls 27
Fixes proven 8
Mission queue
Northstar Running Find black trail shoe in EU 44
Running
House & Table Add nonstick pan and verify returns
Needs proof
Everyday Skin Compare bundles, choose fragrance-free
Blocked
Selected run

Variant selected, maybe.

The agent cannot prove the size state changed, so it stops before adding the item to cart. The app should show the exact proof gap and the smallest next fix.

Proof confidence
Open trace
App mockup 02

Evidence-first report page.

Blocked

Size selector has no verifiable state.

Agent stopped at step 6 before cart.

  1. 01 open category page
  2. 02 dismiss country picker
  3. 03 select size EU 44
  4. 04 check selected state -> unclear
  5. 05 retry selection
  6. 06 stop before cart
Mockup 03

AI CEO without a robot bird.

Board packet ready
Coalbird HQ

The AI CEO writes the memo. Coalbird remains Coalbird.

The joke lives in the board report format: minutes, votes, operating thesis, experiments, and proof gaps. The mascot does not need to become a different mascot.

  • Agents are doers, not visitors.
  • A cart badge is not a contract.
  • The modal economy is an infrastructure problem.
Subscribe to board reports