/theme-audit

name: theme-audit
description: "Audit theme parity: tokens missing or unchanged per theme, component tokens bypassing semantics, contrast within each theme, resolver contexts, theme-switch regressions. Triggers: dark mode audit, theme coverage, brand variant parity. For general token structure use token-audit."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(grep:*), Bash(rg:*)
references:
  - ../../knowledge-notes/token-architecture.md
  - ../../knowledge-notes/output-discipline.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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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, a raised surface that's darker than the base background, which reads as sunken).

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `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` — parse tokens via Style Dictionary (4 or 5) to extract all semantic and component tokens and their per-context values
• `integrations.figma` — Figma variables and their modes as the theme source
• `recurring.*` — the previous theme audit, for trend comparison

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 read each modifier's `contexts` (e.g. a `theme` modifier with `light` and `dark`, a `brand` modifier with `a` and `b`). Each context is a theme; the spec calls them contexts, not modes 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 each resolver's `sets`, `modifiers` and `resolutionOrder`. Resolve the default (the sets, plus each modifier's `default` context, in resolution order) to get the reference set of semantic and component tokens
• For every other context, list which tokens its sources redefine. Everything else inherits the earlier value in the resolution order; that is how resolvers work, not a gap
• Note any alias whose target is defined in no set at all: that token never resolves in any context

**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 SCS