Getting Started

Scaffold Softuq into a fresh Next.js or Vite app in one command.

Prerequisites

Node.js 20 or newer
A React project — create-next-app (App Router) or npm create vite@latest (react-ts)
No manual Tailwind setup — create-next-app ships with Tailwind v4, and for Vite softuq init installs tailwindcss + @tailwindcss/vite and wires the plugin into vite.config.ts automatically

Initialize

One command sets up everything: tokens, provider, @ alias, fonts, and a live starter page.

terminal

npx softuq init

What init does:

Writes softuq-tokens.css, softuq-theme.css, and (Vite only) softuq-fonts.css next to your globals and imports them in the right order
Copies cn(), token JS, SoftuqProvider, and presets.ts into src/lib/ and src/
Wires SoftuqProvider into your layout.tsx (Next) or main.tsx (Vite) and adds data-theme="dark" to <html>
Sets up fonts: next/font/google via a generated src/softuq-fonts.ts for Next.js, or installs @fontsource-variable/* packages and imports them in main.tsx for Vite
For Vite: installs tailwindcss + @tailwindcss/vite if missing, registers the plugin in vite.config.ts, and adds the @/* path alias to tsconfig.app.json and vite.config.ts
Scaffolds a starter landing page at app/page.tsx / App.tsx with a live theme playground for all 6 axes (opt out with --no-starter)

Run npm run dev and the starter renders immediately — no manual wiring.

Add more components

The starter pulls in button, card, form-text, label, select, and separator automatically. Add the rest as you need them.

terminal

# Add specific components
npx softuq add dialog input tabs tooltip

# Or add everything
npx softuq add --all

# See what's available
npx softuq list

Dependencies resolve automatically — adding select pulls in tag, adding breadcrumb pulls in dropdown-menu, etc.

Customize the provider (optional)

SoftuqProvider is already wired. Pass props to set initial theme, or call useSoftuq()to change it at runtime — the starter’s playground does exactly this.

layout.tsx

import { SoftuqProvider } from "@/softuq-provider";
import { softuqFontVariables } from "@/softuq-fonts";
import "./globals.css";

export default function RootLayout({ children }) {
  return (
    <html lang="en" data-theme="dark" className={softuqFontVariables}>
      <body>
        <SoftuqProvider
          palette="neutral"
          accent="violet"
          radius="lg"
          spacing="md"
          font="geist"
          headingFont="fraunces"
          storageKey="softuq-settings"
        >
          {children}
        </SoftuqProvider>
      </body>
    </html>
  );
}

Pass storageKey to persist user choices in localStorage and sync across tabs.

Use components

Import from your own project — components live in your repo.

page.tsx

import { Button } from "@/components/ui/button";
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
import { Input } from "@/components/ui/input";

export default function Page() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Sign in</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <Input placeholder="Email" />
        <Input placeholder="Password" type="password" />
        <Button className="w-full">Continue</Button>
      </CardContent>
    </Card>
  );
}

Keeping components up to date

Components are your code — edit them freely. When the upstream registry changes, pull updates on your terms.

terminal

# See which components have upstream changes
npx softuq diff

# Update all changed components (with confirmation)
npx softuq update

# Update specific components
npx softuq update button card

diff normalizes import paths, so local @/lib/utilsrewrites don’t show as changes.

AI coding skill

Install the Softuq skill so Claude Code (or any agent) writes UI that follows the design-system conventions — typography, spacing, tokens, icons, component patterns.

terminal

# Project-level (.claude/skills/softuq/)
npx softuq skill

# Global (~/.claude/skills/softuq/)
npx softuq skill -g

Theme axes

Six axes, set via SoftuqProvider props or useSoftuq() at runtime. No build step.

Palette (gray tint)

neutralzincstoneslatemauveolive

Accent (brand)

bluevioletemeraldamberredrosecyanorange

Radius

nonesmmdlgfull

Spacing (density)

smmdlg

Font (body)

systemintergeist

Heading font

sansloraplayfairfraunces

Mode (dark / light)

data-theme="dark"data-theme="light"

Available components

accordionalertavatarbadgebreadcrumbbuttoncardcheckboxcodedialogdropdown-menuemptyform-textinputkbdlabelnavigation-menupaginationplaceholderpopoverprogressradiosearchsection-navselectseparatorsheetskeletonsliderspinnersquircletabletabstagtextareatoasttoggletoggle-grouptooltip