Chameleon UI

One component library. Five complete design systems. Switch themes at runtime with a single prop.

Material · Simple · Minimalist · Glassy · Liquid

Each theme ships with a full light and dark mode, its own typography, spacing, and ambient backgrounds — no CSS overrides required.

v2.0 — built for AI agents. Chameleon is a tool surface agents call, not just a library they read about: an MCP server (chameleon mcp, 23 tools), a validated spec language for pages (ChameleonSpec) and whole applications (AppSpec → chameleon new), a brand pipeline with WCAG AA auditing (chameleon brand), live previews (/play), and an integrity-checked registry. Say "build me a CRM for my bakery — brand from my site" to Claude Code and it lands as a running app.

# register the MCP server once
claude mcp add chameleon -- npx -y -p @chameleon-ui-lib/react chameleon mcp
# or teach any agent without MCP
npx chameleon agents init

Install

npm install @chameleon-ui-lib/react

Framework Setup (Vite + React + TypeScript + Tailwind v4)

This is the recommended known-good configuration for new projects.

1. Create your project

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install

2. Install Tailwind v4 and Chameleon UI

npm install -D tailwindcss @tailwindcss/vite
npm install @chameleon-ui-lib/react

3. Configure Vite (vite.config.ts)

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),   // Tailwind v4 uses a Vite plugin — no tailwind.config.ts needed
  ],
});

Tailwind v4 Note: There is no tailwind.config.ts in v4. Configuration is handled via the Vite plugin and CSS directives.

4. Set up your CSS entry (src/index.css)

@import "tailwindcss";
@import "@chameleon-ui-lib/react/styles";

Import order matters: @import "tailwindcss" must come before the library styles. If PostCSS warns "@import must precede all other rules", check that no other CSS rules appear above the @import lines in your entry file.

5. Import CSS in your entry file (src/main.tsx)

import "./index.css";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

6. Wrap your app with ChameleonProvider (src/App.tsx)

import { ChameleonProvider, Button, Card } from "@chameleon-ui-lib/react";

export default function App() {
  return (
    <ChameleonProvider initialTheme="glassy" initialMode="dark">
      <Card>
        <Button>Get Started</Button>
      </Card>
    </ChameleonProvider>
  );
}

7. (Optional) Run chameleon init to scaffold components

npx @chameleon-ui-lib/react init

This creates chameleon.config.json and auto-configures Tailwind in your vite.config.ts.

Quick Start (existing project)

import "@chameleon-ui-lib/react/styles";
import { ChameleonProvider, Button, Card } from "@chameleon-ui-lib/react";

export default function App() {
  return (
    <ChameleonProvider initialTheme="glassy" initialMode="dark">
      <Card>
        <Button>Get Started</Button>
      </Card>
    </ChameleonProvider>
  );
}

Switch themes at runtime — no page reload, no flash:

const { setTheme, setMode } = useChameleon();

setTheme("liquid");   // material | simple | minimalist | glassy | liquid
setMode("light");     // light | dark

What's Included

| Layer | Components | |---|---| | Atoms | Button Input Badge Progress Spinner Label Switch Checkbox | | Molecules | Card Tabs Dialog Alert StatCard PricingCard Avatar Tooltip Select Textarea | | Organisms | DataTable Charts KanbanBoard Calendar FileUpload Gallery CommandPalette | | Auth | LoginForm SignupForm TwoFactorForm MagicLinkForm ForgotPassword ResetPassword | | Templates | Dashboard · Landing · Settings · Inbox · Analytics · Docs | | Animations | Animated AnimatedList — theme-matched motion presets |

Composite-First Architecture

Chameleon now exposes reusable composite sections so you can mix and match blocks without committing to a full template.

Use full templates with typed style overrides

import { LandingPageTemplate } from "@chameleon-ui-lib/react";

<LandingPageTemplate
  styleConfig={{
    heroSection: { heading: "Launch faster" },
    featureCards: { columns: 4 },
  }}
/>;

Mix standalone composites across template domains

import { HeroSection, StatsCard, SettingsList } from "@chameleon-ui-lib/react/composites";

<div className="space-y-8">
  <HeroSection heading="Workspace Overview" />
  <StatsCard label="Active Teams" value={124} trend={9.1} />
  <SettingsList heading="Workspace Preferences" />
</div>;

New subpath imports

• @chameleon-ui-lib/react/composites
• @chameleon-ui-lib/react/templates
• @chameleon-ui-lib/react/types

Deep dive docs

• Composite guide: COMPOSITES.md
• API reference: docs/COMPOSITES_API.md
• Types reference: docs/TYPES.md
• Migration notes: docs/MIGRATION_v1.0.9.md
• Workshop showcase page source: src/app/components/chameleon/composite-showcase.tsx

CLI

Scaffold components and templates directly into your project:

# Initialize Chameleon in an existing project
npx @chameleon-ui-lib/react init

# Copy a component into your source tree
chameleon add button
chameleon add data-table

# Copy a full-page template
chameleon template dashboard

# Set the active theme in chameleon.config.json
chameleon theme glassy

# List everything available
chameleon list

# Health check — verifies your setup
chameleon doctor

The CLI reads/writes chameleon.config.json at your project root and copies files into the directory you configure (src/components/ui by default).

Theme Tokens

All components read from CSS custom properties — override any token to extend a theme without touching component code:

:root {
  --primary: 262 83% 58%;
  --card: 0 0% 100%;
  --radius: 0.75rem;
}

Troubleshooting

PostCSS @import must precede all other rules

This happens when @import statements appear after non-import CSS rules. Fix: ensure your CSS entry file starts with imports and contains no rules before them:

/* ✅ Correct order */
@import "tailwindcss";
@import "@chameleon-ui-lib/react/styles";

/* your custom rules below */
:root { --my-token: red; }

/* ❌ Wrong — rule before import */
:root { --my-token: red; }
@import "tailwindcss";

Run chameleon doctor to auto-detect this issue in your project.

Tailwind classes not applying

Make sure @tailwindcss/vite is in your vite.config.ts plugins array — in Tailwind v4 there is no tailwind.config.ts. Run chameleon init to auto-inject the plugin if it is missing.

Theme not switching

Wrap your entire app tree with <ChameleonProvider>. The provider must be an ancestor of every component that uses useChameleon().

Components directory not found

Run chameleon init first — it creates chameleon.config.json and the configured output directory.

License

MIT