What is the theme-audit skill?
The theme-audit skill is a SKILL.md in murphytrueman/design-system-ops. Ask your AI coding agent for a dark mode audit and it finds each theme, builds a coverage matrix, checks contrast within each theme, flags theme-switch regressions and writes severity-rated findings.
The theme-audit skill is a SKILL.md in murphytrueman/design-system-ops, a skill pack for the work that keeps a design system alive. It audits theme coverage and visual consistency across the multiple themes a design system defines.
It identifies tokens missing from specific themes, component tier propagation failures, consistency violations within each theme, DTCG resolver coverage gaps and components likely to break on theme switches. The output is a theme coverage report with severity-rated findings.
Three kinds of problems
- Coverage gaps: a token is defined in Theme A but not in Theme B.
- Architectural failures: component tokens that bypass the semantic tier.
- Internal consistency breaks: within one theme, visual logic is violated, such as a dark mode raised surface that is darker than the base background.
How it finds your themes
Step 0 discovers the themes before auditing. It scans resolver files, CSS custom property scopes, SCSS variable maps, JavaScript theme objects, Tailwind darkMode configuration and Figma variable modes, then asks whether to audit all of them or specific variants.
Who the theme-audit skill is for
Best for
- Systems that define more than one theme, such as light, dark and brand variants, and want parity checked.
- Triggers named in its description: dark mode audit, theme coverage and brand variant parity.
- Token sources in DTCG format, CSS custom properties, SCSS variables, JavaScript theme objects, Tailwind or Figma modes.
Not for
- Checking whether tokens are defined well, which the token-audit skill in the same pack handles.
- Tonal elevation instead of shadows, moderate contrast targets and flash-free theme switching, which the dark-mode-design-expert skill covers.
- Building a seven category design token system with light and dark themes and RTL support, which the theming-components skill covers.
- Scoring a whole design system on coverage, tokens, docs, accessibility and adoption, which the design-system-audit skill covers.
- Auditing a Figma design, a live page or a description against WCAG 2.1 AA, which the accessibility-review skill covers.
How to install Theme Audit Skill: Theme Parity and Token Coverage
git clone https://github.com/murphytrueman/design-system-ops.git ~/.claude/skills/design-system-opsClone the pack
Run the command above to clone the repository into your skills directory. It holds the theme-audit skill along with the rest of the pack.
Or install per project
Clone the same repository into your-project/.claude/skills/design-system-ops. A project level install only loads once you trust the project folder, then run
/reload-plugins.Confirm it loaded
Run
claude plugin listand look fordesign-system-ops@skills-dirwith status loaded.Run the audit
Ask your agent for a dark mode audit, a theme coverage check or brand variant parity, and point it at your token source.
Check that it loaded
Run claude plugin list and look for design-system-ops@skills-dir with status loaded.
Key features
- Theme discoveryFinds themes from resolver files, CSS custom property scopes, SCSS variable maps, JavaScript theme objects, Tailwind darkMode and Figma modes, then lists them for you to confirm.
- Token inventoryCounts semantic and component tokens, and separates tokens overridden in every theme from those that inherit the default and those defined only in a non-default scope.
- Coverage matrixShows only the gap rows, with a mark for each theme: themed, inherits default or undefined.
- Inheritance treated correctlyInheriting the default is correct for spacing, radius, font sizes and durations. Colour, shadow and border colour that inherit the default are flagged.
- Tier leakage checkFlags a component token that references a primitive instead of a semantic token, and rates it Critical only when no per-theme override exists.
- Contrast within each themeComputes contrast from resolved values against WCAG 2.2 AA: 4.5:1 for body text and 3:1 for large text and non-text elements.
- Brand feedback colorsFor brand variants, checks that error, success and warning colors stay distinguishable from the brand's primary action color, flagging pairs below 3:1.
- DTCG resolver validationReads resolver contexts for what each does with theme-dependent tokens, and finds token files that no resolver set includes.
- Switch regression patternsSearches for hardcoded values, rgba(var()) opacity patterns, calc() on token values, inline style theme assumptions and missing component variants.
- Tiered report with trendFindings carry TH- IDs and severities, end in a three tier remediation priority and a Scope block, and compare against the previous audit on recurring runs.
Frequently asked questions
What is the theme-audit skill?
It is a SKILL.md in the murphytrueman/design-system-ops repository. Your AI coding agent uses it to audit theme coverage across the themes a design system defines, then writes a theme coverage report with severity-rated findings, evidence for each finding and a remediation priority.
How do I install theme-audit?
Run the git clone command shown on this page to place the repository at ~/.claude/skills/design-system-ops, or clone it into your-project/.claude/skills/design-system-ops for a project level install. Then run claude plugin list to see design-system-ops@skills-dir with status loaded. A project level install loads once you trust the project folder, followed by /reload-plugins.
What does theme-audit check?
It checks three categories of problems. Coverage gaps are tokens defined in one theme but not another, architectural failures are component tokens that bypass the semantic tier, and internal consistency breaks are cases where visual logic is violated inside a single theme.
Does an inherited token count as missing?
Not by default. Inheriting the default is correct for tokens that should not change between themes, such as spacing, radius, font sizes and durations. The skill flags theme-dependent tokens, such as colour, shadow and border colour, that inherit the default, and tokens undefined in some theme.
How does theme-audit check contrast?
For every theme it computes contrast from resolved values, following aliases to the final colour in that theme. The baseline is WCAG 2.2 AA, with 4.5:1 for body text and 3:1 for large text and for non-text elements such as borders, focus indicators and icons.
What happens when theming is off in the config?
If a .ds-ops-config.yml file sets system.theming to false, the skill exits early with a note that it applies only to systems with theming enabled. If the value is true, it proceeds with the audit. When no themes are discovered and theming is true in the config, it asks you to name the themes you intend to support.
Which regressions does theme-audit look for?
It looks for five patterns likely to break on a theme switch. These are hardcoded values in component code, rgba(var()) opacity hacks, calc() on token values that fails when a theme defines the token as a unitless number, inline styles with theme assumptions, and missing component variants for theme-specific rendering.
Which themes does theme-audit discover?
Step 0 discovers the themes before auditing. It scans DTCG resolver files, CSS custom property scopes, SCSS variable maps, JavaScript theme objects, Tailwind darkMode configuration and Figma variable modes. It then lists what it found and asks whether to audit all of them or focus on specific variants. If none are found and theming is true in the config, it asks you to name them.