Chromatic Design System

A universal vibrational design system for Next.js applications based on Edwin Babbitt's Principles of Light and Color (1878) and Besant/Leadbeater's Thought-Forms (1901).

For AI agents building ANY application with enlightened design principles.

Core Philosophy
The Three Forces
Chromatic Color Science
The 20 Themes
Complete Palette
Thought-Form Design
Laws of Harmony
Agent Instructions
UX Principles
Quick Reference

Part 1: Core Philosophy

What This Is

This is knowledge for agents that build apps. Users request anything:

"Build me a todo app"
"Create a landing page for my bakery"
"Make a dashboard for sales data"

The agents generate the app using design principles derived from ancient wisdom - but the user never needs to know this. They just get beautiful, coherent, human-centered design.

The Three Laws of Thought-Forms

Every design element is a "thought-form" - a visible manifestation of intention. Three principles govern their creation:

Law	Determines	Application
Quality of thought	COLOR	User's emotional/intentional state → chromatic palette
Nature of thought	FORM	Type of action/content → shape language
Definiteness of thought	CLARITY	Confidence/certainty → outline sharpness, contrast

The Golden Rule

Build interfaces that support human sovereignty, not undermine it.

Every design decision should answer: Does this help the user accomplish their goal with clarity and ease? If not, simplify.

Part 2: The Three Forces

From Babbitt's spectrum analysis, all colors carry one of three fundamental forces:

Force	Hue Range	Quality	Physiological	Mental	Use In UI
THERMAL	Red (0-30°)	Heat, expansion, action	Blood-animating, warming	Passion, will, urgency	CTAs, alerts, energy
LUMINOUS	Yellow (40-60°)	Light, clarity, balance	Nerve-animating	Intellect, perception	Highlights, focus states
ELECTRICAL	Blue-Violet (200-280°)	Cold, contraction, calm	Nerve-soothing, cooling	Intuition, spirituality	Backgrounds, trust, calm
NEUTRAL	Green (90-150°)	Balance, synthesis	Harmonizing	Adaptability, growth	Success, nature, health

Part 3: Chromatic Color Science

CRITICAL: What "Chromatic" Actually Means

CHROMATIC ≠ Bright saturated colors

CHROMATIC = Gradation with hue-tinted grays (8-20% saturation)

The scientific color system uses subtle gray-tinted colors, not vivid saturated ones. This creates visual harmony and psychological calm.

// ❌ WRONG - This is NOT chromatic (too saturated)
const wrongBlue = "hsl(210, 80%, 50%)"

// ✅ CORRECT - This IS chromatic (gray-tinted)
const chromaticBlue = "hsl(210, 12%, 50%)"

Achromatic vs Chromatic

Type	Definition	Saturation	Use Case
Achromatic	No hue (black, white, gray)	0%	Neutral UI, text, borders
Chromatic Gray	Gray tinted with a hue	8-20%	Themed surfaces, accents

The Law of Chromatic Restraint

Never use pure, saturated colors. All colors should be "chromatic grays" - hues with 8-20% saturation.

Why? Pure saturated colors assault the nervous system. Chromatic grays are subtle, professional, and support focus rather than distract.

/* ❌ WRONG - Too saturated */
--primary: hsl(210, 100%, 50%);

/* ✅ RIGHT - Chromatic gray */
--primary: hsl(210, 15%, 45%);

Thought-Form Color Meanings

From Besant/Leadbeater's observations of actual thought emanations:

Color	Positive Expression	Shadow Expression
Rose/Pink	Affection, love, care	Selfish attachment
Crimson	Strong love, passion	Sensuality without love
Orange	Ambition, pride, achievement	Arrogance, conceit
Yellow	Intellect, understanding, wisdom	Cunning without wisdom
Green	Sympathy, adaptability, healing	Jealousy (brownish-green)
Blue	Devotion, loyalty, trust	Fanaticism (dark muddy blue)
Violet	Spiritual aspiration, nobility	Spiritual pride
Gray	Depression, fear	Melancholy
Brown	Selfishness, greed	Avarice
Black	Hatred, malice	—

Avoiding Shadow Colors

Certain color combinations create "muddy" thought-forms. Avoid:

Avoid	Why	Instead Use
Brownish-green	Jealousy, deceit	Pure sage green-gray
Muddy red-brown	Anger + selfishness	Clear rose or crimson
Gray-green	Depression + jealousy	Either pure gray or pure green
Murky orange	Pride corrupted by selfishness	Clear amber-gray

Part 4: The 20 Chromatic Themes

Pre-built themes agents should use. Each is a complete color system.

type ThemeName = 
  | 'trust'          // Blue-gray (210°) - Default, professional
  | 'calm'           // Indigo-gray (235°) - Relaxation, focus
  | 'energy'         // Orange-gray (28°) - Action, urgency
  | 'clarity'        // Yellow-gray (48°) - Information, search
  | 'focus'          // Yellow-gray (50°) - Deep work
  | 'growth'         // Green-gray (120°) - Progress, health
  | 'abundance'      // Emerald-gray (145°) - Success, money
  | 'harmony'        // Teal-gray (170°) - Balance, wellness
  | 'innovation'     // Cyan-gray (185°) - Tech, creativity
  | 'serenity'       // Azure-gray (200°) - Peace, meditation
  | 'spirit'         // Violet-gray (265°) - Premium, spiritual
  | 'wisdom'         // Purple-gray (280°) - Education, depth
  | 'affection'      // Rose-gray (340°) - Social, dating
  | 'passion'        // Crimson-gray (350°) - Creative, bold
  | 'urgency'        // Red-gray (8°) - Alerts, errors
  | 'warmth'         // Stone-gray (35°) - Community, comfort
  | 'earth'          // Stone-gray (35°) - Grounding, nature
  | 'optimism'       // Gold-gray (42°) - Positive, uplifting
  | 'transformation' // Magenta-gray (320°) - Change, creative
  | 'neutral'        // Achromatic (0°) - Universal, minimal

The Law of Intentional Color

Every color choice maps to a user intention or emotional state:

User Intention	Hue Range	Example Use
Trust, stability	200-220° (blue)	Finance apps, dashboards
Energy, action	20-40° (orange)	CTAs, notifications
Calm, rest	230-250° (indigo)	Meditation, reading apps
Growth, success	140-160° (green)	Health, productivity
Clarity, focus	45-55° (yellow)	Search, documentation
Transformation	310-330° (magenta)	Creative tools
Warmth, community	30-40° (stone)	Social apps

The Law of Visual Coherence

All elements in a view should share the same hue family. Don't mix blue buttons with orange headers with green text. Pick ONE dominant hue and derive everything from it.

Part 5: The Complete Chromatic Palette

HSL Values for All Chromatic Grays

export const CHROMATIC_PALETTE = {
  // ═══════════════════════════════════════════════════════════
  // ACHROMATIC (No hue - 0% saturation)
  // ═══════════════════════════════════════════════════════════
  achromatic: {
    50:  "hsl(0, 0%, 98%)",   // near-white
    100: "hsl(0, 0%, 96%)",
    200: "hsl(0, 0%, 90%)",
    300: "hsl(0, 0%, 80%)",
    400: "hsl(0, 0%, 65%)",
    500: "hsl(0, 0%, 50%)",   // normal gray - harmonizes with everything
    600: "hsl(0, 0%, 40%)",
    700: "hsl(0, 0%, 30%)",
    800: "hsl(0, 0%, 20%)",
    900: "hsl(0, 0%, 12%)",
    950: "hsl(0, 0%, 6%)",    // near-black
  },

  // ═══════════════════════════════════════════════════════════
  // THERMAL FORCE - Red/Orange (0-40°)
  // ═══════════════════════════════════════════════════════════
  
  // Red-Gray (Russet) - Urgency, passion, grounding
  redGray: {
    50:  "hsl(10, 12%, 97%)",
    100: "hsl(10, 12%, 93%)",
    200: "hsl(10, 12%, 85%)",
    300: "hsl(10, 14%, 72%)",
    400: "hsl(10, 14%, 58%)",
    500: "hsl(10, 16%, 48%)",  // primary
    600: "hsl(10, 16%, 40%)",
    700: "hsl(10, 18%, 32%)",
    800: "hsl(10, 18%, 24%)",
    900: "hsl(10, 20%, 16%)",
    950: "hsl(10, 20%, 10%)",
  },

  // Orange-Gray (Amber/Brown) - Energy, warmth, enthusiasm
  orangeGray: {
    50:  "hsl(30, 14%, 97%)",
    100: "hsl(30, 14%, 92%)",
    200: "hsl(30, 14%, 84%)",
    300: "hsl(30, 16%, 70%)",
    400: "hsl(30, 16%, 56%)",
    500: "hsl(30, 18%, 46%)",  // primary
    600: "hsl(30, 18%, 38%)",
    700: "hsl(30, 20%, 30%)",
    800: "hsl(30, 20%, 22%)",
    900: "hsl(30, 22%, 15%)",
    950: "hsl(30, 22%, 9%)",
  },

  // ═══════════════════════════════════════════════════════════
  // LUMINOUS FORCE - Yellow (45-60°)
  // ═══════════════════════════════════════════════════════════
  
  // Yellow-Gray (Citrine) - Clarity, intellect, optimism
  yellowGray: {
    50:  "hsl(50, 14%, 97%)",
    100: "hsl(50, 14%, 93%)",
    200: "hsl(50, 14%, 86%)",
    300: "hsl(50, 16%, 74%)",
    400: "hsl(50, 16%, 60%)",
    500: "hsl(50, 18%, 50%)",  // primary
    600: "hsl(50, 18%, 42%)",
    700: "hsl(50, 20%, 34%)",
    800: "hsl(50, 20%, 26%)",
    900: "hsl(50, 22%, 18%)",
    950: "hsl(50, 22%, 10%)",
  },

  // ═══════════════════════════════════════════════════════════
  // NEUTRAL FORCE - Green (90-160°)
  // ═══════════════════════════════════════════════════════════
  
  // Green-Gray (Sage) - Growth, balance, harmony
  greenGray: {
    50:  "hsl(120, 8%, 97%)",
    100: "hsl(120, 8%, 93%)",
    200: "hsl(120, 8%, 85%)",
    300: "hsl(120, 10%, 72%)",
    400: "hsl(120, 10%, 58%)",
    500: "hsl(120, 12%, 48%)",  // primary
    600: "hsl(120, 12%, 40%)",
    700: "hsl(120, 14%, 32%)",
    800: "hsl(120, 14%, 24%)",
    900: "hsl(120, 16%, 16%)",
    950: "hsl(120, 16%, 9%)",
  },

  // Teal-Gray - Balance, wellness, equilibrium
  tealGray: {
    50:  "hsl(170, 10%, 97%)",
    100: "hsl(170, 10%, 93%)",
    200: "hsl(170, 10%, 85%)",
    300: "hsl(170, 12%, 72%)",
    400: "hsl(170, 12%, 58%)",
    500: "hsl(170, 14%, 48%)",  // primary
    600: "hsl(170, 14%, 40%)",
    700: "hsl(170, 16%, 32%)",
    800: "hsl(170, 16%, 24%)",
    900: "hsl(170, 18%, 16%)",
    950: "hsl(170, 18%, 9%)",
  },

  // ═══════════════════════════════════════════════════════════
  // ELECTRICAL FORCE - Blue/Violet (200-280°)
  // ═══════════════════════════════════════════════════════════
  
  // Blue-Gray (Cool) - Trust, calm, professionalism
  blueGray: {
    50:  "hsl(210, 12%, 97%)",
    100: "hsl(210, 12%, 93%)",
    200: "hsl(210, 12%, 86%)",
    300: "hsl(210, 14%, 72%)",
    400: "hsl(210, 14%, 58%)",
    500: "hsl(210, 16%, 48%)",  // primary
    600: "hsl(210, 16%, 40%)",
    700: "hsl(210, 18%, 32%)",
    800: "hsl(210, 18%, 24%)",
    900: "hsl(210, 20%, 16%)",
    950: "hsl(210, 20%, 10%)",
  },

  // Indigo-Gray - Depth, meditation, intuition
  indigoGray: {
    50:  "hsl(240, 10%, 97%)",
    100: "hsl(240, 10%, 93%)",
    200: "hsl(240, 10%, 86%)",
    300: "hsl(240, 12%, 72%)",
    400: "hsl(240, 12%, 58%)",
    500: "hsl(240, 14%, 48%)",  // primary
    600: "hsl(240, 14%, 40%)",
    700: "hsl(240, 16%, 32%)",
    800: "hsl(240, 16%, 24%)",
    900: "hsl(240, 18%, 16%)",
    950: "hsl(240, 18%, 9%)",
  },

  // Violet-Gray - Spirit, creativity, transcendence
  violetGray: {
    50:  "hsl(270, 10%, 97%)",
    100: "hsl(270, 10%, 93%)",
    200: "hsl(270, 10%, 86%)",
    300: "hsl(270, 12%, 72%)",
    400: "hsl(270, 12%, 58%)",
    500: "hsl(270, 14%, 48%)",  // primary
    600: "hsl(270, 14%, 40%)",
    700: "hsl(270, 16%, 32%)",
    800: "hsl(270, 16%, 24%)",
    900: "hsl(270, 18%, 16%)",
    950: "hsl(270, 18%, 9%)",
  },

  // Rose-Gray - Affection, nurturing, care
  roseGray: {
    50:  "hsl(340, 10%, 97%)",
    100: "hsl(340, 10%, 93%)",
    200: "hsl(340, 10%, 86%)",
    300: "hsl(340, 12%, 72%)",
    400: "hsl(340, 12%, 58%)",
    500: "hsl(340, 14%, 48%)",  // primary
    600: "hsl(340, 14%, 40%)",
    700: "hsl(340, 16%, 32%)",
    800: "hsl(340, 16%, 24%)",
    900: "hsl(340, 18%, 16%)",
    950: "hsl(340, 18%, 9%)",
  },
}

Part 6: Thought-Form Design

Nature of Thought → Form

Thought Type	Form Quality	UI Translation
Directed intention	Pointed, projectile-like	Buttons, arrows, CTAs
Radiating energy	Star-like, outward	Icons, badges, notifications
Protective	Shell-like, enclosing	Cards, modals, containers
Intellectual	Crystalline, angular	Data tables, grids, charts
Aspirational	Upward, spire-like	Progress bars, growth indicators
Emotional	Cloud-like, soft	Backgrounds, gradients, blur

Definiteness → Clarity

Definiteness	Form Quality	UI Translation
Crystal clear	Sharp, well-defined	Solid borders, high contrast
Vague emotion	Cloud-like, undefined	Blur effects, soft shadows, gradients
Strong emotion	Dense, saturated core	Solid fills, high contrast
Weak/uncertain	Thin, fragmented	Dotted lines, low opacity, outlines

Border Radius Scale

export const FORM_RADII = {
  sharp: "0px",      // Definite, intellectual, precise
  subtle: "2px",     // Slightly softened, professional
  balanced: "6px",   // Balanced, approachable
  soft: "12px",      // Friendly, warm
  rounded: "20px",   // Nurturing, protective
  full: "9999px",    // Spiritual, ethereal
}

Clarity Scale

export const CLARITY_LEVELS = {
  definite: {
    borderWidth: "1px",
    borderOpacity: 1,
    shadowBlur: "0px",
    contrast: "high",
  },
  clear: {
    borderWidth: "1px",
    borderOpacity: 0.8,
    shadowBlur: "4px",
    contrast: "medium-high",
  },
  balanced: {
    borderWidth: "1px",
    borderOpacity: 0.6,
    shadowBlur: "8px",
    contrast: "medium",
  },
  soft: {
    borderWidth: "0px",
    borderOpacity: 0.4,
    shadowBlur: "16px",
    contrast: "low",
  },
  ethereal: {
    borderWidth: "0px",
    borderOpacity: 0.2,
    shadowBlur: "32px",
    contrast: "very-low",
  },
}

Part 7: Laws of Chromatic Harmony

The Gradation Law

"A beautiful Gradation of Chromatic Grays... are so exquisitely blended, like the gradations of nature, that it is impossible to perceive the degrees of progression."

Never make jarring leaps in lightness or saturation. Always use adjacent steps:

// ✅ CORRECT - Gradual progression
<div className="bg-blueGray-900 text-blueGray-100">
  <div className="bg-blueGray-800" /> {/* one step lighter */}
</div>

// ❌ WRONG - Jarring leap
<div className="bg-blueGray-900 text-blueGray-100">
  <div className="bg-blueGray-200" /> {/* too much contrast */}
</div>

The Harmony Law

Adjacent colors in your palette must share undertones:

// ✅ HARMONIOUS - Same hue family
primary: "blueGray"
accent: "indigoGray"  // adjacent on color wheel

// ❌ DISCORDANT - Clashing undertones
primary: "blueGray"
accent: "orangeGray"  // opposite, creates tension

The Normal Gray Principle

Normal gray (50% lightness, 0% saturation) harmonizes with everything.

Use achromatic gray as a bridge between different chromatic families:

// Bridging two different chromatic palettes
<div className="bg-blueGray-900">
  <div className="bg-achromatic-800" /> {/* neutral transition */}
  <div className="bg-orangeGray-800" /> {/* now feels harmonious */}
</div>

Part 8: Agent Instructions

Step 1: Determine Theme

Before writing any code, determine the appropriate theme:

import { selectTheme, THEME_HUES } from './lib/design-system'

const appType = "todo"     // What they're building
const userIntent = "minimal" // How they want it to feel

const theme = selectTheme(appType, userIntent)

Theme Selection Priority

Explicit user intent ("make it feel calm") → Use intent mapping
App type ("build a finance dashboard") → Use app mapping
Default → Use 'trust' (blue-gray)

Theme Selection Logic

function selectTheme(appType: string, userIntent?: string): ThemeName {
  // App type defaults
  const appDefaults: Record<string, ThemeName> = {
    'finance': 'trust',
    'banking': 'trust',
    'dashboard': 'trust',
    'health': 'harmony',
    'fitness': 'energy',
    'meditation': 'calm',
    'productivity': 'focus',
    'social': 'affection',
    'dating': 'affection',
    'ecommerce': 'abundance',
    'education': 'wisdom',
    'creative': 'transformation',
    'documentation': 'clarity',
    'blog': 'serenity',
    'portfolio': 'neutral',
    'restaurant': 'warmth',
    'nature': 'earth',
    'tech': 'innovation',
    'startup': 'optimism',
    'enterprise': 'trust',
    'gaming': 'energy',
    'music': 'spirit',
    'art': 'passion'
  }
  
  // User intent overrides
  if (userIntent) {
    const intentMap: Record<string, ThemeName> = {
      'professional': 'trust',
      'playful': 'energy',
      'calm': 'calm',
      'exciting': 'passion',
      'trustworthy': 'trust',
      'modern': 'innovation',
      'warm': 'warmth',
      'minimal': 'neutral',
      'bold': 'urgency',
      'elegant': 'spirit'
    }
    if (intentMap[userIntent]) return intentMap[userIntent]
  }
  
  return appDefaults[appType] || 'trust'
}

Step 2: Generate CSS

function generateThemeCSS(hue: number, isDark: boolean = true): string {
  const sat = 12 // Chromatic gray saturation
  
  if (isDark) {
    return `
      --background: hsl(${hue}, ${sat - 4}%, 4%);
      --foreground: hsl(${hue}, ${sat - 6}%, 93%);
      --muted: hsl(${hue}, ${sat - 4}%, 15%);
      --muted-foreground: hsl(${hue}, ${sat - 6}%, 60%);
      --card: hsl(${hue}, ${sat - 2}%, 7%);
      --card-foreground: hsl(${hue}, ${sat - 6}%, 93%);
      --border: hsl(${hue}, ${sat - 4}%, 18%);
      --input: hsl(${hue}, ${sat - 4}%, 18%);
      --primary: hsl(${hue}, ${sat + 3}%, 55%);
      --primary-foreground: hsl(${hue}, ${sat}%, 8%);
      --secondary: hsl(${hue}, ${sat - 4}%, 18%);
      --secondary-foreground: hsl(${hue}, ${sat - 6}%, 93%);
      --accent: hsl(${hue}, ${sat + 5}%, 25%);
      --accent-foreground: hsl(${hue}, ${sat - 6}%, 93%);
      --destructive: hsl(0, 45%, 45%);
      --destructive-foreground: hsl(0, 0%, 100%);
      --ring: hsl(${hue}, ${sat + 3}%, 55%);
    `
  }
  // Light mode similar pattern...
}

Step 3: Apply Design Principles

Color Rules

NEVER use saturated colors (>20% saturation)
All colors derive from the theme hue
Use semantic tokens: bg-background, text-foreground, border-border

Spacing (4px Grid)

// ✅ Good
<div className="p-4 space-y-6">

// ❌ Bad  
<div className="p-5 space-y-7">

Typography

<h1 className="text-4xl font-bold tracking-tight">Heading</h1>
<p className="text-base">Body text</p>
<span className="text-sm text-muted-foreground">Secondary</span>

Components - Always Include:

Loading states (skeletons)
Error states (with retry option)
Empty states (with CTA)

Step 4: Accessibility

Required:

All interactive elements keyboard accessible
Focus states visible (ring class)
Labels on all form inputs
Sufficient color contrast
prefers-reduced-motion honored

<button
  className="focus:ring-2 focus:ring-ring focus:ring-offset-2"
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click me
</button>

Step 5: File Structure

app/
├── globals.css          # Generated theme CSS
├── layout.tsx           # Root layout with fonts
├── page.tsx             # Home page
├── components/
│   └── ui/              # shadcn components
├── lib/
│   ├── utils.ts         # cn() helper
│   └── actions.ts       # Server actions
└── tailwind.config.ts   # Generated config

Agent Decision Tree

1. IDENTIFY APP TYPE
   "todo app" → productivity
   "landing page" → marketing
   "dashboard" → analytics
   
2. SELECT THEME
   productivity → focus (yellow-gray 50°)
   marketing → depends on industry
   analytics → trust (blue-gray 210°)

3. DETECT USER INTENT (from their words)
   "professional" → formal layout
   "playful" → rounded corners, friendly copy
   "minimal" → more whitespace, fewer elements

4. GENERATE WITH PRINCIPLES
   - Chromatic colors (8-20% saturation)
   - Consistent spacing (4px grid)
   - Accessible (keyboard, contrast, motion)
   - Honest UX (no dark patterns)
   
5. ALWAYS INCLUDE
   - Loading states
   - Error states
   - Empty states
   - Responsive design

Part 9: UX Principles (From Ancient Wisdom)

1. Sovereignty Over Dependency

Design should empower users, not create dependency.

Clear escape routes (always show how to undo, go back, exit)
Transparent about what's happening (loading states, progress)
User controls their data (export, delete options)

2. Coherence Over Chaos

Every element should feel like it belongs.

Consistent spacing (use 4px grid: 4, 8, 12, 16, 24, 32, 48)
Consistent typography scale (14px base, 1.25 ratio)
Consistent interaction patterns

3. Presence Over Distraction

Help users focus on what matters.

Minimal notifications
No attention-hijacking patterns
Clear visual hierarchy
Generous whitespace

4. Flow Over Friction

Design for natural movement.

Keyboard works everywhere
Tab order makes sense
Touch targets 44px minimum
Smooth transitions (200-400ms)

5. Truth Over Deception

No dark patterns.

Clear pricing
Honest button labels (not "Maybe later" for "No")
Obvious unsubscribe options
No hidden fees or gotchas

Interaction Guidelines

Keyboard Navigation:

Every interactive element focusable
Focus visible (ring, outline)
Tab order follows visual order
Escape closes modals/dropdowns

Motion & Animation:

Honor prefers-reduced-motion
Use GPU-accelerated properties only: transform, opacity
Duration: 150-400ms
Easing: cubic-bezier(0.4, 0, 0.2, 1) for most

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Loading States:

Never leave users hanging
Skeleton screens for content
Spinners for actions
Progress bars for known duration

Error States:

Clear error messages (not "Error 500")
Suggest fixes when possible
Keep user's input after error
Position errors near the problem

Part 10: Quick Reference

Intention → Palette Mapping

Intention	Palette	Force	Hue	Best For
`urgency`	redGray	Thermal	10°	Alerts, errors, critical
`energy`	orangeGray	Thermal	30°	CTAs, activation, enthusiasm
`warmth`	orangeGray	Thermal	30°	Hospitality, welcome, comfort
`clarity`	yellowGray	Luminous	50°	Learning, documentation, focus
`optimism`	yellowGray	Luminous	50°	Success states, achievements
`growth`	greenGray	Neutral	120°	Progress, health, nature
`harmony`	tealGray	Neutral	170°	Wellness, balance, equilibrium
`trust`	blueGray	Electrical	210°	Professional, reliable, calm
`calm`	indigoGray	Electrical	240°	Meditation, depth, intuition
`spirit`	violetGray	Electrical	270°	Creativity, luxury, transcendence
`affection`	roseGray	Special	340°	Care, love, nurturing
`neutral`	achromatic	—	0°	Minimal, universal, professional

Saturation Guidelines

Element Type	Saturation Range
Backgrounds	8-12%
Cards/Surfaces	10-14%
Text (on dark)	0% (pure white/gray)
Borders	12-16%
Interactive elements	14-18%
Focus states	16-20%

Semantic Classes

Use	Class
Page background	`bg-background`
Primary text	`text-foreground`
Secondary text	`text-muted-foreground`
Cards	`bg-card border-border`
Inputs	`bg-input border-border`
Primary buttons	`bg-primary text-primary-foreground`
Borders	`border-border`

Standard Sizes

Element	Size
Touch targets	min 44px
Button padding	`px-4 py-2`
Card padding	`p-6`
Section gap	`space-y-8`
Border radius	`rounded-lg` (8px)

Spacing Scale (px)

4 | 8 | 12 | 16 | 24 | 32 | 48 | 64 | 96

Typography Scale

12 | 14 | 16 | 18 | 20 | 24 | 30 | 36 | 48

Border Radius

Small (buttons, inputs): 6px
Medium (cards): 8px
Large (modals): 12px
Nested: child radius < parent radius

Shadows (Layered)

--shadow-sm: 0 1px 2px hsl(var(--foreground) / 0.05);
--shadow-md: 0 4px 6px hsl(var(--foreground) / 0.07),
             0 2px 4px hsl(var(--foreground) / 0.05);
--shadow-lg: 0 10px 15px hsl(var(--foreground) / 0.1),
             0 4px 6px hsl(var(--foreground) / 0.05);

Don'ts

❌ Don't use arbitrary colors (text-blue-500) ❌ Don't skip loading states ❌ Don't use placeholders instead of labels ❌ Don't hide navigation ❌ Don't use manipulative button labels ❌ Don't exceed 20% saturation on any color ❌ Never use saturation above 25% for any surface ❌ Never use pure black (hsl(0, 0%, 0%)) - use 950 shades instead ❌ Never use pure white (hsl(0, 0%, 100%)) - use 50 shades instead ❌ Never use brownish-green combinations (jealousy/deceit) ❌ Never use gray-green without clear separation (depression)

Tech Stack Defaults

Next.js 15 (App Router)
├── TypeScript
├── Tailwind CSS 4
├── shadcn/ui components
├── Geist font (or Inter)
└── Server Actions (not API routes)

TypeScript Type Definitions

export type ChromaticHue = 
  | "redGray" 
  | "orangeGray" 
  | "yellowGray" 
  | "greenGray" 
  | "tealGray"
  | "blueGray" 
  | "indigoGray" 
  | "violetGray" 
  | "roseGray"
  | "achromatic"

export type ChromaticShade = 
  | 50 | 100 | 200 | 300 | 400 
  | 500 | 600 | 700 | 800 | 900 | 950

export type Force = "thermal" | "luminous" | "neutral" | "electrical"

export type DesignIntention =
  | "urgency" | "energy" | "warmth"     // THERMAL
  | "clarity" | "optimism"               // LUMINOUS
  | "growth" | "harmony"                 // NEUTRAL
  | "trust" | "calm" | "spirit"          // ELECTRICAL
  | "affection"                          // SPECIAL
  | "neutral"                            // ACHROMATIC

export type FormNature = 
  | "directed"      // pointed, projectile
  | "radiating"     // star-like, outward
  | "protective"    // enclosing, shell
  | "intellectual"  // crystalline, sharp
  | "aspirational"  // upward, spire
  | "emotional"     // cloud-like, soft

export type ClarityLevel = 
  | "definite" 
  | "clear" 
  | "balanced" 
  | "soft" 
  | "ethereal"

export interface ThoughtFormProperties {
  quality: DesignIntention      // → determines color
  nature: FormNature            // → determines shape
  definiteness: ClarityLevel    // → determines outline
}

"Quality of thought determines colour. Nature of thought determines form. Definiteness of thought determines clearness of outline."
— Besant & Leadbeater, Thought-Forms (1901)

"Good design is invisible. Great design is inevitable."