Skip to content

tokens

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

tokens

README.md

@ode/tokens

ODE Design System - Unified Design Tokens

A comprehensive design token package for the Open Data Ensemble (ODE) ecosystem. This package provides a single source of truth for colors, typography, spacing, and all design values used across React Native, React Web, and all ODE applications.

What Are Design Tokens?

Design tokens are the smallest pieces of design information - like colors, spacing, and font sizes. Instead of hardcoding values like #4F7F4E or 16px throughout your code, you use tokens like color-brand-primary-500 or spacing-4.

Benefits:

  • Consistency - Same values everywhere
  • Easy Updates - Change once, update everywhere
  • Type Safety - TypeScript definitions included
  • Multi-Platform - Works for web, mobile, and more

Installation

pnpm install @ode/tokens

Quick Start

For React Web (CSS)

/* Import the CSS variables */
@import '@ode/tokens/dist/css/tokens.css';

/* Use tokens in your CSS */
.button {
  background-color: var(--color-brand-primary-500);
  padding: var(--spacing-3) var(--spacing-6);
  border-radius: var(--border-radius-md);
  color: var(--color-neutral-white);
}

For React Web (JavaScript/TypeScript)

import { colorBrandPrimary500, spacing3, spacing6 } from '@ode/tokens/dist/js/tokens';

const buttonStyle = {
  backgroundColor: colorBrandPrimary500,
  padding: `${spacing3} ${spacing6}`,
  borderRadius: '8px'
};

For React Native

import { tokens } from '@ode/tokens/dist/react-native/tokens';

const styles = StyleSheet.create({
  button: {
    backgroundColor: tokens.color.brand.primary[500], // #4F7F4E
    paddingVertical: tokens.spacing[3], // 12
    paddingHorizontal: tokens.spacing[6], // 24
    borderRadius: 8
  }
});

Static HTML / WebView (e.g. placeholder pages)

Static HTML files (such as a WebView placeholder) cannot import JavaScript modules at runtime. To keep them in sync with tokens:

  1. Build-time generation: A script reads @ode/tokens (e.g. dist/json/tokens.json) and injects token values into the HTML (e.g. a :root CSS block). When tokens change, re-run the script so the HTML is updated.
  2. Reference implementation: In this repo, the Formulus app’s placeholder page uses this approach:
    • Placeholder file: formulus/assets/webview/placeholder_app.html (contains a generated :root block between /* ODE_TOKENS_START */ and /* ODE_TOKENS_END */).
    • Generator script: formulus/scripts/generatePlaceholderTokens.js (reads tokens and rewrites that block).
    • Commands: From the Formulus app directory, run pnpm run generate:placeholder-tokens to regenerate; the Android build also runs this before copying webview assets.

See the script and placeholder file for the exact token paths and CSS variable names used.

Package Structure

packages/tokens/
├── src/tokens/           # Source token files (JSON)
│   ├── base/            # Foundation tokens
│   │   ├── colors.json
│   │   ├── typography.json
│   │   ├── spacing.json
│   │   ├── borders.json
│   │   ├── shadows.json
│   │   ├── motion.json
│   │   ├── z-index.json
│   │   └── opacity.json
│   ├── semantic/        # Meaningful tokens
│   │   └── colors.json  # Success, error, warning, info
│   ├── components/      # Component-specific tokens
│   │   └── icons.json
│   ├── layout/          # Layout tokens
│   │   ├── breakpoints.json
│   │   ├── containers.json
│   │   └── grid.json
│   └── accessibility/   # Accessibility tokens
│       ├── contrast.json
│       ├── focus.json
│       └── touch-targets.json
├── dist/                # Generated outputs (auto-created)
│   ├── css/            # CSS variables
│   ├── js/             # JavaScript/TypeScript
│   ├── json/           # Raw JSON
│   └── react-native/   # React Native format
├── config.json         # Style Dictionary configuration
└── package.json

Available Tokens

For a complete list of all available tokens with detailed specifications, see the Design Tokens Specification. Key sections:

Quick Reference:

  • Colors: Brand (primary green, secondary gold), neutral grays, semantic colors (success, error, warning, info)
  • Typography: Font families, sizes (12px-60px), weights, line heights, letter spacing
  • Spacing: 4px-based scale (0-96px)
  • Borders: Radius and width tokens
  • Shadows: Web CSS shadows + React Native shadow objects
  • Motion: Duration and easing functions
  • Layout: Breakpoints, containers, grid system
  • Accessibility: Contrast ratios, focus states, touch targets

Development

Building Tokens

cd packages/tokens
pnpm install
pnpm run build

This generates all output formats in the dist/ directory:

  • CSS variables (dist/css/tokens.css)
  • JavaScript/TypeScript (dist/js/tokens.js and tokens.d.ts)
  • JSON (dist/json/tokens.json)
  • React Native format (dist/react-native/tokens.js)

Adding New Tokens

For detailed instructions on adding new tokens, naming conventions, and best practices, see the Adding New Tokens section in the Contributing Guide.

Usage Examples

For comprehensive usage examples including CSS, React Web, React Native, and Material UI theming, see the Examples Guide. Key sections:

Design Principles

Our design tokens follow these principles:

  1. Accessibility First - All colors meet WCAG 2.1 AA contrast ratios
  2. Consistency - Unified visual language across all platforms
  3. Simplicity - Clear, predictable token names
  4. Scalability - Easy to extend and maintain

Token Categories Explained

Base Tokens

Foundation values that rarely change: colors, typography, spacing, borders, shadows, motion, z-index, opacity.

Semantic Tokens

Tokens with meaning: success (green), error (red), warning (orange), info (blue). These can change if the design system evolves.

Component Tokens

Values specific to components: icon sizes, avatar sizes, logo sizes.

Layout Tokens

Structure-related: breakpoints, container widths, grid system.

Accessibility Tokens

Inclusion-focused: contrast ratios, focus states, minimum touch target sizes.

Updating Tokens

For detailed instructions on updating tokens, see the Modifying Existing Tokens section in the Contributing Guide.

Contributing

We welcome contributions! For guidelines on adding new tokens, modifying existing ones, and following our conventions, see the Contributing Guide. Key sections:

License

MIT

Documentation

Related

Maintained by: ODE Design System Team
Version: 1.0.0