Skip to main content
skill CX Codex

component-state-auditor — Claude Code skill: what it does

The component-state-auditor skill for Claude Code compares documented component states against a versioned rubric in rubric.json. It identifies missing states during UI development and review.

MIT ★ 529 updated 2026-11-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ShuaiMXu/happyhands --skill component-state-auditor -a claude-code
Open on GitHub

What component-state-auditor does

This skill automates component auditing by matching documented states against rules defined in a local rubric.json file. It separates the analysis into two tiers: checking project documentation against class requirements and scanning component source files for evidence of states.

Successful execution requires a rubric.json file beside the component files, containing expected state sets for classes like async-task-item, collection, or interactive-control. Without this rubric, the skill cannot validate component completeness.

The auditor reports discrepancies such as states present in the source but missing from the design foundation. It does not verify accessibility, keyboard navigation, or runtime visual state correctness.

What it helps with

  • Validate documented component states against project requirements
  • Detect states implemented in code but missing from documentation
  • Identify missing lifecycle scenarios for async-task-item components

Example prompts for the agent

  • Audit the Button component using component-state-auditor
  • Run component-state-auditor against the components/ directory to check for missing states

How to install component-state-auditor

1Skills CLI (Vercel)

npx skills add ShuaiMXu/happyhands --skill component-state-auditor -a claude-code

2Manually: put the files in place

~/.claude/skills/component-state-auditor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/component-state-auditor/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about component-state-auditor

How do I install component-state-auditor in Claude Code?

Run npx skills add ShuaiMXu/happyhands --skill component-state-auditor -a claude-code in your project terminal.

What does this skill do?

It checks if required component states are documented and implemented, using a rubric.json configuration as a reference.

What are the requirements?

You must provide a rubric.json file in your project defining expected states and have your component source code ready for analysis.

Source text

SKILL.md · MIT
---
name: component-state-auditor
description: "Audit documented components against a versioned rubric of the states their class has to be able to express."
---

# Component State Auditor

A surface that renders only its success state is not finished. The states nobody drew are the ones that decide whether a person can keep working: the queue before anything happens, the half-finished run, the failure with no way back.

## Required evidence

- a design foundation with components
- component sources
- `rubric.json` beside this file, which holds the required state sets

## The rubric

`rubric.json` names classes of component and what each class has to be able to express. A class is matched from the component name. The default rubric ships three classes:

- **async-task-item** — a unit of work the product performs over time (a generation, render, upload, export, job). Requires `empty`, `pending`, `in-progress`, `complete`, `needs-review`, `failed`, plus a stated failure reason and a retry. Work that takes time fails, partially succeeds, and produces output a person has to check before trusting it.
- **collection** — a list, table, grid or feed. Requires `empty`, `in-progress`, `complete`, `failed`, plus a stated failure reason. A collection is empty before it is full, and its empty state is the first thing a new user sees.
- **interactive-control** — a button, input, select, toggle or field. Requires `default`, `disabled`, `in-progress`.

The required sets are the judgement of this Skill version, not a universal rule. A project with different classes of component replaces `rubric.json`, and every result records which rubric version produced it.

## Two tiers, kept apart

**Documented.** The states a component declares in the foundation, compared with what its class requires. A data comparison with nothing inferred, so it can be stated plainly: this component documents four states and its class requires six.

**Observed.** State words found in the component's source. This is evidence, never proof. The absence of a word is not the absence of a state, and the presence of one is not a state that works. Report it at low confidence, with the file it came from, for a person to check.

A state the source shows but the foundation does not document is its own result: the implementation moved and the documentation did not.

## Decisions

- Check only the states the component's class needs. A component that matches no class has nothing required of it, and that is reported rather than filled in with a default set.
- Cite the source path and the words found, so a reviewer can confirm or dismiss each one quickly.
- Leave the direction open. A missing state may belong to another component, or the class may be wrong; the audit names the gap and records `add-the-state`, `document-the-state` or `reclassify-the-component` as an unresolved choice.
- Do not add decorative states without a user need.

## Boundary

Source analysis cannot prove that a runtime state is reachable, correct or accessible. Keyboard focus, screen-reader behaviour and visual treatment of each state remain outside this audit.

Match the recorded repository-relative source path exactly. A legacy path without an extension may match one unique implementation at that same path; a same-named file in another directory or an ambiguous extension is not evidence. Missing sources and truncated snapshots keep the result `needs-evidence`, while preserving the documented-state comparison. The release regression corpus covers documented controls, missing states, wrong same-named sources, ambiguous implementations and missing/truncated inputs; it does not establish runtime state quality or operational maturity.

For an offline HTML bundle, scan only its explicit decoded JSON template using the shared source decoder. Preserve template coordinates and the enclosing source identity. Loader code and manifest payloads are not component state or recovery evidence. An unreadable template stays unavailable, with its decoding error; never fall back to scanning the outer bundle. Template text still provides only static candidates, not proof of rendered behaviour.

Return structured evidence, findings, proposed updates and limitations. Use `needs-evidence` when required inputs or professional review are missing. Never invent an Experience Score or promote a project observation into a universal rule.

© ShuaiMXu · MIT · ShuaiMXu/happyhands

Similar skills

All skills for Frontend and UI →

From the same set34

The whole set →
token-contrast-auditor The token-contrast-auditor skill for Claude Code verifies color pair contrast against WCAG standards. It runs during project analysis to check design tokens and CSS styles. CX Codex +1 ★ 529repo stars pattern-library-curator pattern-library-curator is a Claude Code skill that gathers accepted interface solutions into a project pattern library. It checks recurring decisions for evidence before they are treated as reusable patterns. CX Codex +1 ★ 529repo stars design-system-drift-detector The design-system-drift-detector skill for Claude Code identifies discrepancies between implementation and design tokens. It detects ungoverned literals, semantic conflicts, and off-scale values. CX Codex +1 ★ 529repo stars fix-planner fix-planner is a Claude Code skill that turns a confirmed finding into a bounded change plan. It ties proposed fixes to project evidence and approved design decisions. CX Codex +1 ★ 529repo stars visual-hierarchy-reviewer visual-hierarchy-reviewer is a Claude Code skill that reviews task hierarchy and design language from screenshots. It runs on interface reviews, including requests to reduce an AI-made look while keeping the product’s brand. CX Codex +1 ★ 529repo stars review-video review-video is a Claude Code skill that inspects and repairs product or promotional videos using original assets, before/after evidence, and timeline reviews. Runs during video audits and defect fixes. CX Codex +1 ★ 529repo stars happyhands happyhands is a Claude Code skill that investigates a specific UI or product-experience issue and guides a repair. Explicit requests for product or promotional video work go through a separate timestamped workflow. CX Codex +1 ★ 529repo stars frontend-design The frontend-design skill for Claude Code enforces interface styling and typography standards. It runs during the creation or review of web UI components. CX Codex +1 ★ 529repo stars

Project sponsors

Companies that keep this analytics open