Theming

Preset Picker

12 curated presets. Pick based on project feel:

Usage: theme preset <name> --apply writes directly to src/index.css.

NEVER default to violet/purple. If none of these fit, generate a custom theme.

Custom Themes

Sacred Geometry Patterns

11 mathematical patterns for hue generation:

Seed is the base hue (0-360). Pattern generates additional hues from it.

Pattern Aliases

Semantic shortcuts that resolve to a pattern + auto-chroma hint:

Auto-chroma is applied unless you explicitly pass --chroma. Example: --pattern vibrant gives triadic + high chroma. --pattern vibrant --chroma low overrides to low.

Font Registry (32 validated fonts)

Only use fonts from this registry. All have Google Fonts CDN availability.

Usage: --font "Space Grotesk" — the generator builds the full font stack with fallbacks.

Shadow Profiles

Usage: --shadow-profile moderate

Radius Stops

Usage: --radius rounded

Mood / Personality Briefs

The --mood flag generates a design personality brief (.ralph/design-brief.md) alongside the theme. The brief defines typography hierarchy, animation timing, spacing rhythm, and strict rules.

Usage:

theme generate --seed 210 --pattern goldenRatio --mood premium --apply
theme preset elegant-luxury --mood premium --apply
theme list moods

Presets auto-infer mood from the preset name (e.g., cyberpunk → industrial, bubblegum → playful). generate --apply requires --mood — you must choose a design direction.

Chroma — The Saturation Dial

Chroma controls how vivid or muted colors are, independent of hue/pattern:

You can also pass a numeric value (0.0-2.0) for fine control.

Usage:

theme generate --seed 150 --pattern triadic --chroma high --mood playful --apply
theme preset cyberpunk --chroma low --apply

Chroma cascade priority: explicit --chroma > alias auto-chroma > mood's chromaHint > default (1.0x).

OKLCH Color Model

Theme colors use OKLCH: oklch(L C H) where:

• L (Lightness): 0 = black, 1 = white
• C (Chroma): 0 = gray, higher = more saturated. The --chroma flag scales this channel.
• H (Hue): 0-360 degrees. The --pattern flag controls hue harmony.

Pattern controls WHICH colors. Chroma controls HOW VIVID they are. Independent knobs.

Custom Personalities — Remix the Presets

12 personality templates are available in .skills/personalities/. Use them as starting points:

# Browse available personalities
ls .skills/personalities/

# Read one
cat .skills/personalities/industrial.json

# Copy, remix, and use
cp .skills/personalities/industrial.json .ralph/my-personality.json
replace .ralph/my-personality.json "Raw structure." "Futuristic minimalism."
theme generate --seed 200 --pattern triadic --personality .ralph/my-personality.json --apply

When --personality is provided, it replaces --mood for the design brief. You can remix any field: philosophy, typography, animation timing, spacing rhythm, allowed/notAllowed rules, and checklist.

Modify Existing Themes

theme modify reads your current src/index.css and shifts colors:

# Shift all brand colors by 30 degrees and apply
theme modify --shift-hue 30 --scope brand --apply

# Shift only surface colors
theme modify --shift-hue -15 --scope surface --apply

# Shift everything
theme modify --shift-hue 45 --scope all --apply

Scopes:

• brand — primary, secondary, accent, ring, chart colors
• surface — background, card, popover, muted, border, input, sidebar
• all — everything

After shifting, contrast is re-enforced automatically. WCAG AA 4.5:1 minimum guaranteed.

Design Tokens (.ralph/tokens.json)

The theme command generates .ralph/tokens.json alongside CSS — a structured DTCG-format token file with full color data, contrast ratios, font metadata, shadow primitives, and mood personality.

Query tokens from the shell:

tokens                    # Full token summary (palette, contrast, fonts, shadows, mood)
tokens contrast           # Contrast ratio table — check before choosing color pairings
tokens palette            # Brand, surface, and text color tables
tokens font               # Font families, categories, weights
tokens shadow             # Shadow scale and primitives
tokens mood               # Mood personality: typography hierarchy, animation timing, spacing

Use tokens data to inform design decisions. Don't guess animation durations — check tokens mood. Don't guess contrast — check tokens contrast. The data is generated from the same OKLCH math as the theme.

Required Variables

All themes must define these. The theme command handles this automatically.

Values are OKLCH: oklch(0.6487 0.1538 150.31) — the theme generator produces these.

Tailwind v4 is active. Opacity modifiers like bg-primary/30 work natively with OKLCH. No color-mix() workaround needed for opacity.

Color coverage: For expressive presets, use bg-primary or bg-accent on at least one major section (hero, CTA, footer). Don't leave every section on bg-background — the theme has colors, use them.

Semantic Color Mapping

Every color need maps to a semantic token:

If you need a color that isn't in this table, use theme extend:

# Add a content-specific color at a specific hue
theme extend --name grape --hue 300
theme extend --name ocean --hue 200

# Then use it like any other token
# bg-grape text-grape-foreground border-grape

# List/remove extended colors
theme extend --list
theme extend --remove grape

Extended colors are auto-registered with @theme inline at build time. They regenerate automatically when you switch themes, maintaining harmony with the new palette.

Dynamic Colors (Data Viz, Timelines, Tags)

For elements that need distinct colors from a set (chart bars, timeline events, category tags), use the chart variables:

Pattern for dynamic color assignment:

const COLORS = ['bg-chart-1', 'bg-chart-2', 'bg-chart-3', 'bg-chart-4', 'bg-chart-5']
items.map((item, i) => <Tag className={COLORS[i % COLORS.length]}>{item.label}</Tag>)

For more than 5 colors, use theme extend --name <n> --hue <N> to add custom colors to the palette, then reference via bg-<n> / text-<n>.

NEVER use raw oklch(), hsl(), or hex values in components. Every color traces to a CSS variable.

Design Philosophy

Dynamic by Default

Landing pages should have motion, personality, and visual interest. Static pages feel dated. Only reduce animations when user explicitly requests "minimal", "clean", or "simple".

Theme Independence

Create themes appropriate to project content and mood, not the IDE. A crypto landing page should feel different from a bakery website.

Purposeful Motion

Animations should:

• Guide attention to important elements
• Provide feedback on interactions
• Create a sense of polish and care
• Never distract or annoy

Match Project Type

Creative CSS (Use By Default)

Entrance Animations

Add to sections and cards:

.fade-in {
  animation: fadeIn 0.6s ease-out forwards;
  opacity: 0;
}

@keyframes fadeIn {
  to { opacity: 1; }
}

@keyframes slideUp {
  from { opacity: 0; transform: translateY(20px); }
  to { opacity: 1; transform: translateY(0); }
}

Staggered Delays

For lists and grids, delay each item:

.stagger > *:nth-child(1) { animation-delay: 0s; }
.stagger > *:nth-child(2) { animation-delay: 0.1s; }
.stagger > *:nth-child(3) { animation-delay: 0.2s; }
/* Continue pattern */

Micro-interactions

/* Hover lift */
.hover-lift {
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.hover-lift:hover {
  transform: translateY(-4px);
  box-shadow: 0 10px 20px rgba(0,0,0,0.1);
}

/* Button press */
.press:active {
  transform: scale(0.98);
}

/* Glow effect for CTAs */
.glow:hover {
  box-shadow: 0 0 20px color-mix(in oklch, var(--primary), transparent 60%);
}

Background Effects

/* Gradient background */
.gradient-bg {
  background: linear-gradient(135deg, var(--primary), var(--accent));
}

/* Glassmorphism */
.glass {
  background: color-mix(in oklch, var(--background), transparent 20%);
  backdrop-filter: blur(10px);
  border: 1px solid color-mix(in oklch, var(--border), transparent 50%);
}

Opacity

Tailwind v4: Opacity modifiers work natively with OKLCH — use bg-primary/30 in className. CSS: Use color-mix when writing raw CSS (keyframes, custom properties):

/* 40% opacity of primary */
color-mix(in oklch, var(--primary), transparent 60%)

/* 70% opacity of background */
color-mix(in oklch, var(--background), transparent 30%)

/* 50% opacity of border */
color-mix(in oklch, var(--border), transparent 50%)

Timing Guidelines

• Micro-interactions: 150-200ms
• Hover states: 200-300ms
• Entrance animations: 400-600ms
• Stagger delays: 50-100ms between items
• Easing: ease-out for entrances, ease-in-out for hovers

Keyframes Library

Include these in src/index.css as needed:

/* Entrances */
@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes fadeInUp {
  from { opacity: 0; transform: translateY(20px); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes fadeInDown {
  from { opacity: 0; transform: translateY(-20px); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes slideIn {
  from { opacity: 0; transform: translateX(-20px); }
  to { opacity: 1; transform: translateX(0); }
}

@keyframes scaleIn {
  from { opacity: 0; transform: scale(0.9); }
  to { opacity: 1; transform: scale(1); }
}

/* Decorative */
@keyframes float {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-10px); }
}

@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.7; }
}

@keyframes bounce {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-5px); }
}

/* Backgrounds */
@keyframes gradient-shift {
  0% { background-position: 0% 50%; }
  50% { background-position: 100% 50%; }
  100% { background-position: 0% 50%; }
}

@keyframes glow-pulse {
  0%, 100% { box-shadow: 0 0 5px color-mix(in oklch, var(--primary), transparent 50%); }
  50% { box-shadow: 0 0 20px color-mix(in oklch, var(--primary), transparent 20%); }
}

Accessibility

Always include this in src/index.css:

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

This respects users who have motion sensitivity while keeping your design intact for others.

Respecting User Preferences

Default (no specific request)

Go rich: animations, expressive colors, dynamic backgrounds, micro-interactions. Make it memorable.

When user says "minimal", "clean", or "simple"

• Reduce to subtle fades only (no bounces, floats, or complex animations)
• Monochromatic or limited palette
• More whitespace
• Fewer decorative elements

When user says "professional" or "corporate"

• Subdued animations (fades only, shorter durations)
• Conservative color palette (blues, grays)
• Structured grid layouts
• No playful elements

Always honor explicit requests. If user says "no animations", remove them entirely.

Overlays & Z-Index (CRITICAL)

Stack components handle this automatically. If you must go custom:

/* Backdrop */
.overlay-backdrop {
  @apply fixed inset-0 bg-black/50 z-40;
}

/* Content */
.overlay-content {
  @apply fixed z-50;
  /* center it */
  @apply top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2;
}

Z-index scale:

• z-10: Sticky headers
• z-20: Dropdowns, tooltips
• z-30: Fixed sidebars
• z-40: Modal backdrops
• z-50: Modal content
• z-[100]: Dev tools only

Never manually layer multiple modals. Use one at a time.

Native Form Element Fix (CRITICAL)

Radix Select, native <select>, and other form elements ignore CSS variables in dark mode. Always include:

/* In src/index.css, after :root variables */
select,
input,
textarea {
  background-color: var(--background);
  color: var(--foreground);
  border-color: var(--border);
}

select option {
  background-color: var(--popover);
  color: var(--popover-foreground);
}

/* For autofill */