Getting Started

Installation

Add Wuko's shadcn-style component registry to your project. Components land directly in your codebase, themed by Wuko's role tokens, ready to customize.

Prerequisites

Wuko requires Tailwind v4 (the @theme inline pattern is v4-only) and React 19+. If your project is on Tailwind v3, migrate to v4 before continuing.

1. Initialize shadcn

Wuko components are distributed through the shadcn CLI. Run init once in your project. It creates components.json and adds lib/utils.ts with the cn helper.

terminal

npx shadcn@latest init

2. Set up Wuko's role tokens

Paste the block below into your app/globals.css(or wherever you import Tailwind). It defines Wuko's public role tokens for both dark and light modes, and wires them as Tailwind v4 utility classes (bg-wuko-card, text-wuko-text, and so on).

app/globals.css

@import "tailwindcss";

@custom-variant light (&:where([data-theme="light"] *));

:root {
  --wuko-bg: #0f172a;
  --wuko-card: #1e293b;
  --wuko-border: #334155;
  --wuko-heading: #e2e8f0;
  --wuko-text: #cbd5e1;
  --wuko-text-muted: #94a3b8;
  --wuko-accent: #5eead4;
  --wuko-accent-hover: #2dd4bf;
  --wuko-accent-active: #14b8a6;
  --wuko-danger: #e11d48;
  --wuko-danger-hover: #be123c;
  --wuko-danger-fg: #fb7185;
  --wuko-success-fg: #10b981;
  --wuko-warning-fg: #f59e0b;
  --wuko-gold: #d4a017;
  color-scheme: dark;
}

[data-theme="light"] {
  --wuko-bg: #f8fafc;
  --wuko-card: #ffffff;
  --wuko-border: #e2e8f0;
  --wuko-heading: #0f172a;
  --wuko-text: #475569;
  --wuko-text-muted: #64748b;
  --wuko-accent: #0f766e;
  --wuko-accent-hover: #0d9488;
  --wuko-accent-active: #134e4a;
  --wuko-danger: #dc2626;
  --wuko-danger-hover: #b91c1c;
  --wuko-danger-fg: #b91c1c;
  --wuko-success-fg: #047857;
  --wuko-warning-fg: #92400e;
  --wuko-gold: #d4a017;
  color-scheme: light;
}

@theme inline {
  --color-wuko-bg: var(--wuko-bg);
  --color-wuko-card: var(--wuko-card);
  --color-wuko-border: var(--wuko-border);
  --color-wuko-heading: var(--wuko-heading);
  --color-wuko-text: var(--wuko-text);
  --color-wuko-text-muted: var(--wuko-text-muted);
  --color-wuko-accent: var(--wuko-accent);
  --color-wuko-accent-hover: var(--wuko-accent-hover);
  --color-wuko-accent-active: var(--wuko-accent-active);
  --color-wuko-danger: var(--wuko-danger);
  --color-wuko-danger-hover: var(--wuko-danger-hover);
  --color-wuko-danger-fg: var(--wuko-danger-fg);
  --color-wuko-success-fg: var(--wuko-success-fg);
  --color-wuko-warning-fg: var(--wuko-warning-fg);
  --color-wuko-gold: var(--wuko-gold);
}

Without this block, Wuko components install but render with undefined utility classes. The role tokens are the foundation of the design system.

3. Add a component

Pull any Wuko primitive into your codebase via the shadcn CLI:

terminal

npx shadcn@latest add http://localhost:3000/r/placeholder.json

Wuko's registry is currently served from localhost:3000 during development. Replace the URL with the production origin once Wuko is publicly hosted.

4. Verify theming

The component lands at components/ui/placeholder.tsx (per your components.json aliases). To verify the role tokens flip correctly, set <html data-theme="light"> in your dev tools or your layout. The component will switch to light values automatically.

Build a real theme toggle later, or copy Wuko's pattern from THEMING.md. The tokens you just installed are designed to respond to data-theme changes without component-side code.

Quick Start