Cairn Design System

Stone and paper. Weight you can read. The connective tissue between past decisions, present code, and future intent, made visible.

This page is the canonical reference for Cairn's UI. Three files carry everything: fonts.css loads the type, tokens.css defines every color, size, and duration, components.css styles the surfaces. Every component here reads from tokens. No hardcoded hex values downstream.

Color

Warm stone, quiet ink, chain accents tuned to role (not brand). Every value is a token.

Typography

Source Serif 4 for sentences. IBM Plex Sans for UI. IBM Plex Mono for anything exact.

Spacing and radius

Spacing steps in a readable rhythm. Radii stay low: stone is eroded, not milled.

Motion

Stones settle. They do not bounce. Six durations, four easings, one idle animation (drift).

--dur-tick    120ms   near-instant response
--dur-quick   200ms   snappy state change
--dur-settle  320ms   default, stone finding its place
--dur-reveal  520ms   progressive disclosure
--dur-breathe 2400ms  drift node idle (only idle animation)
--dur-build   1800ms  map building sequence

--ease        cubic-bezier(0.2, 0.7, 0.2, 1)    generic
--ease-settle cubic-bezier(0.2, 0.85, 0.3, 1)   default, damped
--ease-stack  cubic-bezier(0.4, 0, 0.2, 1)      hover, focus, color
--ease-lift   cubic-bezier(0.3, 0, 0.1, 1)      pulling up
--ease-paper  cubic-bezier(0.25, 0.8, 0.25, 1)  map inertia, reveal

Buttons

Three tiers. One primary per view. Secondary as support. Ghost for navigation.

Pills and badges

Chain membership and state markers. Never decorative; every pill carries a load-bearing term.

Inputs and keys

Cairn is queried, not searched. Inputs read in mono by default.

Code blocks

Monospace as evidence. Paths, IDs, blueprints, contracts.

Inline cairn.blueprint or neighbourhood saas.api.auth stays flush with surrounding text.

# cairn.blueprint fragment
module saas.api.auth {
  contracts: [auth.contract]
  decisions: [dec.two-chain-authority]
  tags: [@auth, @api]
}

Artefact row

One list item for all six artefact types: contract, decision, research, source, todo, review.

Chain diagram

Provenance meets authority at the hinge (the decision). Six stones, two directions.

Stone node

Every node on the map. Four states: synced, ghost, drift, settled.

Principle cards

Six principles, each earned. Watermark numerals in ghost ink.

Emotional registers

Every interaction targets one register: arrival, clarity, reassurance, unease.

Stat grid

Tabular figures in serif; labels in mono caps.

Panel

Generic container; the base for principle cards, inspectors, and wells.

Topbar

Application chrome: brand, breadcrumb, command search, chain toggles.

Inspector panel

Right-side detail surface. 380px wide. Holds decisions, changes, and chain balance.

Command palette

Full-screen modal for querying. Cairn is queried, not browsed.

Changes drawer

Bottom-docked. In-flight / review / archived as horizontally scrolling cards.

Logo mark

Three stacked stones. Hovering tilts the top two. The cairn is the thing.

Glossary

Load-bearing vocabulary. Never paraphrase these in UI.

blueprint.blueprint

The declarative file describing what your system should be. Authored by hand; the single source of intent.

mapmap.md

The reconciled view of your system. Cairn produces it by comparing the blueprint to actual code and surfacing findings.

provenance chainadvisory

Evidence flowing in: source → research → decision. Informs; never binds.

authority chainenforced

Rules flowing out: decision → blueprint → contract → code. Binds at every gate.

hingespec §3.4

The decision. Obligations in both directions; where provenance meets authority.

interface hashidentity

A stable fingerprint of a contract's shape. When it moves, the map moves with it.

rationale tensionadvisory

A non-blocking finding. Something the provenance chain wants to flag. Never fails a gate.

interface contradictionblocking

A blocking finding. The authority chain disagrees with itself; commits are gated until resolved.

ghoststate

Declared in the blueprint but not yet reconciled to code. Drawn dashed, with hatched fill.

syncedstate

Declared and reconciled. The default, quiet state.

orphanedstate

Present in code but not in the blueprint. A module without a declaration.

driftstate, advisory

Code diverged from its declaration. The only node that breathes.

neighbourhoodquery primitive

The N-hop graph around a node. "Show neighbourhood" never becomes "show nearby".

reconcilerinterface

The pluggable thing that compares a blueprint against a reality layer. Code is the first reconciler; others follow.

artefactkernel primitive

A typed schema object: contract, decision, todo, research, review, source. Umbrella kept; direct types are the six.