Cairn

Why shadcn? shadcn copies component files directly into your repo — you own them and can edit them without fighting a library API. Cairn's app.css overrides shadcn's default palette by redefining --background, --primary, --border, and related variables with Cairn tokens. Every shadcn component picks up Cairn's stone neutrals, brand colour, and radius scale automatically — no per-component changes needed for base styling.

What Design.md is for. Design.md follows the google-labs-code/design.md specification — a structured format that lets coding agents reliably understand a design system. It combines YAML front-matter (machine-readable tokens) with Markdown prose (human-readable guidelines). Agents read the YAML for exact values and the prose for intent and constraints.

Why three layers? Most design systems have two — a palette and component values. The third layer (semantic tokens) is what enables multi-product theming and light/dark mode without touching component code. A button uses color-interactive, not a hex value. Swap the hex behind that token and every component updates automatically.

Why split surfaces? App UI and marketing have opposite jobs. The app user has already committed — the job is efficiency. The marketing visitor hasn't committed — the job is confidence and momentum. Trying to use one visual language for both creates a UI that is either too cold for marketing or too noisy for a task surface. The split is maintained in code via a .surface-marketing wrapper class and a --mkt- token namespace that never bleeds into app components.

Why Space Grotesk over Inter? Inter is neutral by design — it deliberately disappears. Space Grotesk has detectable character in specific letters: the double-storey a, the spurred G, the curved-tail t, and particularly strong numerals. At display sizes this distinction is what makes metric cards and hero headlines feel designed rather than default. It still works at 12px in dense UIs without losing legibility.

Why 600 weight only at 22px+? Space Grotesk 500 is optically heavier than Inter 500. Using 600 at body or label sizes produces a heavy, overworked feeling. 600 is reserved for display-scale headings where the extra weight reads as editorial rather than aggressive.

Why stone neutrals rather than grey? Pure grey (#f5f5f5) reads as "default browser" on screen. Stone has a barely-perceptible warm undertone that makes surfaces feel considered. The difference is subtle in isolation but clearly visible when grey and stone are placed side by side. It also prevents the app from feeling clinical — important for a product users spend hours in daily.

Why is brand colour restricted to interactive elements? Every use of brand colour in the app UI should answer "is this something I can interact with?" If the answer is no, the colour shouldn't be there. Decorative brand colour dilutes the interactive signal and makes the UI harder to scan.

Why borders instead of shadows? Box shadows create visual noise that competes with content. They also render inconsistently across displays and are invisible in dark mode unless carefully managed. A 0.5px border is precise, scales perfectly at any resolution, and works identically in light and dark mode. The one exception is marketing: a subtle brand-colour glow on CTA buttons is permitted because in that context the glow serves as a signal of interactivity on a dark surface, not a decorative effect.

Why such different motion rules per surface? In the app, motion that draws attention is a distraction — the user is trying to complete a task. In marketing, motion is part of the persuasion. A feature section that reveals on scroll feels alive; the same animation on a data table row would be maddening. The shared principle across both: motion should be purposeful, not ornamental. No continuous loops, no parallax, no motion for its own sake.

Why is "Sign in" a text link, not a secondary button? Giving sign-in a button border creates two competing CTAs next to the primary. Sign-in is for returning users who know what they want — it doesn't need to compete. The hierarchy should be: new user (primary CTA) is more prominent than returning user (text link). This also reduces visual noise in the nav.

Why no zebra stripes? Alternating row colours fragment attention horizontally — your eye reads across a stripe rather than scanning down a column. Hover-only highlighting keeps the table visually quiet and lets status badges and avatars carry their colour without competing with row backgrounds. When you need to draw attention to a row, the hover state is more precise and intentional than a permanent background tint on every other row.

Why not fill the featured card with brand colour? A brand-colour background on the featured card reads as "this is selected", not "this is recommended". It also forces white text on a coloured background, which reduces the legibility of the feature list — exactly the content that needs to be read carefully. The 1px border achieves the same differentiation without the legibility cost.

Why a sidebar instead of a top nav in the app? Top navs force all products to share the same horizontal space. As features are added, top nav items overflow into dropdowns or truncate. A sidebar scales vertically without compression and keeps all navigation visible. It also creates a clear spatial separation between navigation (left, dark) and content (right, light) that aids orientation in information-dense interfaces.

Why is the sidebar always dark, even in light mode? The sidebar's job is product context — which product, which section, who you are. Keeping it anchored to the dark treatment makes it consistent across all products regardless of their brand colour, and gives the product icon somewhere to land with real contrast. A light sidebar in a light-mode app would require careful work to avoid looking like a continuation of the content area.

Why design the handoff explicitly? Most SaaS products treat the marketing-to-app transition as a technical problem (routing). The user clicks "Start free trial", gets redirected, and lands in an empty dashboard. That jarring emptiness after a high-energy conversion moment is a missed opportunity. The three principles: (1) the dark sidebar appears immediately — it's the visual anchor that says "you're in the product". (2) First load shows an onboarding checklist, not an empty state. (3) Brand colour (#5B6EE1) is the continuous thread — it appears in the marketing CTA button, then immediately in the app sidebar and the first active checklist item.

Why not override semantic tokens directly per product? If products override --color-interactive directly, you lose the ability to control light/dark mode separately. The brand primitive tokens (--brand-500, etc.) sit between primitives and semantic tokens — semantic tokens reference brand tokens, brand tokens are set per product. This means a product theme file only needs to define 7 values, and the entire semantic layer — including dark mode variants — updates automatically.

Important caveat: not all brand colours work in all positions. A pale or low-saturation brand colour cannot be used as a nav background the same way deep indigo can. Each product's theme file must be authored with care — --brand-dark-nav in particular may need to be an independently chosen dark value rather than a mechanical darkening of the brand colour.

Key rules for dark mode colour shifts: Brand colour lightens (500 → 400) because saturated colours at 500 feel too heavy on dark backgrounds. The muted tint inverts — a light 50-stop tint on a dark surface reads as a light bleed, not a badge. Nav stays darkest even in dark mode — losing the hierarchy between nav and page background makes the sidebar disappear visually. Surface hierarchy inverts: in light mode, page is stone-50 and cards are white (lighter). In dark mode, page is ink-950 and cards are ink-900 (lighter). Same logic, opposite direction.

Don't mechanically darken the brand colour for --brand-dark-nav. Not all brand colours work in all positions. A pale or low-saturation brand colour cannot serve as a nav background the same way deep indigo can. --brand-dark-nav should be independently chosen — a dark surface that feels right as a sidebar, not a mathematical shade derived from the brand. Treat it as a dedicated dark-surface colour that happens to share the brand's hue family.