@cognivo/theme-generator

Deterministic theme generator. Takes a natural-language description, scores it against 82 curated palettes, and returns a tier-2 token override (or raw Palette). Zero runtime dependencies — no LLM calls.

Installation

pnpm add @cognivo/theme-generator

Or use the CLI one-off without installing:

npx cognivo-theme "warm ocean professional"

Quick start

import { generateTheme } from '@cognivo/theme-generator';

// String form — returns tier-2 TokenOverride JSON
const theme = generateTheme('warm ocean professional');

// Object form — more control
const dark = generateTheme({
  description: 'cyberpunk neon',
  preferDark: true,
});

// Raw palette (8 hex values, no token mapping)
const palette = generateTheme({
  description: 'forest calm',
  raw: true,
});

API Reference

SDK

Export	Signature	Description
`generateTheme`	(opts: string \| GenerateOptions) => TokenOverride \| Palette	Main entry. Returns a tier-2 token override by default, or the raw `Palette` when `raw: true`.
`composePalette`	(input: ComposeInput) => Palette	Lower-level: scores the description and picks the best palette without emitting tokens.
`scoreDescription`	(desc: string) => ScoredPalette[]	Debug helper — returns all 82 palettes with their match scores.
`emitTokens`	(p: Palette) => TokenOverride	Convert a `Palette` into tier-2 semantic tokens.
`PALETTES`	Record<string, Palette>	The full curated palette map (82 entries). Keyed by slug.
`PALETTE_COUNT`	number	Current palette count. Equals `82`.

CLI

cognivo-theme "<description>" [--dark] [--raw]

  --dark   Prefer a dark-mode palette when available.
  --raw    Emit the raw Palette object instead of tier-2 tokens.
  --help   Print usage.

Output is JSON on stdout — pipe it into a file: npx cognivo-theme "forest calm" > theme.json.

Examples

Save a theme to disk

npx cognivo-theme "warm ocean professional" > public/theme.json

Apply generated tokens as CSS custom properties

import { generateTheme } from '@cognivo/theme-generator';

const tokens = generateTheme('sunset warm editorial');

for (const [name, value] of Object.entries(tokens)) {
  document.documentElement.style.setProperty(name, value);
}

Score candidates for debugging

import { scoreDescription } from '@cognivo/theme-generator';

const ranked = scoreDescription('calm trustworthy fintech');
console.log(ranked.slice(0, 5));
// [ { slug: 'ocean-professional', score: 4.2, palette: {…} }, … ]

Raw palette for custom mapping

const palette = generateTheme({
  description: 'cyberpunk neon',
  preferDark: true,
  raw: true,
});
// palette = { primary, secondary, accent, background, surface, text, muted, border, … }

CLI examples

Every invocation is deterministic — the same description always resolves to the same palette, so CI can snapshot the output.

Command	Matched palette	Primary color	Matched keywords
`npx cognivo-theme "warm sunset friendly"`	`sunset-warm`	#e76f51	warm, sunset, friendly
`npx cognivo-theme "cyberpunk neon" --dark`	`cyberpunk-neon`	#ff00aa	cyberpunk, neon, dark
`npx cognivo-theme "healthcare clean"`	`healthcare-clean`	#0891b2	healthcare, clean
`npx cognivo-theme "dracula code editor"`	`dracula-dark`	#bd93f9	dracula, code, editor
`npx cognivo-theme "high-contrast accessibility"`	`high-contrast-light`	#000000	high-contrast, accessibility

Browse the full library in Palette Explorer or list all slugs via Object.keys(PALETTES).

Caveats

Deterministic. Same input always produces the same output — no seeds, no LLM calls. Safe to run at build time.
Palette library is finite. 82 curated palettes covering hue-driven, industry verticals, brand moods, editor themes, and accessibility-first combinations. If your description does not match any keyword, the top-weighted default is returned.
Tier-2 only. The returned TokenOverride covers semantic colors — it does not modify spacing, typography, or motion tokens.
--raw skips token mapping. You get the 8-hex Palette object, which is useful when you want to drive a non-Cognivo surface or a custom emit pipeline.