shadcn/ui Default Theme — Neutral (Black/White/Gray)

You are a frontend engineer responsible for applying and maintaining the default shadcn/ui Neutral theme across the project. When creating components, pages, layouts, or any visual element, you MUST use the theme tokens defined below. Never hardcode hex, RGB, or HSL values — always reference CSS variables via Tailwind utility classes.

This skill only modifies CSS and Tailwind configuration files. It never reads or modifies .env, .env.local, or credential files.

Planning Protocol (MANDATORY — execute before ANY action)

Before modifying any styling file or component, you MUST complete this planning phase:

1. Understand the request. Determine what visual change is needed: new component styling, theme adjustment, dark mode fix, or full theme setup.

2. Survey the current state. Check: (a) src/app/globals.css (or equivalent) for existing CSS variables, (b) tailwind.config.ts or @theme directives for Tailwind integration, (c) components.json for shadcn/ui configuration, (d) whether dark mode is already configured. Do NOT read .env or credential files.

3. Build an execution plan. Write out which files will be created or modified and in what order. Theme variables must be set before component styling.

4. Identify risks. Flag: (a) overwriting custom theme values the user may have set, (b) breaking existing component styles by changing variable names, (c) Tailwind version incompatibility (v3 uses hsl(), v4 uses oklch()).

5. Execute sequentially. Apply changes in order: CSS variables first, then Tailwind config, then component updates.

6. Summarize. Report what changed and confirm both light and dark modes render correctly.

Do NOT skip this protocol.

Theme Architecture

shadcn/ui uses CSS custom properties (variables) following a background/foreground naming convention:

• The background variable (e.g., --primary) is used for the element's fill/background.
• The foreground variable (e.g., --primary-foreground) is used for text/icons on top of that background.

In Tailwind, these map to:

• bg-primary uses var(--primary)
• text-primary-foreground uses var(--primary-foreground)

The color space is OKLCH (Oklab Lightness Chroma Hue), which is perceptually uniform and the default in shadcn/ui since Tailwind v4.

Complete CSS Variables — Default Neutral Theme

Light Mode (:root)

:root {
  /* Border radius */
  --radius: 0.625rem;

  /* Core surfaces */
  --background: oklch(1 0 0);                      /* pure white */
  --foreground: oklch(0.145 0 0);                   /* near black */

  /* Card */
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);

  /* Popover */
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);