← Back to Generator

API Documentation

Generate balanced light & dark themes programmatically using OKLCH color science.

🎨 OKLCH Color Space

Perceptually uniform colors for consistent, balanced themes.

☯️ Dual Themes

Every request returns perfectly matched light & dark variants.

🔧 20 Tokens per Theme

Complete design system tokens ready for production.

🧪 Readability Guardrails

Final pass protects text legibility and token separation.

Base URL

https://taichi.bucaastudio.com/api

Endpoints

POST /generate-theme 10 req/min

Generate balanced light and dark themes using color harmony theory with one coherent brightness/contrast/saturation adjustment stage.

Request Body

Parameter Type Description
mode (style) string Harmony mode: random, analogous, complementary, triadic, etc.
baseColor string? Hex color seed, e.g. #3B82F6
saturationLevel number? -5 to 5. Shared vibrancy adjustment (aliases: saturation, sat).
contrastLevel number? -5 to 5. Shared contrast adjustment (aliases: contrast, con).
brightnessLevel number? -5 to 5. Shared brightness adjustment (aliases: brightness, bri).
darkFirst boolean? Generate dark mode as the source palette, then derive light mode.
splitAdjustments boolean? Enable separate light/dark adjustment levels (alias: split).
light*/dark* number? Per-mode levels used with splitAdjustments=true (aliases: lsat, lcon, lbri, dsat, dcon, dbri).

Example Request

curl -X POST https://taichi.bucaastudio.com/api/generate-theme \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "analogous",
    "baseColor": "#3B82F6",
    "saturationLevel": 2,
    "darkFirst": true,
    "splitAdjustments": true,
    "lightBrightnessLevel": 1,
    "darkBrightnessLevel": -1
  }'

Response

{
  "success": true,
  "light": { "bg": "#f4f5f9", "primary": "#3d6fc2", ... },
  "dark": { "bg": "#0a0b0d", "primary": "#5e8ad4", ... },
  "metadata": {
    "mode": "analogous",
    "style": "analogous",
    "seed": "#3B82F6",
    "colorSpace": "OKLCH",
    "philosophy": "Harmony found in nature...",
    "options": {
      "darkFirst": true,
      "splitAdjustments": true,
      "saturationLevel": 2,
      "contrastLevel": 0,
      "brightnessLevel": 0,
      "lightSaturationLevel": 2,
      "lightContrastLevel": 0,
      "lightBrightnessLevel": 1,
      "darkSaturationLevel": 2,
      "darkContrastLevel": 0,
      "darkBrightnessLevel": -1
    }
  }
}
POST /export-theme 15 req/min

Convert a theme object to CSS, SCSS, LESS, Tailwind, or JSON format.

Request Body

Parameter Type Description
theme object Theme tokens object (from generate-theme)
format string css, scss, less, tailwind, json
options.prefix string? Variable prefix (default: taichi)

Example Request

curl -X POST https://taichi.bucaastudio.com/api/export-theme \
  -H "Content-Type: application/json" \
  -d '{
    "theme": { "primary": "#3B82F6", "bg": "#F8FAFC", ... },
    "format": "css",
    "options": { "prefix": "my-app" }
  }'

Semantic Tokens (20 per theme)

Each theme includes these 20 tokens. The response returns light + dark (40 token values total):

bg
card
card2
text
textMuted
textOnColor
primary
primaryFg
secondary
secondaryFg
accent
accentFg
border
ring
good
goodFg
warn
warnFg
bad
badFg

Adjustment Model

The API generates a neutral base palette, then applies brightness, contrast, and saturation together in one adjustment stage. A final readability/parity pass keeps text legible and semantic chromatic identity aligned between light and dark outputs.

Harmony Modes

Style Description
random Randomly chosen harmony mode
monochrome Single hue with varied lightness
analogous Adjacent colors on the wheel
complementary Opposite colors for high contrast
split-complementary Base + two adjacent to complement
triadic Three evenly spaced colors
tetradic Four colors in rectangular pattern
compound Complement + two adjacent
triadic-split Wide dynamic palette

Error Codes

Code Description
METHOD_NOT_ALLOWED Wrong HTTP method (use POST)
RATE_LIMIT_EXCEEDED Too many requests, wait and retry
INVALID_STYLE Unknown harmony style
INVALID_PARAMETERS Values outside -5 to 5 range
INVALID_BASE_COLOR Invalid hex color format
INVALID_THEME Missing or malformed theme object
INVALID_FORMAT Unknown export format

CORS

All endpoints support CORS with Access-Control-Allow-Origin: *, allowing direct browser requests.