npm package: @hero-design/colors
Description: `@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/
Latest version: 8.47.4-test-auto-workflow.3

# @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

```sh
yarn add @hero-design/colors
```

**Peer dependencies:** None required.

## Usage

### Basic Example

```typescript
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)

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```sh
corepack enable && yarn install
```

2. Build the package:

```sh
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](../../apps/website/README.md) 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.