Materials & surfaces
Five named surfaces. No color picker; every background in product is one of these tokens. If you need something else, we probably need a sixth.
Five tokens, one purpose each
Pick by role, not by color. Semantic tokens are what keep light and dark mode coherent — the names stay the same, the values flip.
The page itself. Product canvas. 99% of product.
The layer cards float on. Rails, list backgrounds, empty states.
Secondary containers: disabled fields, read-only rows, code blocks.
Primary CTA, nav pills, tooltips, dark hero bands.
Marketing warmth. The one non-neutral we allow as a background — used on landing pages and the onboarding flow, nowhere else.
Depth without shadows
We step one surface level for every layer of containment. Shadow is for lift; surface is for nesting. Don't use the two interchangeably.
Three principles
Never stack same-on-same
A default card on a default page needs a border or shadow to read. Use canvas underneath default, or step one level.
Inverse is a pattern, not a surface
Only for emphasis — primary CTA, dark hero, overlay. If you catch yourself filling half the screen with inverse, flip the model.
Cream is strictly brand
It lives in marketing and onboarding. It doesn't appear in product chrome, dashboards, or admin. Ever.