ColorSystemFoundation [principle] v1.0.0

Every Prime-guided project must use a three-layer color architecture — Primitive (OKLCH values), Semantic Scale (12-step functional scale), and Application Token (CSS custom properties) — and no layer may be skipped. Color choices must be rooted in perceptual color science to break AI default palette convergence.

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Applies To

• any frontend project with a design system
• AI-generated UI builds
• brand palette creation
• dark mode implementation

Counter Examples

• Using raw Tailwind color classes (bg-blue-500) directly in components — skips all three layers
• Defining colors only as hex values without OKLCH equivalents — breaks the primitive layer contract
• Using a single --primary CSS variable without a full scale — collapses semantic and token layers together

ColorSystemFoundation [principle] v1.0.0

Every Prime-guided project must use a three-layer color architecture — Primitive (OKLCH values), Semantic Scale (12-step functional scale), and Application Token (CSS custom properties) — and no layer may be skipped. Color choices must be rooted in perceptual color science to break AI default palette convergence.

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Applies To

• any frontend project with a design system
• AI-generated UI builds
• brand palette creation
• dark mode implementation

Counter Examples

• Using raw Tailwind color classes (bg-blue-500) directly in components — skips all three layers
• Defining colors only as hex values without OKLCH equivalents — breaks the primitive layer contract
• Using a single --primary CSS variable without a full scale — collapses semantic and token layers together

Examples

• A SaaS dashboard using Radix Colors as the semantic layer, OKLCH primitives for brand hue, and Tailwind v4 @theme tokens for components
• A portfolio site with a custom OKLCH ramp at the primitive layer, a hand-authored 12-step scale, and CSS custom properties consumed by every component

Relations

related: [@impeccable/template-oklch-palette, @community/anti-pattern-generic-saas-blue, @community/check-color-oklch-required, @community/anti-pattern-rainbow-explosion, @community/counter-example-tailwind-blue-500, @community/example-stripe-dashboard, @community/example-mercury-banking-dashboard, @community/rule-color-hue-selection, @community/rule-color-oklch-required]

Rationale

Left unconstrained, language-model agents converge on a narrow band of colors: Indigo-600/Violet-500 hero backgrounds, Blue-500 CTAs on white, Slate-700 body text, and identical Tailwind default tokens across every project. The three-layer architecture breaks that convergence by separating concerns: primitives own color math, semantic scales own functional meaning, and tokens own component coupling. Changing one layer does not require touching others.