02 — Visual Doctrine
Surface Model
A surface is a named rendering context that defines an elevation level, a background color token, and a contrast profile. Components are always rendered within a surface — they do not exist in isolation from a rendering context. Surface inheritance is resolved at compile time: the compiler determines each component's surface context from the composition graph and resolves color tokens accordingly.
Named Surface Levels
| Surface | Elevation | Typical Background | Usage |
|---|---|---|---|
| surface.base | 0 | color.background.canvas | Page or application background |
| surface.raised | 1 | color.background.surface | Cards, panels, sections |
| surface.overlay | 2 | color.background.overlay | Modals, dialogs, drawers |
| surface.floating | 3 | color.background.elevated | Tooltips, popovers, dropdowns |
Surface and Color Token Resolution
Color tokens in IDL may declare surface-specific overrides. A border token that appears one shade lighter on surface.raised than on surface.base is expressed as a surface-conditional token mapping, not as two separate tokens. The compiler resolves the correct token value based on the surface context determined from the component's position in the slot graph.
Surface Declaration in Component Specs
Components that establish a new surface context — modals, cards, drawers — MUST declare the surface level they introduce. Components that render within an existing surface MUST NOT re-declare the surface context. This constraint prevents surface-level conflicts in deeply nested composition graphs and ensures that color token resolution is always deterministic.