Design Tokens & Theming
Relevant source files
The following files were used as context for generating this wiki page:
Design tokens provide a centralized source of truth for visual styles across the web and mobile applications. The platform stores these tokens in the @dhc/tokens package, which exports colors, spacing, typography, and radii to maintain visual consistency throughout the monorepo.
The system ensures that both the Next.js web application and the Expo mobile application share the same design language. This architecture facilitates rapid UI updates by allowing developers to modify a single configuration file to propagate changes across all platforms.
Sources: README.md:23, packages/tokens/package.json:1-10
Architecture and Token Distribution
The system distributes design tokens through different mechanisms depending on the target environment. The @dhc/tokens package serves as the primary repository for all style constants.
Distribution Flow
The following diagram illustrates how tokens flow from the core package to the individual applications:
The design token system provides a unified interface for both CSS-based and object-based styling.
Sources: packages/tokens/src/index.ts:42-56, apps/web/app/layout.tsx:12-20, apps/mobile/src/theme.ts:1-5
Core Tokens Definitions
Tokens include specific values for colors, spacing, typography, and border radii.
Color Palette
The platform categorizes colors into functional groups: brand, neutral, severity, and status.
| Group | Key | Value | Purpose |
|---|---|---|---|
| Brand | 500 | #0f9b8e | Primary brand color |
| Neutral | 900 | #0f172a | Primary text color |
| Neutral | 0 | #ffffff | Background surfaces |
| Severity | block | #dc2626 | Critical safety warnings |
| Severity | warn | #d97706 | Intermediate warnings |
| Status | success | #16a34a | Successful operations |
Sources: packages/tokens/src/index.ts:5-18
Spacing and Geometry
Spacing values follow a numeric scale, and radii define the corner rounding for interface elements.
- Spacing Scale: Increments of 4px (e.g.,
1: 4,2: 8,4: 16). - Radii:
sm: 4,md: 8,lg: 12,full: 9999. - Accessibility: A
MIN_TOUCH_TARGETof 44px is enforced for mobile and touch interactions.
Sources: packages/tokens/src/index.ts:20-37
Web Implementation
The web application converts JavaScript tokens into CSS custom properties (variables) during the initial page render.
CSS Variable Injection
The toCssVariables function flattens the nested token object into a flat record of strings suitable for CSS usage. For example, colors.brand[500] becomes --color-brand-500.
// packages/tokens/src/index.ts
export function toCssVariables(): Record<string, string> {
// ... walk logic ...
walk('--color', colors, '');
walk('--space', spacing, 'px');
walk('--radius', radii, 'px');
walk('--font-size', fontSizes, 'px');
return vars;
}
Sources: packages/tokens/src/index.ts:42-56
The RootLayout in the web app injects these variables into the :root pseudo-class via an inline <style> tag.
// apps/web/app/layout.tsx
const rootCss = `:root{${Object.entries(toCssVariables())
.map(([name, value]) => `${name}:${value}`)
.join(';')}}`;
Sources: apps/web/app/layout.tsx:12-14
CSS Usage Patterns
Styles in globals.css consume these variables. This ensures the UI automatically updates when tokens change.
/* apps/web/app/globals.css */
body {
font-size: var(--font-size-md);
color: var(--color-neutral-900);
background: var(--color-neutral-50);
}
.card {
border-radius: var(--radius-lg);
padding: var(--space-6);
}
Sources: apps/web/app/globals.css:12-25
Mobile Implementation
The mobile application imports tokens directly into a theme.ts file. This file serves as the configuration for React Native styles and NativeWind.
- Platform Specifics: The
themeobject exports colors, fontSizes, radii, and spacing. - Layout Constants: The mobile theme defines
TWO_PANE_MIN_WIDTH = 768to determine when to switch to tablet-optimized layouts.
Sources: apps/mobile/src/theme.ts:1-8
Summary of Usage Requirements
Developers must adhere to these standards when implementing new UI components:
- Use Variables: Never hardcode HEX values or pixel sizes in
apps/web; always usevar(--color-...)orvar(--space-...). - Shared Tokens: New tokens must be added to
packages/tokens/src/index.tsto be available for both platforms. - Touch Targets: Interactive elements like buttons and inputs must maintain a minimum height of
44pxas defined byMIN_TOUCH_TARGET.
Sources: packages/tokens/src/index.ts:37, apps/web/app/globals.css:67-75