Grundtone Design Tokens

Web-only styling layer: SCSS utilities, CSS output, grid system, and mixins for the Grundtone design system.

React Native? Use @grundtone/core + @grundtone/react-native instead. This package is for web (Vue, Vite, or any project using SCSS/CSS).

Features

• 9-shade Color Palette: Each color family includes 9 carefully crafted shades (50-900)
• Semantic Color Mapping: Meaningful names like primary, success, error for design intent
• SASS Helper Functions: Powerful functions for color access and manipulation
• CSS Custom Properties: Automatic generation of CSS variables for runtime theming
• Accessibility First: WCAG AA compliant color combinations
• TypeScript Support: Full type definitions for all design tokens

Installation

# Already included in the monorepo
import '@grundtone/design-tokens';

Color System

Color Families

Each color family includes 9 shades following modern design system conventions:

• Gray (50-900): Neutral colors for text, backgrounds, and borders
• Blue (50-900): Primary brand colors
• Green (50-900): Success states and positive actions
• Red (50-900): Error states and destructive actions
• Yellow (50-900): Warning states and cautionary content
• Indigo (50-900): Alternative primary colors

Semantic Colors

Pre-defined semantic colors for common use cases:

• primary, primary-light, primary-dark
• secondary, secondary-light, secondary-dark
• success, success-light, success-dark
• warning, warning-light, warning-dark
• error, error-light, error-dark
• info, info-light, info-dark

Usage

SASS Functions

Basic Color Access

@use '@grundtone/design-tokens' as tokens;

.button {
  // Access specific color shades
  background-color: tokens.color('blue', 500); // #3b82f6
  border: 1px solid tokens.color('blue', 600); // #2563eb

  // Use semantic colors
  background-color: tokens.semantic('primary'); // #2563eb
  color: tokens.text('inverse'); // #ffffff
}

Color Variations

.button {
  // Create lighter variants (move up the scale)
  background-color: tokens.lighter('blue', 500, 2); // blue-300

  // Create darker variants (move down the scale)
  &:hover {
    background-color: tokens.darker('blue', 500, 1); // blue-600
  }

  // Alpha variants
  &.disabled {
    background-color: tokens.alpha('blue', 500, 0.5); // 50% opacity
  }
}

Surface and Text Colors

.card {
  background-color: tokens.surface('background'); // #ffffff
  color: tokens.text('primary'); // #171717
  border: 1px solid tokens.border('light'); // #e5e5e5
}

.alert {
  background-color: tokens.surface('surface-alt'); // #f5f5f5
  color: tokens.text('secondary'); // #404040
}

CSS Custom Properties

All colors are automatically available as CSS custom properties:

.component {
  /* Direct color palette access */
  background-color: var(--color-blue-500);
  border-color: var(--color-gray-300);

  /* Semantic colors */
  color: var(--semantic-primary);

  /* Surface colors */
  background: var(--surface-background);

  /* Text colors */
  color: var(--text-primary);

  /* Border colors */
  border-color: var(--border-medium);
}

Helper Functions for CSS Variables

.component {
  background-color: tokens.css-color('blue', 500); // var(--color-blue-500)
  color: tokens.css-semantic('primary'); // var(--semantic-primary)
  border-color: tokens.css-border('light'); // var(--border-light)
}

Utility Mixins

Color Schemes

.card {
  // Apply consistent color scheme
  @include tokens.color-scheme('surface', 'primary');

  // Add focus styles
  @include tokens.focus-styles('primary');
}

Interactive States

.button {
  // Hover state with different shade
  @include tokens.hover-color('blue', 500, 600);

  // Focus styles
  @include tokens.focus-styles('primary');
}

Advanced Usage

Custom Color Combinations

.custom-alert {
  // Combine different color functions
  background-color: tokens.lighter('red', 500, 4); // red-100
  color: tokens.darker('red', 500, 2); // red-700
  border: 1px solid tokens.color('red', 300);

  // Add subtle background with alpha
  &::before {
    background: tokens.alpha('red', 100, 0.5);
  }
}

Theme-aware Components

.theme-card {
  @include tokens.color-scheme('surface', 'primary');

  // Responsive to CSS custom property changes
  transition:
    background-color 0.2s ease,
    color 0.2s ease;

  &.emphasized {
    @include tokens.color-scheme('primary', 'white');
  }
}

Error Handling

All functions include comprehensive error handling:

// This will show a helpful error message
.invalid {
  color: tokens.color('invalid-family', 500);
  // Error: Color family "invalid-family" not found.
  // Available families: gray, blue, green, red, yellow, indigo
}

Available Functions

Color Access Functions

• color($family, $shade) - Get color from palette
• semantic($name) - Get semantic color
• surface($name) - Get surface color
• text($name) - Get text color
• border($name) - Get border color

Color Manipulation Functions

• lighter($family, $shade, $steps) - Get lighter shade
• darker($family, $shade, $steps) - Get darker shade
• alpha($family, $shade, $alpha) - Add transparency

CSS Variable Functions

• css-color($family, $shade) - CSS variable for color
• css-semantic($name) - CSS variable for semantic color
• css-surface($name) - CSS variable for surface color
• css-text($name) - CSS variable for text color
• css-border($name) - CSS variable for border color

Utility Mixins

• color-scheme($bg, $text, $border) - Apply color scheme
• hover-color($family, $base, $hover) - Hover state colors
• focus-styles($color) - Consistent focus styles

Color Reference

Gray Scale

• 50: #fafafa (lightest)
• 100: #f5f5f5
• 200: #e5e5e5
• 300: #d4d4d4
• 400: #a3a3a3
• 500: #737373 (middle)
• 600: #525252
• 700: #404040
• 800: #262626
• 900: #171717 (darkest)

Blue (Primary)

• 50: #eff6ff → 900: #1e3a8a

Green (Success)

• 50: #f0fdf4 → 900: #14532d

Red (Error)

• 50: #fef2f2 → 900: #7f1d1d

Yellow (Warning)

• 50: #fefce8 → 900: #78350f

Indigo (Alternative)

• 50: #eef2ff → 900: #312e81

Migration from Old System

Before (Old System)

.button {
  background-color: $color-blue-info; // Fixed color
  border: 1px solid $color-gray-400; // Limited palette
}

After (New System)

.button {
  background-color: tokens.semantic('primary'); // Semantic naming
  border: 1px solid tokens.border('medium'); // Systematic approach

  &:hover {
    background-color: tokens.darker('blue', 500, 1); // Easy variations
  }
}

Browser Support

• All modern browsers (Chrome 60+, Firefox 55+, Safari 11+)
• CSS Custom Properties with fallbacks
• No JavaScript runtime dependencies

Contributing

When adding new colors:

1. Follow the 9-shade naming convention (50-900)
2. Ensure WCAG AA compliance for text/background combinations
3. Add semantic aliases for common use cases
4. Update documentation
5. Add appropriate helper functions if needed

Documentation

Core Token Documentation

• Color System - Complete color palette with light-dark() support
• Semantic Colors - Intent-based color mapping (primary, success, error, etc.)
• Typography - Font families, sizes, weights, and line heights
• Spacing - 8px-based spacing scale with responsive support
• Breakpoints & Grid - Responsive breakpoints and 12-column grid
• Visual Effects - Shadows, border radius, and z-index layering

Advanced Features

• Mixins - SCSS mixins for typography, buttons, layout, and utilities
• Accessibility - WCAG 2.1 compliant color calculations and validation
• TypeScript API - Full type-safe access to tokens in TS/JS
• CSS Variables - Complete reference of all CSS custom properties
• Functions - Helper functions for color, spacing, and more

Quick Links

• Accessibility Functions
• SCSS Mixins
• TypeScript Exports

TypeScript/JavaScript Usage

Import and use design tokens directly in TypeScript/JavaScript:

import { colors, spacing, typography } from '@grundtone/design-tokens';

// Access color values
const primaryBlue = colors.primary[500]; // '#3b82f6'
const lightGray = colors.gray[100]; // '#f3f4f6'

// Use spacing
const cardPadding = spacing[4]; // '1rem'

// Typography
const baseFont = typography.fontFamily.sans; // ['Inter', 'system-ui', ...]
const fontSize = typography.fontSize.base; // '1rem'

See TypeScript API documentation for complete examples.

Accessibility Features

Built-in WCAG 2.1 accessibility functions:

@use '@grundtone/design-tokens/core/accessibility' as a11y;

// Calculate contrast ratios
$ratio: a11y.contrast-ratio(#333333, #ffffff); // 12.63:1

// Check WCAG compliance
$is-aa: a11y.is-wcag-aa-compliant(#767676, #ffffff); // true

// Automatically choose text color
.badge {
  background-color: $bg-color;
  color: a11y.auto-text-color($bg-color); // White or black
}

// Ensure minimum contrast
.text {
  color: a11y.ensure-contrast(
    #999999,
    // Desired color
    #ffffff,
    // Background
    4.5,
    // Min ratio (WCAG AA)
    'darker' // Adjustment direction
  );
}

See Accessibility documentation for complete reference.

Changelog

v1.0.0

• Initial release with modern SASS color system
• 9-shade palette for 6 color families
• Comprehensive SASS helper functions
• CSS custom property generation
• Semantic color mapping
• Full TypeScript support
• WCAG 2.1 accessibility functions
• SCSS mixins library
• CSS variables reference