pn-color-system

Color System

When to Use

• Establishing or auditing a project's color palette and token system.
• Implementing dark mode or theme switching.
• Ensuring WCAG contrast compliance.
• Replacing ad-hoc hex values with a structured token system.
• Reviewing or fixing color choices that look generic, washed-out, or inaccessible.

Context Gathering

Check .pncore-design.md in the project root first. Brand personality and visual ambition affect color choices. If missing, recommend running pn-setup (design context option).

Core Approach

OKLCH is the recommended color space for token systems. It is perceptually uniform — equal lightness steps look equal across hues. HSL is not perceptually uniform and produces colors that feel inconsistent.

Tint your neutrals. Pure gray has no personality. Add a tiny amount of your brand hue (chroma 0.005–0.01) to all neutrals for subconscious cohesion.

Never use pure black or pure white. Always tint. Real shadows and surfaces always have a color cast.

→ Full implementation details, code patterns, WCAG tables, and dark mode architecture: reference/color-and-contrast.md

Quick Reference

Color Token Structure

/* Primitives — define once, never use in components */
--blue-500: oklch(60% 0.15 250);
--blue-200: oklch(85% 0.08 250);

/* Semantics — what components reference */
:root {
  --color-primary:       var(--blue-500);
  --color-primary-muted: var(--blue-200);
  --color-text:          oklch(15% 0.01 250);
  --color-surface:       oklch(98% 0.005 250);
  --color-border:        oklch(88% 0.01 250);
}

/* Dark mode — only redefine semantics */
[data-theme="dark"] {
  --color-primary: oklch(68% 0.13 250);
  --color-text:    oklch(92% 0.01 250);
  --color-surface: oklch(14% 0.01 250);
  --color-border:  oklch(28% 0.02 250);
}

Tinted Neutrals

/* Brand hue drives the neutral tint */
--brand-hue: 250;  /* blue */

--gray-50:  oklch(98% 0.005 var(--brand-hue));
--gray-100: oklch(95% 0.008 var(--brand-hue));
--gray-400: oklch(65% 0.010 var(--brand-hue));
--gray-700: oklch(38% 0.012 var(--brand-hue));
--gray-900: oklch(18% 0.010 var(--brand-hue));