🎨 OKLCH Spectrum Audit

Advanced OKLCH Color Palette Visualizer — Explore, convert and audit color scales with a pure-math engine. Export semantic CSS variables in HEX or OKLCH format.

---

✨ Features

• 🌈 OKLCH Standard — Full Tailwind v4 palette (22 families) in OKLCH color space
• 🔀 HEX Equivalent — Instant OKLCH→HEX conversion via a pure-math engine (no external libs)
• ✂️ Custom Selection — Cherry-pick color families and export as CSS :root variables
• 🎛️ Preset Mode — Define 6 base colors, generate full 11-shade scales using parametric curves
• 🖱️ Interactive Mode — Tweak any color via picker and see the scale regenerate in real time
• 📊 Luminance Audit — WCAG-compliant luminance gap analysis across the spectrum
• 📋 CSS Export — One-click copy of :root {} in HEX or OKLCH format
• 🏷️ Semantic Mapping — Rename families to semantic tokens (e.g. --color-brand-500)
• 🌗 4 Themes — Light, Dark, White, Black — all token-driven

---

🚀 Quick Start

Prerequisites: Node.js 18+

git clone https://github.com/vandre-sales/OKLCH-Spectrum-Audit.git
cd OKLCH-Spectrum-Audit
npm install
npm run dev

Open http://localhost:3000 in your browser.

---

📐 How It Works

flowchart LR
    subgraph INPUT["🎨 Input"]
        A1["Tailwind v4\nOKLCH tokens"]
        A2["Custom\nbase color"]
    end

    subgraph ENGINE["⚙️ Math Engine"]
        B1["Parse OKLCH\n→ OKLab → sRGB"]
        B2["Parametric curve\nshade generation"]
        B3["Gamut mapping\nbisection (10 iter)"]
    end

    subgraph OUTPUT["📦 Output"]
        C1["Color scale\n11 shades"]
        C2["CSS variables\nHEX or OKLCH"]
        C3["Luminance\naudit table"]
    end

    A1 --> B1
    A2 --> B2
    B1 --> B3
    B2 --> B3
    B3 --> C1 --> C2
    C1 --> C3

Loading

Color Math Pipeline

Step	Operation	Formula
1	OKLCH → OKLab	Polar to Cartesian: a = C·cos(h), b = C·sin(h)
2	OKLab → Linear sRGB	M2 matrix multiplication
3	Linear sRGB → sRGB	Gamma correction: 1.055·c^(1/2.4) − 0.055
4	sRGB → HEX	#RRGGBB byte encoding
5	Gamut mapping	Binary search bisection on chroma (C)

---

🏗️ Tech Stack

Technology	Version	Purpose
React	19	UI framework with hooks
TypeScript	5.8	Type safety
Vite	6	Build tool with HMR
Tailwind CSS	CDN	Utility-first styling

Zero external color libraries — OKLCH↔HEX math built from scratch.

---

📁 Project Structure

OKLCH-Spectrum-Audit/
├── index.html              # Entry point
├── index.tsx               # React DOM mount
├── App.tsx                 # App orchestrator — state, modes, theme
├── AppVersion.ts           # Version SSoT
├── package.json            # Dependencies & scripts
├── vite.config.ts          # Vite + React config
├── tsconfig.json           # TypeScript config
├── LICENSE                 # MIT
├── README.md               # This file
├── metadata.json           # Project metadata
├── lib/
│   ├── types.ts            # TypeScript contracts
│   ├── constants.ts        # Palette data + defaults
│   ├── colorConverter.ts   # OKLCH↔HEX math engine
│   ├── colorCurveEngine.ts # Parametric scale generator
│   ├── theme.ts            # Semantic token engine (4 modes)
│   ├── colors-primitive-tailwind.ts   # Tailwind v4 OKLCH tokens
│   ├── colors-primitive-custom.ts     # Custom brand tokens
│   └── colors-semantic-custom.ts      # Semantic token mappings
├── hooks/
│   └── usePaletteGenerator.ts  # Palette logic hook
└── components/
    ├── ColorRow.tsx            # Color family row organism
    ├── ColorSwatch.tsx         # Individual shade molecule
    ├── audit/
    │   └── AuditTable.tsx      # Luminance gap analysis table
    ├── layout/
    │   └── StickyToolbar.tsx   # Floating controls bar
    └── ui/
        ├── Button.tsx          # Semantic button atom
        ├── EmptyState.tsx      # Empty state molecule
        ├── Icon.tsx            # SVG icon registry
        ├── LayoutPrimitives.tsx # PageContainer, Grid, GlassPanel
        └── Typography.tsx      # Polymorphic text atom

---

📦 Scripts

Command	Description
npm run dev	Start dev server on port 3000
npm run build	Build for production (dist/)
npm run preview	Preview production build

---

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit PRs.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

MIT — Vandre Sales 2026

---

Built with ❤️ using React, Vite & TypeScript

⬆ Back to top