/theme-audit

name: theme-audit
description: "Audit theme coverage and consistency across a design system's semantic and component token tiers. Triggers: audit my themes, check theme coverage, are all tokens defined across themes, dark mode audit, brand variant check, do themes have parity, theme consistency check, light/dark token coverage, or anything about whether themes are complete and internally consistent. Use this when launching a new theme, after a rebrand, adopting dark mode, or when token-audit reveals tier leakage that defeats theming."
references:
  - ../../knowledge-notes/token-architecture.md

Theme audit

A skill for auditing theme coverage and visual consistency across multiple design system themes. Identifies tokens missing from specific themes, component tier propagation failures, internal consistency violations within each theme, DTCG resolver coverage gaps, and components likely to break on theme switches. Produces a theme coverage report with severity-rated findings.

Context

Theming is where the three-tier token architecture proves its value or reveals its failures. When a system switches themes correctly, the change ripples through every component that references the semantic tier. When it does not — when components hardcode primitives or when the semantic tier is incomplete — a theme switch becomes a hunt through hundreds of files for missed overrides.

A theme audit is not about validating a single theme's visual appearance. It is about ensuring every token consumed by every component exists and is correctly defined across every theme the system claims to support. It is about catching cases where the component tier skips the semantic tier entirely, making theme switches invisible to that component.

The audit surfaces three categories of problems: coverage gaps (token defined in Theme A but not Theme B), architectural failures (component tokens that bypass the semantic tier), and internal consistency breaks (within a single theme, visual logic is violated — e.g. in dark mode, surface colours are lighter than background).

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `system.theming` — if false, exit early with a note that this skill applies only to systems with theming enabled. If true, proceed.
• `severity.*` — overrides for theme-specific findings (e.g. `missing_theme_value: critical` for a system about to launch dark mode)
• `integrations.style_dictionary` — if enabled, parse tokens via Style Dictionary v4 to auto-extract all semantic and component tokens and their resolver-defined mode values
• `integrations.figma` — if enabled, pull Figma variables and their modes as the theme source
• `recurring.*` — if this is a recurring run, load the previous theme audit for trend comparison

If no config file exists, proceed with defaults and ask for manual input.

Step 0: Theme discovery and scope

Before auditing, discover what themes the system actually defines:

**Discover themes:** 1. **Resolver files** — if DTCG format, scan the project for `.resolver.json` files and extract mode names (e.g. `light`, `dark`, `brand-a`, `brand-b`) 2. **CSS custom property scopes** — if using CSS variables, scan for theme selectors like `:root`, `.dark`, `[data-theme="light"]`, `[data-theme="dark"]`, `[data-brand="brand-a"]` — each scope is a theme variant 3. **SCSS variable maps** — if using SCSS, look for `$themes: (...)` or separate theme files (`_theme-light.scss`, `_theme-dark.scss`) 4. **JavaScript theme objects** — if using CSS-in-JS, look for exported theme objects or theme switching functions (e.g. `export const lightTheme = { ... }; export const darkTheme = { ... }`) 5. **Tailwind mode declarations** — check `tailwind.config.js` or `tailwind.config.ts` for `darkMode` configuration and any theme extends 6. **Figma modes** — if Figma integration is configured, list all variable modes in the linked file

**Present discovered themes to user:**

Produce a brief inventory:

Themes discovered:
- Light (default, CSS root scope, Figma mode)
- Dark (CSS .dark scope, Figma mode)
- Brand A (data-theme="brand-a" scope)
- Brand B (data-theme="brand-b" scope)
Total: 4 themes

Ask: "I found these [N] themes. Should I audit all of them, or focus on specific variants?"

If no themes are discovered and theming is marked as `true` in config, ask the user to name the themes they intend to support.

Step 1: Identify tokens in scope

Gather the semantic and component tiers across all discovered themes:

**For DTCG format:**

• Parse resolver files and extract all semantic tokens and their mode-specific values
• Extract all component tokens and their mode-specific values
• Verify that every token in every set has values defined for every declared mode

**For CSS custom properties:**

• Extract `:root` (or default theme scope) as the reference set of all semantic tokens
• Extract theme-scoped selectors (`.dark`, `[data-theme="dark"]`, etc.) and their token definitions
• Map which tokens are defined in each scope

**For SCSS variables:**

• Extract variables from the base/default theme file as the reference set
• Extract variables from each theme file
• Identify which variables are redefined per theme

**For JavaScript theme objects:**

• Extract the reference theme object's keys as the token inventory
• For each theme variant, identify which tokens are redefined

**For Tailwind:**

• Extract `theme` and `darkMode` blocks
• Identify which theme values are overridden in each mode
• Note which breakpoints or variants redefine token values

Output a token inventory:

Semantic tokens: 156 total
- Defined in all themes: 144
- Defined in light only: 5
- Defined in dark only: 4
- Defined in brand-a only: 3

Component tokens: 287 total
- Defined in all themes: 278
- Coverage gaps: 9

This checkpoint reveals the scale of coverage problems before the detailed audit.

Step 2: Theme coverage check

For each semanti