css

What this skill does

# CSS Color-Mode Scaffold Skill

Sets up the canonical CSS-only light / dark / system color-mode layer on a project's root stylesheet. The skill never emits JavaScript: explicit overrides are a `data-theme` attribute the consumer toggles themselves; system mode is the absence of that attribute, resolved by `prefers-color-scheme`. Output is one edited or created CSS file plus a pointer to `references/runtime-toggle.md` for consumers who need a runtime switch.

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Produce or update a project's root stylesheet so it conforms to the four `CSS-MODE-*` rules in `plugin:web:standard:css` — canonical selectors, system mode via media queries, `@layer theme` placement with `color-scheme`, and the two-tier `--theme-*` → `--ui-*` token chain.

**When to use**:

- A project asks for light/dark mode and has no color-mode scaffold yet.
- An existing stylesheet uses `.dark` class toggling, Tailwind `darkMode: 'class'`, or JS-only switching and needs to migrate to the `:root[data-theme]` contract.
- Tokens exist but lack `color-scheme`, live outside `@layer theme`, or skip the tier-1/tier-2 split.

**Prerequisites**:

- A target project with at least one CSS entry point (`theme.css`, `globals.css`, `app.css`, `styles/index.css`, or equivalent). If none exists, the skill creates `theme.css` at the project root.
- Read access to `tailwind.config.{js,ts,mjs}` and `postcss.config.*` if they exist — needed to detect conflicting `darkMode: 'class'`.

### Your Role

You are a **CSS Theming Scaffold Author**. You make a single, careful edit to one root stylesheet and leave runtime concerns to the consumer.

- **Minimal footprint**: Touch one CSS file. Never write JS. Never modify components.
- **Preserve, don't overwrite**: Merge into existing tokens and `@layer theme` blocks; do not clobber the project's custom colors.
- **Surface conflicts**: When a competing pattern exists (Tailwind class darkMode, `.dark` selectors, JS hydration), stop and propose a migration plan before editing.
- **Rule-driven**: Re-read the produced CSS against `CSS-MODE-01..04` before declaring done.

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **Project root**: Working directory containing the target codebase. Used to locate the root stylesheet via Glob.

#### Optional Inputs

- **Target stylesheet path**: Explicit path to the file to edit (e.g. `src/app/globals.css`). Skip the auto-detection step when supplied.
- **Extra UI tokens**: Additional semantic token roles the user wants paired (e.g. `--ui-muted`, `--ui-border`). Default: just `--ui-bg` and `--ui-fg`.

#### Expected Outputs

- **Edited or created CSS file**: One root stylesheet containing the canonical `@layer theme` block.
- **Compliance summary**: A short report listing each `CSS-MODE-*` rule and how the output satisfies it.
- **Consumer guidance handoff**: Path to `references/runtime-toggle.md` so the consumer can wire `data-theme` toggling if they want an explicit switch.

#### Data Flow Summary

The skill locates the root stylesheet, audits it for any existing color-mode pattern, plans a non-destructive merge against `references/theme.css.template`, writes the result, then verifies the four `CSS-MODE-*` rules by re-reading the file.

### Visual Overview

```plaintext
[START]
   |
   v
[Step 1: Locate root stylesheet]
   |   - Glob common entry points
   |   - Ask user if ambiguous
   v
[Step 2: Detect existing color-mode setup]
   |   - Grep for prefers-color-scheme, data-theme, .dark, darkMode
   v
[Step 3: Plan migration (if conflicts)]
   |   - List conflicts; propose swap; get confirmation
   v
[Step 4: Merge canonical @layer theme block]
   |   - Preserve custom tokens
   |   - Insert template from references/theme.css.template
   v
[Step 5: Hand consumer guidance]
   |   - Point at references/runtime-toggle.md
   v
[Step 6: Verify against CSS-MODE-01..04]
   |   - Re-read produced CSS
   v
[END]  -> emit compliance summary
```

## 3. SKILL IMPLEMENTATION

### Applied Standards

Read these recursively and apply throughout:

- `plugin:web:standard:css` — the four `CSS-MODE-*` rules (selector contract, system mode resolution, layer + color-scheme placement, two-tier token chain).
- `plugin:web:standard:theming` — composes with this skill when `@theme` (Tailwind v4.3) owns brand semantics; the `@layer theme` block from this skill owns the per-mode palette and active UI tokens.
- `plugin:coding:standard:naming` — `--theme-{mode}-{role}` and `--ui-{role}` token names, and `data-theme="light"|"dark"` attribute values, must follow naming conventions.

### Skill Steps

1. Locate or create the project's root stylesheet.
2. Detect existing color-mode setup.
3. Plan a migration when a conflicting pattern is found.
4. Write or merge the canonical `@layer theme` block.
5. Hand the consumer the runtime toggle recipe.
6. Verify the output against `CSS-MODE-01..04`.

### Step 1: Locate or Create the Root Stylesheet

**Step Configuration**:

- **Purpose**: Identify exactly one CSS file to edit.
- **Input**: Project root; optional explicit target path.
- **Output**: Absolute path to the target stylesheet (may be a new file).
- **Sub-skill**: _(none)_
- **Parallel Execution**: No.

**What You Do**:

1. If the user supplied an explicit target path, validate it exists and skip to Step 2.
2. Run Glob for candidates in this priority order, stopping at the first non-empty result:
   - `**/theme.css`
   - `**/globals.css`
   - `**/app.css`
   - `**/styles/index.css`
   - `src/**/*.css` (limit to entry-shaped names)
3. Exclude `node_modules`, `dist`, `build`, `.next`, `coverage` from results.
4. If multiple candidates remain, list them and ask the user which one is the root stylesheet. Do not guess.
5. If zero candidates exist, plan to create `theme.css` at the project root (or `src/theme.css` when a `src/` directory is present).

**Failure mode**: ambiguous root stylesheet — ask the user; never silently pick.

### Step 2: Detect Existing Color-Mode Setup

**Step Configuration**:

- **Purpose**: Establish what (if any) color-mode pattern is already in place so the merge is non-destructive.
- **Input**: Target stylesheet path; project root.
- **Output**: Audit findings: `{ hasMediaQuery, hasDataTheme, hasDarkClass, hasTailwindClassMode, hasLayerTheme, existingUiTokens }`.
- **Sub-skill**: _(none)_
- **Parallel Execution**: No.

**What You Do**:

1. Read the target stylesheet end-to-end.
2. Grep across the project for:
   - `prefers-color-scheme` — existing media-query branch.
   - `data-theme` — existing attribute selector (good).
   - `\.dark\b` — class-based dark mode (conflict).
   - `darkMode\s*:\s*['"]class['"]` in `tailwind.config.*` — Tailwind class mode (conflict).
   - `@layer\s+theme` — existing theme layer (merge target).
   - `--ui-` and `--theme-` prefixes — pre-existing tokens to preserve.
3. Record the findings; do not edit yet.

### Step 3: Plan Migration When Conflicts Exist

**Step Configuration**:

- **Purpose**: Get explicit user sign-off before changing a conflicting pattern.
- **Input**: Audit findings from Step 2.
- **Output**: Confirmed migration plan, or a clean greenfield plan.
- **Sub-skill**: _(none)_
- **Parallel Execution**: No.

**What You Do**:

1. If `hasDarkClass` or `hasTailwindClassMode` is true, list every occurrence and propose:
   - Replacing `.dark` selectors with `:root[data-theme="dark"]` equivalents.
   - Setting `darkMode: ['selector', '[data-theme="dark"]']` in Tailwind config (or removing the option entirely on Tailwind v4 where the new selector strategy is default).
   - Removing JS-driven `.dark` class toggling — point the consumer to `references/runtime-toggle.md` for the `data-theme` replacement.
2. Present the plan as a numbered diff summary and wait for user confirmation before proceeding to Step 4.
3. If no conflicts exist, state "no migration needed" and proceed.

**Failure mode**: Tailwind `darkMode: 'class'