Theme Audit

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 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 (figures illustrative). With CSS scopes, SCSS theme files and JS theme objects, a token not redefined in a theme inherits the default — "not overridden" is not the same as "missing":

Semantic tokens: 156 total
- Overridden in every theme: 118
- Inherit the default in one or more themes: 34 (fine for spacing, radius, type; check colour and shadow)
- Defined only in a non-default theme scope: 4 (undefined in the default theme — a real gap)

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

Inheriting the default is correct for tokens that shouldn't change between themes — spacing, radius, font sizes, durations usually don't. Flag only:

• Theme-dependent tokens that aren't themed — colour, shadow, border colour, and anything else the theme is meant to change, which inherit the default (CSS/SCSS/JS scopes, resolver contexts) or hold the same value as the default (Figma modes). A dark theme inheriting the light --color-text-default is a real gap
• Tokens undefined in some theme — defined only in a non-default scope, or aliasing a target that no resolver set defines, so they don't resolve at all there

If the team has said a token is deliberately the same across themes (a fixed brand colour), treat it as accepted.

Coverage matrix:

Show only the rows with a gap — not every semantic token. Columns are themes. Mark each cell as:

• ✓ Themed (token has its own value in this theme)
• ↳ Inherits default (flag only if the token is theme-dependent)
• ✗ Undefined (token doesn't resolve in this theme)

Summarise gaps per theme (figures illustrative):

Dark theme: 4 theme-dependent tokens not themed (--color-feedback-info, --color-feedback-warning, --color-border-subtle, --shadow-raised)
Brand A: 2 not themed (--color-feedback-warning, --color-action-secondary); 1 undefined (--text-heading-display)
Brand B: no gaps

For each gap, flag:

• Finding ID (e.g. TH-01; the TH- prefix keeps these distinct from token-compliance's TC- findings when both reports are read together)
• Evidence: the file and line (or resolver context, or Figma collection and mode) where the token is defined, and where the theme scope fails to redefine it
• Severity: 🔴 Critical if the token is undefined in a shipped theme, or a component token consumes it without its own per-theme override; 🟠 High if used by multiple components; 🟡 Medium if used by few components; ⚪ Low if no in-repo consumers were found
• Description: Semantic token [name] is not defined in [theme]
• Impact: Which components depend on this token and may render incorrectly
• Recommended action: Define the token in the missing theme. If the token should not apply to this theme, document that decision.

Step 3: Component tier propagation check

Tier leakage as an architectural finding belongs to token-audit. If a token-audit report exists for this system, take its list of component tokens that reference primitives and don't re-derive it; cite the finding IDs. What this skill adds is the theming consequence: whether each leaking token is overridden per theme, and what breaks if it isn't. Report each leak once, here, in those terms.

Verify that component tokens correctly inherit from the semantic tier across all themes:

For each component token:

1. Trace its reference — does it point to a semantic token, or to a primitive?
2. If it points to a primitive: this is tier leakage. The component token bypasses theming.
3. If it points to a semantic token: verify that the semantic token has values defined in all themes where the component is used.

Tier leakage detection:

Flag any component token that references a primitive (rather than a semantic token):

TH-10 | 🔴 Critical | Tier leakage | button.background.default references {color.blue.500} (primitive) instead of semantic tier, with no per-theme override (tokens/component.tokens.json:14)
- Impact: Button background will not change on theme switch (dark mode will show blue on blue)
- Recommended action: Redefine as button.background.default: {color.action.primary}

Quantify the scope:

Component tokens examined: 287
- Correctly reference semantic tier: 276
- Tier leakage (reference primitives): 11

Tier leakage is the most dangerous category of theme bug — everything appears to work until someone activates a new theme. It's 🔴 Critical only when the component token isn't itself overridden per theme. If each theme sets its own value for the component token, theming works; the leakage is then a 🟡 Medium maintenance finding (every new theme has to remember that override).

Step 4: Visual consistency check within each theme

For each theme, validate internal logical consistency:

Consistency rules (apply per theme, not across themes):

For every theme, compute contrast from resolved values (follow aliases to the final colour in that theme) rather than judging by name. The baseline is WCAG 2.2 AA: 4.5:1 for body text, 3:1 for large text and for non-text elements such as borders, focus indicators and icons. (Some legal baselines, e.g. EN 301 549, still reference WCAG 2.1 AA; use that if it's the team's obligation.)

Compute ratios in sRGB. Convert OKLCH, Lab, LCH and Display P3 values to sRGB first, and say when a value was out of gamut and clipped. A colour with alpha has no contrast ratio on its own: composite it over the background it sits on before computing, and if that background isn't known from the tokens, report the ratio as not computed rather than guess. Every consistency finding names the tokens, their resolved values in that theme, and the file and line (or Figma collection and mode) they came from.

For light theme:

• Raised surfaces are usually lighter than or equal to the page background, separated by border or shadow
• Text colours meet the contrast baseline against the backgrounds they're used on
• Action colours should be visually distinct from neutral colours
• Hover states should be visually different from default states (e.g. darker, not lighter)

For dark theme:

• Raised surfaces should be lighter than the base background — elevation reads as lightness in dark themes, since shadows barely show. A surface darker than the background reads as sunken
• Text colours meet the contrast baseline against dark backgrounds
• Action colours may need adjustment to maintain contrast in dark mode

For brand variants: run the same checks per brand. The one brand-specific check is that feedback colours (error, success, warning) stay distinguishable from that brand's primary action colour: compute the contrast between each pair, and flag below 3:1, because a brand whose primary is red makes error states invisible.

Consistency violations to flag:

Run visual spot-checks on high-impact token groups:

• Does color.feedback.error meet 4.5:1 (as text) or 3:1 (as an icon or border) against color.background.default in this theme, computed from resolved values?
• Are color.surface.primary and color.background.default visually distinct (same value is sometimes OK, but should be documented as intentional)?
• Is color.action.primary visually more prominent than color.action.secondary in this theme?

Flag violations:

TH-22 | 🟡 Medium | Consistency | Dark theme: color.background.default and color.surface.primary are identical (#121212) (src/styles/tokens.css:41,44)
- This may be intentional (both are neutral backgrounds), but it reduces visual hierarchy
- Recommended action: Review with design team. If intentional, document the decision. If not, adjust surface token.