Wax Design System
Relevant source files
The following files were used as context for generating this wiki page:
- apps/reef/app/wax/theme/theme.css.ts
- apps/reef/app/wax/theme/theme-dark.css.ts
- apps/reef/app/wax/theme/theme-light.css.ts
- apps/reef/app/tests/architecture.test.ts
- AGENTS.md
- apps/reef/app/wax/components/inputs/checkbox/checkbox.css.ts
- apps/reef/app/wax/components/code-block/code-block.css.ts
- apps/reef/app/wax/components/settings-layout/settings-layout.css.ts
Wax is the design system for the Coral project, specifically powering the Reef application. It provides reusable visual behaviors, styling primitives, and UI components. Wax ensures consistency across the interface by centralizing theme values, typography, and interactive controls, preventing the duplication of UI primitives in application-specific modules.
The system is built using vanilla-extract for type-safe CSS-in-JS and follows strict architectural boundaries to keep presentation logic independent from data-fetching and route-specific logic.
Sources: AGENTS.md:124-126, apps/reef/app/tests/architecture.test.ts:133-145
Architectural Boundaries
Wax operates as a durable boundary within the Reef application. Architecture tests enforce that all visible controls and text primitives reside within Wax. Application modules must compose Wax components rather than using native HTML tags or importing third-party UI libraries directly.
Strict Enforcement Rules
- Primitive Isolation: Native HTML tags (e.g.,
<a>,<button>,<h1>,<p>,<table>) are restricted to Wax components. App modules must use Wax Typography, Links, and Table components instead. - UI Library Proxy: Low-level UI libraries such as
@base-ui/,react-aria, andlucide-reactmust remain behind Wax. App modules extend Wax capabilities rather than creating parallel sets of controls. - Data Fetching: Presentation modules in Wax only render data provided via props; they never perform data fetching or import server-side modules.
Sources: apps/reef/app/tests/architecture.test.ts:108-132, apps/reef/app/tests/architecture.test.ts:246-261, apps/reef/app/tests/architecture.test.ts:276-285
Component Composition Flow
The diagram shows how application views compose Wax layouts and primitives, keeping data fetching isolated in the route layer.
Theme System
Wax utilizes a theme contract to maintain parity between light and dark modes. The system defines static utilities for colors like black and white, alongside a comprehensive theme contract created via vanilla-extract.
Theme Contract Structure
The contract organizes tokens into logical groups:
- Typography: Defined for various scales (Small, Medium, Large, XLarge) and styles (Body, Heading, Code, Button).
- Surface & Stroke: Manages backgrounds (main, card, floating) and borders (primary, secondary, control, focused).
- Interactive States: Provides tokens for buttons (primary, secondary, destructive, bare), switches, and segmented controls.
- Semantic Colors: Defines tokens for
success,error,warning, andinfostates, including their backgrounds and content colors.
Sources: apps/reef/app/wax/theme/theme.css.ts:24-184
Palette Mapping Examples
| Token Group | Light Mode Source | Dark Mode Source |
|---|---|---|
| Primary Button | CoralGreen['09'] | CoralGreen['09'] |
| Surface Main | Gray['03'] | Gray['02'] |
| Link Content | CoralGreen['11'] | CoralGreen['11'] |
| Error Content | RedAlpha['11'] | RedAlpha['10'] |
Sources: apps/reef/app/wax/theme/theme-light.css.ts:28-144, apps/reef/app/wax/theme/theme-dark.css.ts:28-140
Core Components and Layouts
Wax provides standardized layouts and components that dictate the spatial organization of the Reef UI.
Settings Layout
The settings-layout organizes resource-specific settings into a header and two-column grid.
- Columns: A main column (max 480px) for cards and an optional aside (max 320px) for facts.
- Responsive Behavior: On screens narrower than 1040px, the grid collapses to a single column.
- Removal Section: A specialized section at the bottom for destructive actions, separated by a secondary stroke.
Sources: apps/reef/app/wax/components/settings-layout/settings-layout.css.ts:7-60
Code Blocks
Wax includes specialized components for rendering code:
- Framed Code: Uses
theme.surface.onMainContentSubtlefor the background andtheme.stroke.secondaryfor the border. - Syntax Highlighting: Tokens are mapped for
comment,constant,function,keyword,string, andtype. - Annotated Code Block: Supports line highlighting via
borderLeftColormapped totheme.content.link.
Sources: apps/reef/app/wax/components/code-block/code-block.css.ts:14-88, apps/reef/app/wax/components/code-block/annotated-code-block.css.ts:16-24
Visual and Behavioral Standards
Wax enforces specific accessibility and behavioral requirements to ensure a high-quality user experience.
Accessibility (WCAG Compliance)
- Non-Color Meaning: Components must not convey meaning through color alone. For example, the
Checkboxuses a physical check or dash mark in the box so state changes are visible without color perception. - Contrast: Control outlines maintain at least a 3:1 contrast ratio against the page (WCAG 1.4.11).
- Color-Blind Support: Color changes are paired with icon shapes or text labels.
Sources: AGENTS.md:144-147, apps/reef/app/wax/components/inputs/checkbox/checkbox.css.ts:16-19
Transitions and Animations
Wax centralizes animation utilities to ensure consistent UI motion:
- Color/Fade: Standard 0.2s ease for background, color, box-shadow, and opacity transitions.
- Panel Reveal: A specific
cubic-bezier(0.22, 1, 0.36, 1)ease used for panel movements, with a 400ms open and 350ms close duration.
Sources: apps/reef/app/wax/theme/theme.css.ts:10-22
Style Layering
To prevent third-party styles from overriding system rules, Wax uses CSS layers. The system states a specific layer order in reset.css and layers.css.ts. Third-party stylesheets must arrive through an @import that names a specific layer to avoid being "unlayered," which would otherwise outrank Wax rules regardless of specificity.
Sources: apps/reef/app/tests/architecture.test.ts:312-326, apps/reef/app/tests/architecture.test.ts:342-353