@hero-design/colors

Overview

@hero-design/colors provides color palettes, scale generation utilities, and color mixing functions for Hero Design components. This library ensures color consistency across the design system and is consumed by @hero-design/react (web), @hero-design/rn (mobile), and @hero-design/website (documentation).

Key features:

• Pre-built color palettes for web and mobile platforms
• Color scale generation with automatic tint and shade variants
• Color mixing utilities for creating custom color variants
• TypeScript support with full type definitions
• Support for dark mode palettes
• Product-specific palette customization

Installation

yarn add @hero-design/colors

Peer dependencies: None required.

Usage

Basic Example

import { defaultWebPalette } from '@hero-design/colors';

const Button = styled.button`
  background-color: ${defaultWebPalette.blue};
  color: ${defaultWebPalette.white};
  
  &:hover {
    background-color: ${defaultWebPalette.blueDark15};
  }
`;

API Reference

Available Palettes:

• defaultWebPalette - Default web color palette
• defaultMobilePalette - Default mobile color palette
• defaultMobileDarkPalette - Default mobile dark mode palette
• [Product]Palette - Product-specific palettes

Color Scale Utilities:

• colorScales - Pre-generated color scales with base, lighten, and darken variants
• mixColor(color) - Create a color mixer for custom color manipulation
  • mixer.tint(percentage) - Lighten a color by percentage
  • mixer.shade(percentage) - Darken a color by percentage

Color Scale Structure:

Each color scale provides:

• base - The base color value
• lighten{5-95} - 19 tint variants (in 5% increments)
• darken{5-95} - 19 shade variants (in 5% increments)

import { colorScales } from '@hero-design/colors';

const blueScale = colorScales.blue;
// Available properties:
// - blueScale.base
// - blueScale.lighten5, lighten10, ..., lighten95
// - blueScale.darken5, darken10, ..., darken95

Theming

The color palettes are designed to work seamlessly with Hero Design's theming system. Colors are organized into semantic categories:

• Brand Colors: Primary product colors (blue, green, etc.)
• Neutral Colors: Grey scale for text and backgrounds
• Functional Colors: Status colors (success, warning, error, info)
• Visualization Colors: Data visualization and chart colors

Theme Integration

import { defaultMobilePalette } from '@hero-design/colors';

const theme = {
  colors: {
    primary: defaultMobilePalette.blue,
    success: defaultMobilePalette.green,
    error: defaultMobilePalette.red,
  }
};

Design Tokens

Colors are provided as design tokens that can be used directly in styled components or theme configurations. Each palette includes semantic color names that map to specific use cases in the design system.

Examples

Using Colors in Components

import { defaultWebPalette } from '@hero-design/colors';

const Button = styled.button`
  background-color: ${defaultWebPalette.blue};
  color: ${defaultWebPalette.white};
  
  &:hover {
    background-color: ${defaultWebPalette.blueDark15};
  }
`;

Creating Custom Color Variants

import { mixColor } from '@hero-design/colors';

const brandColor = '#1dbeee';
const colorMixer = mixColor(brandColor);
const hoverColor = colorMixer.tint(20);
const activeColor = colorMixer.shade(20);

Advanced: Using Color Scales

import { colorScales } from '@hero-design/colors';

const Card = styled.div`
  background-color: ${colorScales.blue.lighten10};
  border: 1px solid ${colorScales.blue.base};
  
  &:hover {
    background-color: ${colorScales.blue.lighten20};
  }
`;

Contributing

Contributions to @hero-design/colors are welcome!

Development Setup

1. Install dependencies from the root of the monorepo:

corepack enable && yarn install

2. Build the package:

yarn turbo run build --filter=@hero-design/colors

Development Scripts

• yarn dev - Start Rollup in watch mode for development
• yarn build - Build the package (JavaScript and TypeScript declarations)
• yarn build:js - Build JavaScript bundles only
• yarn build:types - Generate TypeScript declaration files only
• yarn build:watch - Watch mode for both JS and types
• yarn lint - Run ESLint
• yarn type-check - Type check without emitting files

Guidelines

• Adding new colors: Add base colors to src/colorScales/index.ts following the existing naming conventions
• Creating new palettes: Create a new palette file in src/ and export it from src/index.ts
• Color naming: Use descriptive, definitive names (e.g., maasstrichtBlue, mellowApricot) rather than generic names
• Testing: Ensure colors meet accessibility contrast requirements

Previewing Changes

1. Start the website: yarn dev:website (see Website README for setup)
2. After making changes to colors, rebuild the package: yarn turbo run build --filter=@hero-design/colors
3. Refresh the website to see your changes in the color documentation:
   • Web: http://localhost:4000/web/Guidelines/Colors
   • Mobile: http://localhost:4000/mobile/Guidelines/Colors

For more information about contributing to Hero Design, please refer to the main repository documentation.