MOC — Surface
Color, shadow, border-radius, dark mode. The "background" choices that decide feel.
Raw markdown On GitHubreferences/surface/MOC-surface.md
Taught in
The decisions that look invisible but determine whether the UI feels considered or generated. Monochromatic with restraint usually beats colorful.
Nodes
-
color-monochromatic — Monochromatic with one or two accents beats a five-color palette. Why bright/purple gradients scream AI.
-
dark-mode — Never pure
#000. Use#18181bor#1a1a1awith 90–93% opacity white text. Why pure-black breaks. -
shadows-whisper — Shadows should whisper, not announce. The default
0 2px 8px rgba(0,0,0,0.1)is a tell. Concrete spec. -
border-radius — Uniform radius everywhere is lazy. Capsule buttons need full package. Nested-radius rules.
-
visual-imperfection — Asymmetry in marketing only. Optical over mathematical alignment. Subtle texture/noise. Imperfect shapes — perfect geometry feels cold.
-
contrast-and-color-scheme — APCA over WCAG 2 for contrast math.
<meta name="theme-color">+color-scheme: dark. Interactions raise contrast. Avoid gradient banding. -
color-scales-oklch — Author in OKLCH: one hue per ramp, L anchored and evenly spaced, chroma as a clamped curve, siblings at the same fraction of their own ceiling, dark mode by remapping steps, contrast repaired by moving L only.
-
depth-and-nesting — Inner radius = outer − padding; shadows elevate, borders separate; dark mode collapses shadows to a ring; 0.5px hairlines, pure black/white image outlines, mask fades, themes flip variables.
-
z-index-strategy — DOM order first, then one global file of sequential layers, local values inside
isolation: isolate; no magic numbers; what creates a stacking context or escapes a clip. -
color-token-tiers — Primitives by hue and step, semantics by role (the only tier components use), a full role inventory, one word per concept,
accentfor the brand soprimarystays free. -
palette-step-roles — One neutral, one accent, only the status ramps you render; every step has a role (Tailwind by lightness, Radix by role); fills on 600; status ≥ 15° from the accent; audit before restructuring.
-
gradient-interpolation —
in oklabby default,in oklchto stay vivid (shorter or longer hue), the grey dead zone, banding, text measured at its worst region. -
translucent-materials — Glass by hierarchy: heavier for structure, never light on light, scrim only for modal tasks, legible text on glass, solid fallbacks for reduced transparency.
-
oklch-gamut-and-migration — Chroma ceilings by hue and lightness, clamping that holds L and H, P3 behind a media query, the hex floor, what never to convert.
Cross-cluster
- See ai-default-tells in [[MOC-anti-patterns]] for surface tells (purple gradients, neon glows on dark mode).
mocsurfacecolorshadow