Skip to main content

Source: ocean/docs/adr/0002-token-based-design-system.md | ✏️ Edit on GitHub

ADR-0002: Implement Token-Based Design System for Styling

Date: 2025-07-26

Status​

Accepted

Context​

As a new project, we need a robust and scalable approach to manage our application's styling. We have adopted ShadCN/UI components, which are unstyled by default and designed to be themed using CSS variables, typically with Tailwind CSS. Initially, these CSS variables were hardcoded directly within src/styles.css.

To facilitate easier theming, maintain consistency, and prepare for potential future integration with design tools like Figma, a more centralized and automated system for managing design tokens (colors, spacing, radii, etc.) is required. This will allow us to use ShadCN/UI's defaults as a baseline and evolve our design system over time without directly modifying core component styles.

Decision​

We will implement a token-based design system using a custom JavaScript script to generate CSS variables from a JSON source of truth. This approach provides a lightweight yet effective solution for managing design tokens.

Specifically, the decision involves:

  1. Centralized Token Definition: All core design tokens (starting with colors and border radii) will be defined in a structured JSON file (design-tokens/tokens.json). This file will initially contain the default ShadCN/UI values.
  2. Automated CSS Variable Generation: A custom Node.js script (build-tokens.mjs) will read design-tokens/tokens.json and automatically generate a CSS file (src/styles/tokens.css) containing the corresponding CSS variables.
  3. Integration into Main Stylesheet: The generated src/styles/tokens.css will be imported into the main src/styles.css file, replacing any hardcoded CSS variable definitions.
  4. Simplified Workflow: Developers will update design tokens by modifying design-tokens/tokens.json and running a simple npm run build:tokens command.

Consequences​

Positive​

  • Centralized Source of Truth: All design tokens are managed from a single, structured JSON file, improving consistency and reducing errors.
  • Easier Theming and Customization: Modifying the application's visual theme (e.g., changing primary colors, border radii) becomes a simple update in the JSON file, followed by a script run.
  • Improved Consistency: Ensures that all components using the defined tokens adhere to the same visual standards.
  • Faster Design-to-Code Iteration: Changes made in the design token JSON can be quickly reflected in the application's UI.
  • Future-Proofing for Figma Integration: The structured JSON format is compatible with design tools like Figma (via plugins like Tokens Studio), allowing for seamless synchronization between design and development.
  • Leverages ShadCN/UI Baseline: Starts with a solid, accessible foundation provided by ShadCN/UI's default styling.

Negative​

  • Initial Setup Complexity: Requires setting up a new build step and understanding the token transformation process.
  • Learning Curve: Developers need to understand the new workflow for managing styles via tokens rather than direct CSS modifications.
  • Additional Build Step: Introduces a new step in the development workflow that must be run when tokens are updated.

Implementation Details​

  • design-tokens/tokens.json: Contains the JSON definition of design tokens (colors, radius, etc.).
  • build-tokens.mjs: A Node.js ES module script responsible for reading tokens.json and writing src/styles/tokens.css.
  • src/styles/tokens.css: The auto-generated CSS file containing --variable: value; declarations for all tokens.
  • src/styles.css: The main stylesheet now imports src/styles/tokens.css and no longer contains hardcoded token definitions.
  • package.json: Includes a "build:tokens": "node build-tokens.mjs" script to trigger the token generation.

Alternatives Considered​

  • Manual CSS Variable Management: Continuing to hardcode CSS variables directly in src/styles.css. Rejected due to lack of centralization, difficulty in managing large numbers of tokens, and poor scalability for theming.
  • Full-featured Design System Tools (e.g., Style Dictionary with complex configurations): While powerful, these tools can introduce significant complexity and a steeper learning curve. The chosen custom script provides a simpler, more tailored solution for a new project, avoiding unnecessary overhead while still achieving the core benefits of token management.

References​

Decision Makers​

  • Development Team
  • Technical Lead
  • None