← 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 Semantic Tokens

Complete design system tokens ready for production.

📦 Multiple Formats

Export to CSS, SCSS, LESS, Tailwind, or JSON.

Base URL

https://taichi.bucaastudio.com/api

Endpoints

POST /generate-theme 10 req/min

Generate balanced light and dark themes using color harmony theory.

Request Body

Parameter Type Description
style string Harmony mode: random, analogous, complementary, triadic, etc.
baseColor string? Hex color seed, e.g. #3B82F6
saturation number? -5 to 5. Adjust color vibrancy.
contrast number? -5 to 5. Adjust light/dark separation.
brightness number? -5 to 5. Global lightness shift.

Example Request

curl -X POST https://taichi.bucaastudio.com/api/generate-theme \
  -H "Content-Type: application/json" \
  -d '{
    "style": "analogous",
    "baseColor": "#3B82F6",
    "saturation": 2
  }'

Response

{
  "success": true,
  "light": { "bg": "#f4f5f9", "primary": "#3d6fc2", ... },
  "dark": { "bg": "#0a0b0d", "primary": "#5e8ad4", ... },
  "metadata": {
    "style": "analogous",
    "seed": "#3B82F6",
    "colorSpace": "OKLCH",
    "philosophy": "Harmony found in nature..."
  }
}
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)

Each theme includes these tokens for both light and dark modes:

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

Harmony Styles

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.