Skip to main content

Source: ocean/docs/adr/050-design-system-cleanup-monochrome.md | ✏️ Edit on GitHub

ADR-050: Design System Cleanup and Monochrome Transition

Date: 2025-01-03

Status​

Accepted

Context​

The Ocean platform previously implemented a complex multi-theme design system with:

  • Design tokens stored in JSON files
  • Style Dictionary for CSS generation
  • Multiple color palettes (neutral, stone, zinc, gray, slate)
  • Dynamic theme switching via React Context
  • Contrast checking and validation tools
  • Pre-commit hooks for design validation
  • Build-time token generation

This system added significant complexity:

  • Multiple build steps required before development
  • Maintenance overhead for token files
  • Unnecessary abstraction for a single-product platform
  • Performance impact from dynamic theme switching
  • Complex tooling dependencies

The platform had already transitioned to a shadcn-inspired monochrome design system, but legacy infrastructure remained in the codebase.

Decision​

We will complete the transition to a simple monochrome design system by:

  1. Removing all design token infrastructure

    • Delete /design-tokens/ directory
    • Remove Style Dictionary configuration and dependency
    • Remove all token-related build scripts

  2. Simplifying the color system

    • Use direct CSS variables in /src/styles.css
    • OKLCH color space for all colors
    • Single grayscale palette with light/dark modes
    • No runtime theme switching

  3. Cleaning up tooling

    • Remove contrast checking tools (no longer needed for monochrome)
    • Remove token generation from pre-commit hooks
    • Remove all token-related scripts from package.json

  4. Maintaining shadcn compatibility

    • Keep CSS variable naming compatible with shadcn/ui
    • Preserve light/dark mode switching
    • Use standard Tailwind CSS classes

Consequences​

Positive​

  • Reduced complexity: No build-time token generation or complex tooling
  • Faster development: No pre-build steps, immediate development start
  • Smaller bundle: No theme switching logic or multiple color sets
  • Easier maintenance: Colors defined in one place, no abstraction layers
  • Better performance: No runtime theme calculations
  • Cleaner codebase: ~15 fewer files and tools to maintain

Negative​

  • Less flexibility: Adding new color themes would require more work
  • No design tokens: Loss of potential Figma integration (not currently used)
  • Manual updates: Color changes must be made directly in CSS

Neutral​

  • shadcn alignment: Maintains compatibility while simplifying implementation
  • Accessibility: Monochrome design inherently has good contrast
  • Developer experience: Simpler but less "enterprise" feel

Implementation​

The cleanup involved:

  1. Removed files:

    /design-tokens/
    /style-dictionary.config.js
    /tools/check-contrast.ts
    /tools/fix-contrast.ts
    /tools/build-tokens.js
    /tools/convert-palettes-to-tokens.js
    /tools/sync-design-tokens.js
    /tools/validate-tokens.js
    /tools/codemod-replace-raw-colors.ts
    /.github/workflows/contrast-check.yml

  2. Updated package.json:

    • Removed all tokens:* scripts
    • Removed predev and prebuild hooks
    • Removed design:codemod script
    • Removed style-dictionary dependency

  3. Updated code comments:

    • Fixed outdated references to useColorTheme hook
    • Updated to reference new CSS-based approach

Notes​

  • The monochrome design was chosen for its simplicity and professional appearance
  • This aligns with the "foundation-stage" nature of the project
  • Future theme requirements can be met with CSS custom properties
  • The cleanup reduces the codebase by approximately 2,000 lines of configuration and tooling

References​

  • ADR-041: Diverging from shadcn contrast for accessibility
  • Original design system implementation (removed in this cleanup)
  • shadcn/ui documentation: https://ui.shadcn.com/docs/theming