Palettt/Documentation

Palettt Code

A CSS-first design system generator for Tailwind CSS v4 — powered by your Palettt color palette. Also generates DESIGN.md and AGENTS.md for AI coding tools.

Available on npmNode.js 18+Tailwind CSS v4ESM

Overview#

palettt-code bridges the gap between picking colors on Palettt and using them in your app. Give it a Palettt URL and it outputs a complete set of OKLCH CSS custom properties for your globals.css — wired up with the Tailwind v4 @theme block so every color is accessible as a Tailwind utility.

It also generates AI agent documentation: a DESIGN.md with your full color token table (following the Google Stitch open format) and an AGENTS.md so Claude, Cursor, Copilot, and Windsurf all understand your design system out of the box.

You can scaffold a brand-new project with create, drop the design system into an existing project with init, or swap to a different palette with sync.

create

Scaffold a full project — framework, Tailwind, shadcn/ui, and your palette in one go.

init

Add the design system to an existing project by pointing at a Palettt URL.

sync

Swap your palette colors without touching any other CSS.

AI docs

Auto-generates DESIGN.md and AGENTS.md for AI coding tools on every init/sync.

Installation#

The easiest way is npx — no permanent install needed:

bash

npx palettt-code@latest create
npx palettt-code@latest init
npx palettt-code@latest sync

ℹ️How npx works: npx downloads palettt-code to a local cache on your machine (~/.npm/_npx/) and runs it from there. It does download the package — it just doesn't add a global command to your PATH. The cache persists between runs so subsequent calls are instant.

Prefer a permanent global command? Install once and use palettt anywhere:

bash

npm install -g palettt-code

# Then use the short command directly:
palettt create
palettt init
palettt sync

Requirements

✓Node.js 18 or newer
✓An existing package.json in your project root
✓A Palettt palette URL from palettt.com (see URL Format below)

Commands#

$palettt-code create [template]#

Scaffolds a brand-new project with your chosen framework, installs Tailwind CSS v4, optionally adds shadcn/ui, and runs init against your Palettt URL — all in one interactive flow.

Usage

bash

npx palettt-code@latest create

Interactive prompts

Prompt	Options
Project Name	Lowercase alphanumeric, hyphens, dots, underscores
Framework	`Next.js`, `Vite (React/TS)`, `React Router`
Palettt URL	A valid URL from `palettt.com/generate-palette/v2/...`
Install shadcn/ui	Yes / No — runs `shadcn@latest init -d`

Template shortcut

Pass shadcn as a template argument to skip the shadcn prompt and always include it:

bash

npx palettt-code@latest create shadcn

What it does

Runs the framework scaffolder (create-next-app, create-vite, or create-react-router)
Installs tailwindcss, clsx, and tailwind-merge as dev dependencies
Writes a lib/utils.ts with the cn() helper
Configures Vite plugin and TypeScript path aliases (for Vite / React Router)
Optionally runs shadcn/ui initialization
Injects OKLCH color tokens into your global CSS file
Generates DESIGN.md and AGENTS.md in the project root

$palettt-code init [url]#

Initializes the Palettt design system in an existing project. Finds your global CSS file, injects an OKLCH-based :root {} block, wires up Tailwind v4 @theme variables, and generates AI agent documentation files.

Usage

bash

# Interactive (prompts for URL)
npx palettt-code@latest init

# Direct (URL as argument)
npx palettt-code@latest init https://palettt.com/generate-palette/v2/50-0.2-250_70-0.1-20_80-0.15-180_40-0.05-300_90-0.05-50

Auto-detected CSS paths

The CLI searches for your global CSS file in this order:

app/app.css
app/globals.css
src/app/globals.css
src/index.css
src/styles/globals.css
index.css

Generated output

The following is added to your CSS file:

css

/* Palettt Design System */
:root {
  --background: oklch(90% 0.05 50);
  --foreground: oklch(0.15 0 0);
  --primary: oklch(50% 0.2 250);
  --primary-foreground: oklch(0.98 0 0);
  --secondary: oklch(70% 0.1 20);
  --secondary-foreground: oklch(0.15 0 0);
  --accent: oklch(80% 0.15 180);
  --accent-foreground: oklch(0.15 0 0);
  --muted: oklch(40% 0.05 300);
  --muted-foreground: oklch(0.98 0 0);
}

💡If a design system is already initialized, the CLI will ask whether you meant to sync instead. This prevents accidental overwrites.

TypeScript path aliases

init also updates tsconfig.json to add "@/*": ["./src/*"] if it's not already there.

Backups

Before modifying any file, the CLI writes a .palettt-backup copy next to the original so you can always restore. For example: globals.css.palettt-backup.

$palettt-code sync [url]#

Updates the OKLCH color values in an already-initialized project. Only replaces the color values — all other CSS is left untouched. Also regenerates DESIGN.md with the new colors. Great for experimenting with different palettes.

Usage

bash

# Interactive (prompts for URL)
npx palettt-code@latest sync

# Direct (URL as argument)
npx palettt-code@latest sync https://palettt.com/generate-palette/v2/65-0.18-160_...

How it differs from init

	`init`	`sync`
Requires existing design system	No	Yes
Creates :root block	Yes	No
Updates OKLCH values	Yes	Yes
Updates tsconfig.json	Yes	No
Touches non-color CSS	No	No
Generates DESIGN.md	Yes	Yes (updates)
Generates AGENTS.md	Yes (once)	No (preserved)

ℹ️If you run sync on a project that hasn't been initialized yet, the CLI will offer to run init instead.

URL Format#

The CLI parses the /v2/ segment of any Palettt palette URL to extract 5 colors. URLs must be from palettt.com.

Pattern

https://palettt.com/generate-palette/v2/L-C-H_L-C-H_L-C-H_L-C-H_L-C-H

Each segment is L-C-H, separated by underscores. The 5 segments map to CSS variables in order:

Segment	CSS variable	Also generates
1st	--primary	--primary-foreground
2nd	--secondary	--secondary-foreground
3rd	--accent	--accent-foreground
4th	--muted	--muted-foreground
5th	--background	--foreground

L, C, H explained

Part	Meaning	Range
L	Lightness (perceptual)	0 – 100
C	Chroma (color intensity)	0 – 0.5
H	Hue angle	0 – 360

Auto-contrast foreground

The CLI automatically picks a foreground color for each segment based on the lightness value:

css

/* If L > 60 → dark text */
--primary-foreground: oklch(0.15 0 0);

/* If L ≤ 60 → light text */
--primary-foreground: oklch(0.98 0 0);

Example URL breakdown

https://palettt.com/generate-palette/v2/50-0.2-250_70-0.1-20_80-0.15-180_40-0.05-300_90-0.05-50

Segment	Value	CSS output
--primary	50-0.2-250	oklch(50% 0.2 250)
--secondary	70-0.1-20	oklch(70% 0.1 20)
--accent	80-0.15-180	oklch(80% 0.15 180)
--muted	40-0.05-300	oklch(40% 0.05 300)
--background	90-0.05-50	oklch(90% 0.05 50)

CSS Variables#

After running init, your global CSS file will contain the following custom properties. These are also bridged into the Tailwind @theme block so you can use them as utilities:

css

:root {
  --background:           oklch(/* your value */);
  --foreground:           oklch(/* contrast auto */);

  --primary:              oklch(/* your value */);
  --primary-foreground:   oklch(/* contrast auto */);

  --secondary:            oklch(/* your value */);
  --secondary-foreground: oklch(/* contrast auto */);

  --accent:               oklch(/* your value */);
  --accent-foreground:    oklch(/* contrast auto */);

  --muted:                oklch(/* your value */);
  --muted-foreground:     oklch(/* contrast auto */);
}

@theme {
  --color-background:           var(--background);
  --color-foreground:           var(--foreground);
  --color-primary:              var(--primary);
  --color-primary-foreground:   var(--primary-foreground);
  --color-secondary:            var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-accent:               var(--accent);
  --color-accent-foreground:    var(--accent-foreground);
  --color-muted:                var(--muted);
  --color-muted-foreground:     var(--muted-foreground);

  --radius-lg: 0.5rem;
  --radius-md: calc(var(--radius-lg) - 2px);
  --radius-sm: calc(var(--radius-lg) - 4px);
}

💡Because the Tailwind @theme block maps every variable to a --color-* token, you can use utilities like bg-primary, text-primary-foreground, border-muted, etc., directly in your Tailwind classes.

AI Agent Files#

Every init (and create) generates two documentation files at your project root so AI coding tools understand your design system immediately — no manual setup.

`DESIGN.md`

Follows the Google Stitch open format . Machine-readable YAML front matter with all color tokens and radius values, plus a human-readable table of every token, its CSS variable, its Tailwind class, and its OKLCH value. Updated automatically on every sync.

yaml

---
name: my-app Design System
generator: palettt-code
colors:
  background: "oklch(95% 0.01 220)"
  foreground: "oklch(0.15 0 0)"
  primary: "oklch(65% 0.15 220)"
  primary-foreground: "oklch(0.15 0 0)"
  secondary: "oklch(70% 0.12 180)"
  ...
radius:
  lg: "0.5rem"
  md: "calc(0.5rem - 2px)"
  sm: "calc(0.5rem - 4px)"
---

# Design System: my-app

| Role       | CSS Variable          | Tailwind Class          | Value               |
|------------|-----------------------|-------------------------|---------------------|
| Primary    | `--primary`           | `bg-primary`            | `oklch(65% 0.15 220)` |
| Background | `--background`        | `bg-background`         | `oklch(95% 0.01 220)` |
| ...

`AGENTS.md`

The cross-platform AI agent standard — read by Claude Code, Cursor, GitHub Copilot, Windsurf, and others. Contains your project stack, framework-specific file conventions, dev commands, and design system rules. Generated once on init and never overwritten so you can customize it freely.

markdown

# my-app

## Stack
- **Framework**: Next.js (App Router)
- **Styling**: Tailwind CSS v4
- **UI Components**: shadcn/ui
- **Design System**: Palettt OKLCH — see [DESIGN.md](./DESIGN.md)

## Design System Rules
- Never hardcode colors — use CSS variables or Tailwind semantic classes
- Tailwind classes: `bg-primary`, `text-foreground`, `bg-muted`, etc.
- Class merging: use `cn()` from `@/lib/utils`
- Radius: `rounded-lg` / `rounded-md` / `rounded-sm`

## File Conventions
- Pages: `app/page.tsx`, `app/[route]/page.tsx`
- Components: `components/` (shared) or co-located
...

💡DESIGN.md updates with sync, AGENTS.md does not. When you run palettt sync with a new palette, DESIGN.md is regenerated with the new colors. Your AGENTS.md is left untouched — any customizations you've made are preserved.

Examples#

Copy any of these Palettt URLs and paste it into the CLI prompt to get started immediately.

Ocean Blue

Cool, professional blues with a dark navy primary and light sky background.

Preview

bash

npx palettt-code@latest init https://palettt.com/generate-palette/v2/30-0.18-245_60-0.12-220_75-0.1-200_25-0.08-250_92-0.04-215

Warm Earth

Earthy terracotta and warm neutrals — great for lifestyle or food brands.

Preview

bash

npx palettt-code@latest init https://palettt.com/generate-palette/v2/50-0.2-35_70-0.14-55_80-0.1-70_35-0.08-30_93-0.03-60

Forest Green

Deep greens with muted sage accents for nature-inspired interfaces.

Preview

bash

npx palettt-code@latest init https://palettt.com/generate-palette/v2/35-0.15-145_65-0.1-155_78-0.08-140_28-0.06-150_91-0.03-130

Want to create your own palette?

Open Palette Generator