npm package: @lonelyguy-se1/palettier
Description: Automated color palette intelligence for developer workflows — scan, analyze, generate, optimize, and refactor color palettes from your codebase.
Latest version: 1.0.0

# Palettier

**Automated color palette intelligence for developer workflows.**

Scan codebases for colors, analyze usage patterns, generate or optimize palettes, improve accessibility, and safely refactor source files — all from the command line.

---

## First 60 Seconds

```bash
# Install globally
npm install -g @lonelyguy-se1/palettier

# Verify it works
palettier doctor

# Apply a theme to any project — one command
palettier apply cyberpunk -o my-theme.css

# Done! Link the CSS file in your HTML:
# <link rel="stylesheet" href="my-theme.css">
```

That's it. You now have a perceptually-balanced, WCAG-checked color palette as CSS custom properties.

---

## Features

- **Codebase Color Discovery** — Scan CSS, SCSS, Less, HTML, JSX/TSX, Vue, JSON, YAML, Python, Dart, Swift, Kotlin, C#, and more for hex, RGB, HSL, HWB, named colors, CSS variables, Tailwind tokens, and Sass/Less variables
- **Palette Generation** — Random intelligent palettes using OKLCH perceptual color space with harmony rules (complementary, analogous, triadic, etc.)
- **Theme-Based Generation** — Generate palettes from theme names like "cyberpunk", "pastel", "corporate", "nature", "minimal dark", or mood keywords
- **Accessibility Engine** — WCAG AA/AAA contrast checking, color blindness simulation (protanopia, deuteranopia, tritanopia, achromatopsia), readability scoring, auto-correction
- **Palette Optimization** — Fix contrast, resolve clashing colors, improve harmony while preserving visual identity
- **Safe Code Refactoring** — Dry-run previews, diff generation, backup creation, undo capability, file integrity verification
- **Multi-Format Export** — CSS custom properties, Tailwind config, W3C design tokens, terminal themes, Figma JSON, Markdown reports, YAML
- **Color Science** — OKLCH/LAB perceptual spaces, ΔE 2000 perceptual difference, gamut clamping, proper interpolation

## Installation

```bash
npm install -g @lonelyguy-se1/palettier
```

Or use locally:

```bash
npm install @lonelyguy-se1/palettier
npx palettier --help
```

## Quick Start

### Easy Mode — Apply a theme to any project

```bash
# Apply a theme and output a CSS file
palettier apply ocean -o palette.css

# Apply to a specific project directory
palettier apply cyberpunk --project-root ./my-website -o styles/theme.css

# Get Tailwind config instead
palettier apply nord --format tailwind -o tailwind.colors.js

# Pipe JSON for CI
palettier apply sunset --json | jq '.swatches[].hex'
```

### Scan & analyze your project

```bash
# Scan your project for colors
palettier scan ./my-project

# Generate a random palette
palettier generate random --count 8

# Generate a themed palette
palettier theme "cyberpunk"
palettier theme "dark minimal" --count 10

# Check accessibility
palettier a11y ./my-project --wcag AA --colorblind

# Optimize scanned colors
palettier optimize ./my-project --wcag AA --harmony

# Preview a palette with contrast heatmap
palettier preview ./my-project --heatmap --a11y

# Export to various formats
palettier export css --theme "ocean" -o palette.css
palettier export tailwind --theme "nord" -o tailwind.colors.js
palettier export design-tokens -i palette.json -o tokens.json

# Refactor colors in your codebase (dry run)
palettier refactor ./my-project --wcag AA

# Apply refactoring
palettier refactor ./my-project --apply

# Undo refactoring
palettier undo .palette-backups/2026-02-18T12-00-00 ./my-project

# Diagnostics
palettier doctor
```

## Commands

### `palettier doctor`

Print binary identity, version, active config, and system info for debugging.

### `palettier apply <theme>`

**Easy mode** — generate a theme and write it directly to a file.

| Option                  | Description                                       |
| ----------------------- | ------------------------------------------------- |
| `-o, --output <file>`   | Output file path (default: `palettier-theme.css`) |
| `-n, --count <n>`       | Number of colors (default: 8)                     |
| `--format <fmt>`        | Export format: css, tailwind, design-tokens, yaml |
| `--wcag <level>`        | WCAG level: AA or AAA (default: AA)               |
| `--seed <n>`            | Random seed for reproducibility                   |
| `--json`                | Output JSON to stdout instead of writing file     |
| `--project-root <path>` | Resolve output relative to this directory         |

### `palettier scan [dir]`

Scan a project directory for color usage patterns.

| Option                  | Description                             |
| ----------------------- | --------------------------------------- |
| `--json`                | Output raw JSON data                    |
| `--limit <n>`           | Maximum colors to display (default: 20) |
| `--project-root <path>` | Override project root directory         |

### `palettier generate [mode]`

Generate a random but aesthetically valid color palette.

| Option                | Description                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `-n, --count <n>`     | Number of colors (default: 6)                                                               |
| `--harmony <rule>`    | `complementary`, `analogous`, `split-complementary`, `triadic`, `tetradic`, `monochromatic` |
| `--seed <n>`          | Random seed for reproducibility                                                             |
| `--accessible`        | Ensure accessibility compliance (default: true)                                             |
| `--wcag <level>`      | WCAG level: AA or AAA (default: AA)                                                         |
| `--scale <hex>`       | Generate a 10-step shade scale from base color                                              |
| `--export <format>`   | Export format                                                                               |
| `-o, --output <file>` | Output file path                                                                            |
| `--json`              | Output palette as JSON                                                                      |

### `palettier theme [name]`

Generate a palette from a theme or mood description.

| Option                | Description                      |
| --------------------- | -------------------------------- |
| `--list`              | Show all available theme presets |
| `-n, --count <n>`     | Number of colors (default: 8)    |
| `--seed <n>`          | Random seed                      |
| `--wcag <level>`      | WCAG level (default: AA)         |
| `--export <format>`   | Export format                    |
| `-o, --output <file>` | Output file                      |
| `--json`              | Output palette as JSON           |

**Built-in themes:** cyberpunk, pastel, corporate, nature, minimal-dark, minimal-light, solarized, ocean, sunset, forest, retro, candy, monochrome, dracula, nord

### `palettier optimize [dir]`

Optimize colors in a project for accessibility and harmony.

| Option                  | Description                 |
| ----------------------- | --------------------------- |
| `--wcag <level>`        | WCAG level (default: AA)    |
| `--harmony`             | Improve color harmony       |
| `--fix-clashes`         | Fix clashing similar colors |
| `--json`                | Output raw JSON             |
| `--project-root <path>` | Override project root       |

### `palettier refactor [dir]`

Safely refactor colors in your codebase.

| Option                  | Description                                   |
| ----------------------- | --------------------------------------------- |
| `--apply`               | Apply changes (default is dry-run)            |
| `--no-backup`           | Skip backup creation                          |
| `--aggressiveness <n>`  | Replacement aggressiveness 0-1 (default: 0.5) |
| `--wcag <level>`        | Target WCAG level                             |
| `--palette <file>`      | Target palette JSON to refactor toward        |
| `--json`                | Output plan as JSON                           |
| `--project-root <path>` | Override project root                         |

### `palettier preview [source]`

Preview a palette in the terminal with color blocks.

| Option         | Description                       |
| -------------- | --------------------------------- |
| `--heatmap`    | Show contrast heatmap             |
| `--a11y`       | Show accessibility report         |
| `--colorblind` | Color blindness simulation report |
| `--json`       | Output as JSON                    |

### `palettier a11y [source]`

Run accessibility analysis on a project or palette.

| Option                  | Description                           |
| ----------------------- | ------------------------------------- |
| `--wcag <level>`        | WCAG level (default: AA)              |
| `--fix`                 | Auto-correct and output fixed palette |
| `--colorblind`          | Include color blindness report        |
| `--json`                | Output as JSON                        |
| `--project-root <path>` | Override project root                 |

### `palettier export <format>`

Export a palette to CSS, Tailwind, design tokens, etc.

| Option                | Description                               |
| --------------------- | ----------------------------------------- |
| `-i, --input <file>`  | Input palette JSON file                   |
| `-o, --output <file>` | Output file path                          |
| `--theme <name>`      | Generate from theme instead of input file |
| `-n, --count <n>`     | Colors when generating (default: 8)       |

**Formats:** `json`, `css`, `tailwind`, `design-tokens`, `terminal`, `markdown`, `figma`, `yaml`

### `palettier init [dir]`

Create a `.palette.config.json` configuration file.

| Option            | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `--preset <name>` | Config preset: `web-basic`, `react-app`, `design-system` |

### `palettier undo <backup-dir> [project-dir]`

Restore files from a refactoring backup.

## Run on an Existing Website

If you have an existing site and want to re-theme it quickly:

```bash
# 1. Scan to see what colors you already use
palettier scan ./my-site

# 2. Pick a theme and export CSS variables
palettier apply ocean -o my-site/palette.css

# 3. Add to your HTML
#    <link rel="stylesheet" href="palette.css">

# 4. Replace hardcoded colors with var(--color-primary), etc.
# Or let palettier do it:
palettier refactor ./my-site --palette palette.json --apply
```

## Troubleshooting

| Problem                                | Solution                                                                 |
| -------------------------------------- | ------------------------------------------------------------------------ |
| `palettier: command not found`         | Run `npm install -g @lonelyguy-se1/palettier` or use `npx palettier`     |
| Wrong binary is running                | Run `palettier doctor` to verify binary identity and version             |
| Tool scans its own files or lock files | Defaults now ignore `.git`, `node_modules`, lock files, build dirs, etc. |
| Exit code 1 but no error message       | Check stderr: `palettier scan . 2>&1`                                    |
| Windows paths look wrong               | Use `--project-root <path>` to set an absolute root                      |
| Too many colors in scan                | Use `--limit` or add patterns to `exclude` in config                     |

## Configuration

Create `.palette.config.json` in your project root (or run `palettier init`):

```json
{
  "accessibility": "AA",
  "colorSpace": "oklch",
  "replacementAggressiveness": 0.5,
  "include": ["**/*"],
  "exclude": ["node_modules", ".git", "dist", "build"],
  "createBackups": true,
  "parallelism": 4,
  "cacheDir": ".palette-cache",
  "themePresets": {}
}
```

Use a preset for common project types:

```bash
palettier init --preset web-basic
palettier init --preset react-app
palettier init --preset design-system
```

## Supported File Types

| Category       | Extensions                                   |
| -------------- | -------------------------------------------- |
| Web/CSS        | `.css`, `.scss`, `.sass`, `.less`, `.styl`   |
| HTML/Templates | `.html`, `.htm`, `.vue`, `.svelte`           |
| JavaScript     | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` |
| Data           | `.json`, `.jsonc`, `.json5`, `.yaml`, `.yml` |
| Design         | `.svg`, `.xml`, `.xaml`                      |
| Languages      | `.py`, `.dart`, `.kt`, `.swift`, `.cs`       |
| Docs           | `.md`, `.mdx`                                |

## Detected Color Formats

- **Hex:** `#RGB`, `#RRGGBB`, `#RGBA`, `#RRGGBBAA`
- **Functional:** `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`
- **Named:** All 148 CSS named colors
- **Variables:** CSS `var(--name)`, Sass `$name`, Less `@name`
- **Tokens:** Tailwind classes (`bg-blue-500`, `text-red-200`, etc.)
- **Design:** JSON hex values in theme configs

## Color Science

Palettier uses **OKLCH** (Oklab Lightness-Chroma-Hue) as its primary perceptual color space.

- Perceptually uniform lightness for consistent visual steps
- Proper hue interpolation without muddy transitions
- ΔE 2000 for precise color difference measurement
- Gamut clamping via binary search for sRGB-safe output
- Color blindness simulation using Brettel/Viénot matrices

## Architecture

```
src/
├── cli/           # CLI entry point and terminal formatting
│   ├── index.ts   # Command definitions (Commander.js)
│   └── formatting.ts  # ANSI color rendering
├── color/         # Color science fundamentals
│   ├── color-science.ts  # Conversions, contrast, ΔE, harmony
│   └── index.ts
├── parser/        # Codebase scanning engine
│   ├── patterns.ts      # Regex patterns for color detection
│   ├── parse-color.ts   # String → RGB parsing
│   ├── semantic-roles.ts # Role inference (background, accent, etc.)
│   ├── scanner.ts       # File discovery and scanning
│   └── index.ts
├── palette/       # Palette generation engine
│   ├── generator.ts     # Random, theme, and optimization
│   ├── theme-presets.ts  # Built-in theme definitions
│   └── index.ts
├── accessibility/ # Accessibility analysis
│   └── index.ts   # Contrast, color blindness, readability
├── refactor/      # Code refactoring engine
│   └── index.ts   # Replacement mapping, diff, apply, undo
├── export/        # Export to multiple formats
│   └── index.ts   # CSS, Tailwind, tokens, terminal, etc.
├── config/        # Configuration management
│   └── index.ts   # Load, merge, init config files
├── types.ts       # Shared type definitions
└── index.ts       # Public API barrel export
```

## Programmatic API

```typescript
import {
  scanProject,
  generateRandomPalette,
  generateThemePalette,
  optimizePalette,
  analyzeContrast,
  exportPalette,
  contrastRatio,
  rgbToOklch,
} from 'palettier';

// Scan a project
const result = scanProject('./my-project');

// Generate a palette
const palette = generateThemePalette('cyberpunk', { count: 8 });

// Export
const css = exportPalette(palette, 'css');
```

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Write tests for your changes
4. Ensure all tests pass: `npm test`
5. Submit a pull request

## License

MIT