Foundations

Tokens

Complete CSS custom property reference for the Blanc design system. Tokens are defined in packages/ui/src/tokens/tokens.css and available globally. Reference Colors, Typography, and Spacing for those dedicated sections.

This page covers the remaining token groups: shadows, animation, and grid/layout tokens, plus the dark mode and forced section theme overrides.

Shadows

Seven levels. Use the lightest shadow that creates the necessary depth — avoid stacking shadows.

Token
Value
Usage
--shadow-xs
0 1px 2px 0 rgba(0,0,0,0.04)

Focused inputs, subtle lift

--shadow-sm
0 1px 2px 0 rgba(0,0,0,0.05)

Buttons, chips

--shadow-md
0 4px 6px -1px rgba(0,0,0,0.08)

Cards, dropdowns

--shadow-lg
0 10px 15px -3px rgba(0,0,0,0.08)

Modals, popovers

--shadow-xl
0 20px 25px -5px rgba(0,0,0,0.08)

Floating panels

--shadow-2xl
0 25px 50px -12px rgba(0,0,0,0.18)

Full-screen overlays

--shadow-inner
inset 0 2px 4px 0 rgba(0,0,0,0.06)

Inset inputs, pressed states

Duration

Four named durations. Always pair with an easing — never use linear for UI motion.

Token
Value
Usage
--duration-fast
150ms

Micro-interactions — hover states, toggles

--duration-normal
250ms

Component transitions — modals, drawers

--duration-slow
400ms

Page-level transitions

--duration-slower
600ms

Ambient / decorative motion

Easing

Four named curves. ease-out for entering, ease-in for exiting, ease-default for in-place transitions.

Token
Value
Usage
--ease-default
cubic-bezier(0.4, 0, 0.2, 1)

Standard — most transitions

--ease-in
cubic-bezier(0.4, 0, 1, 1)

Exiting elements

--ease-out
cubic-bezier(0, 0, 0.2, 1)

Entering elements

--ease-spring
cubic-bezier(0.34, 1.56, 0.64, 1)

Bouncy / playful

Grid & Layout

Container widths, gutters, and margins. These are set on :root and scale responsively via media queries.

Token
Value
Usage
--container-sm
640px

Small container width

--container-md
768px

Medium container width

--container-lg
1024px

Large container width

--container-xl
1280px

XL container width

--container-2xl
1440px

Max container width

--gutter
32px (responsive)

Active column gutter — scales up at each breakpoint

--margin
24px (responsive)

Page margin — space from viewport edge to grid

--gap-gallery
32px

Gap between gallery rows and cards

Dark Mode Strategy

Dark mode uses a CSS class strategy — add .dark to <html> to activate. Only the semantic role tokens flip — numeric scales stay constant. A synchronous <script> in layout.tsx reads localStorage before first paint to prevent FOUC.

Light

background#FFFFFF
surface#F7F6F3
border#DEDED9
accent#0057FF
foreground#0A0A0A

Dark

background#0D0D0B
surface#181816
border#252523
accent#4B8EFF
foreground#EEEEE8

Forced Section Themes

Individual page sections can be forced to light or dark regardless of the global toggle. Apply data-theme="dark" or data-theme="light" to any element — CSS variables cascade down to all children. Used by the Sanity page builder textSection and imageSection blocks.

data-theme="light"

Forces light palette. Overrides .dark on <html>.

data-theme="dark"

Forces dark palette regardless of global mode.