Theme Foundation

Generate a complete theme color system from a single brand color. Creates primary accent, secondary accent (complementary), and neutral ramps - all mathematically derived.

When to Use

• "Create a theme from my brand color"
• "I need colors for light and dark mode"
• "Generate a color system for my app"
• "Start a new design system with this color"

Installation

npx @basiclines/rampa

Recipe

Given a user's brand color, generate three ramp types:

1. Primary Accent Ramp

The main brand color expanded to a full 10-shade scale.

rampa -C "<brand-color>" -L 95:10 --size=10 -O css --name=accent

2. Secondary Accent (Complementary)

Mathematically opposite on the color wheel - perfect for CTAs, highlights, or secondary actions.

rampa -C "<brand-color>" --add=complementary -L 95:10 --size=10 -O css

This outputs two ramps:

• base - the primary accent
• complementary-1 - the secondary accent

3. Neutral Ramp

Derived from the brand color but heavily desaturated. This creates "warm" or "cool" neutrals that feel cohesive with the brand.

rampa -C "<brand-color>" -L 98:5 -S 5:10 --size=10 -O css --name=neutral

Complete Example

For brand color #3b82f6 (blue):

# Primary accent
rampa -C "#3b82f6" -L 95:10 --size=10 -O css --name=accent

# Secondary + Primary together
rampa -C "#3b82f6" --add=complementary -L 95:10 --size=10 -O css

# Neutrals (slightly warm from the blue)
rampa -C "#3b82f6" -L 98:5 -S 5:10 --size=10 -O css --name=neutral

Output Structure

:root {
  /* Primary Accent */
  --accent-0: #f0f7ff;
  --accent-1: #dbeafe;
  /* ... */
  --accent-9: #1e3a5f;

  /* Secondary Accent (complementary) */
  --complementary-1-0: #fff7ed;
  --complementary-1-1: #ffedd5;
  /* ... */

  /* Neutrals */
  --neutral-0: #fafafa;
  --neutral-1: #f5f5f5;
  /* ... */
  --neutral-9: #171717;
}

Light vs Dark Mode

The same ramps work for both modes - just map them differently:

Light Mode:

• Background: neutral-0 to neutral-2
• Text: neutral-8 to neutral-9
• Accent: accent-5 to accent-7

Dark Mode:

• Background: neutral-9 to neutral-7
• Text: neutral-0 to neutral-2
• Accent: accent-3 to accent-5

Tips

1. The complementary color is mathematically guaranteed to contrast with the primary
2. Neutrals inherit subtle warmth/coolness from the brand color
3. Use --size=11 for more granular control
4. Adjust -L range for more/less contrast (e.g., -L 90:20 for less extreme)