Skip to content

README.md

Latest commit

 

History

History
129 lines (84 loc) · 5.16 KB

README.md

File metadata and controls

129 lines (84 loc) · 5.16 KB
Raw

EDS Color Palette Generator

Internal tooling for building accessible colour themes and palettes for the Equinor Design System.

The project hosts two tools in one Next.js App Router app:

  • Theme Builder (/, the primary tool) — build accessible colour themes and palettes, preview them on example components, and check contrast. Palette state is shareable via the URL.
  • Colour Palette Generator (/old, archived) — the original Gaussian colour-scale generator. It creates harmonious colour scales using Gaussian distribution and the OKLCH colour space, ensuring consistent, accessible colours across different lightness levels. Still fully functional but no longer the default entry point.

The /themebuilder route now redirects to /.

Features

  • Gaussian-based chroma distribution: Colors maintain visual harmony using mathematical bell curves
  • OKLCH color space: Perceptually uniform color generation
  • Multiple color anchors: Support for interpolation between colors at specific steps for gradient-like scales
  • Accessibility-focused: Built-in contrast checking with APCA and WCAG methods
  • Light and dark mode support: Separate configurations for optimal contrast in each mode
  • Interactive configuration: Adjust lightness values and Gaussian parameters in real-time
  • Export/Import: Save and share color palette configurations
  • CLI tool: Generate color tokens from configuration files (supports both single value and multiple anchors)
  • About page: Comprehensive documentation with interactive demos explaining how the generator works

Getting Started

Web Interface

First, run the development server:

pnpm dev

Open http://localhost:3000 with your browser to see the Theme Builder (the primary tool).

The archived Gaussian colour-scale generator is available at http://localhost:3000/old. To learn how that generator works internally, visit the About page at http://localhost:3000/about.

CLI Tool

Generate color tokens from a configuration file:

generate-colors [configPath] [outputDir]

See src/cli/README.md for detailed CLI documentation and examples.

Example:

generate-colors examples/palette-config.json output/

This will generate color.tokens.light.json and color.tokens.dark.json files in the output directory.

How It Works

The generator uses a three-step process:

  1. Define lightness values: Each color step has predefined lightness values optimized for specific use cases (backgrounds, borders, text, etc.)
  2. Apply Gaussian distribution: Chroma (color intensity) varies using a bell curve, creating natural color progression
  3. Generate color scale: Colors are created in OKLCH space, maintaining hue while varying lightness and chroma

Single Value vs. Multiple Anchors

  • Single value: Provide one base color, and the generator applies Gaussian distribution across all steps
  • Multiple anchors: Define colors at specific steps (e.g., step 6 and step 9), and the generator interpolates smoothly between them in OKLCH space while still applying Gaussian chroma distribution

For detailed explanations and interactive demonstrations showing the difference, see the About page or read ABOUT_PAGE.md.

Key Concepts

  • Mean: The lightness value where chroma is at maximum (center of the bell curve)
  • Standard deviation: Controls how quickly chroma decreases away from the mean
  • Lightness: Predefined values for each step based on accessibility requirements
  • Chroma: Calculated as gaussian(lightness, mean, stdDev) × baseChroma

Configuration

Color palettes can be configured through:

  • Display options panel: Toggle contrast checking, lightness inputs, and Gaussian parameters
  • Quick actions menu: Import/export configurations, change color format
  • Individual color controls: Rename colors, adjust base colors, add or remove colors

Testing

Run unit tests with:

pnpm test

Run end-to-end tests:

pnpm test:e2e

Building

Build the CLI tool:

pnpm build:cli

This will compile the TypeScript CLI script into a distributable JavaScript file in the dist/ directory.

Documentation

Built With

Learn More