Design System & Styling

The file DESIGN.md in the repo root is the source of truth for how the product looks. It holds the design tokens (colors, typography, spacing, radii, elevation, motion) at the top as YAML, plus plain rules for interaction and layout below.

DESIGN.md changes when the product identity or design changes. When you start a new product from this template, branding writes a new DESIGN.md for that product. Do not ship the template demo tokens as your brand.

How the pieces connect

DESIGN.md is where visual decisions get made. Nothing else authors them.

apps/web/app/globals.css puts those decisions into code. Its :root and .dark variables and the Tailwind v4 @theme block copy the tokens. It mirrors the file above. It is not a second system.

apps/web/modules/ui/components holds the reusable parts (Button, Card, Dialog, and the rest), built on those tokens. Extend these parts instead of inventing styles on a page.

When you want a visual change, edit DESIGN.md first, then apply it to the CSS and the parts. Never paste raw hex colors into components. Use bg-primary, text-foreground, border-border, ring-ring, and similar names.

VibeKit uses Tailwind CSS v4 with CSS custom properties and Radix UI primitives.

Design aesthetic

• Developer-first aesthetic: Crisp dark surfaces, clean typography, monospace code labels, and subtle borders.
• Theme support: System theme by default with light and dark theme support powered by next-themes.
• Motion & animations: Tasteful micro-transitions with tailwindcss-animate.

CSS variables (globals.css)

Colors and UI tokens are defined as CSS variables in apps/web/app/globals.css:

@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-border: var(--border);
}

Theme toggle

Use the next-themes hook to let users switch between light, dark, and system themes:

"use client";

import { useTheme } from "next-themes";
import { Button } from "@ui/components/button";

export function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <Button
      variant="outline"
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
    >
      Toggle theme
    </Button>
  );
}

See the available component library in UI Components.