design-system-audit

Audits UI views and components against a design system for interaction states and native primitives.

15|22|Updated May 5, 2024
One-click install
npx skills add https://github.com/brayandiazc/project-starter-template-es-ai --skill design-system-audit-brayandiazc
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: design-system-audit
Source: https://github.com/brayandiazc/project-starter-template-es-ai/tree/main/.claude/skills/design-system-audit
Command: npx skills add https://github.com/brayandiazc/project-starter-template-es-ai --skill design-system-audit-brayandiazc

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Design system compliance checks that automated scripts cannot perform — such as interaction states, data states, and misuse of custom components instead of native HTML primitives — often go unreviewed, letting inconsistent UI slip into production. ## Core Features & Use Cases - Native Primitive Detection: Flags reinvented components (e.g., a <div>-based modal) and recommends native replacements like <dialog>, <details>, or popover that handle focus, keyboard, and Escape natively. - Interaction & Data State Review: Verifies default, hover, active, and disabled states, plus the four data states (loading skeleton, empty with CTA, error with retry, success) on every data-loading view. - Theme & Hierarchy Checks: Confirms both light and data-theme="dark" themes use tokens correctly and that visual hierarchy communicates importance through spacing and typography. - Use Case: Ask whether a settings view follows your design system, and receive a pass/fail list with file:line references and concrete fixes, such as Modal.tsx:12 — <div role="dialog"> without focus trap; use <dialog>. ## Quick Start Ask the assistant to audit a specific view or component against the design system, for example by requesting a review of whether the settings page follows the design guidelines.

Frequently Asked Questions about design-system-audit

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit a component against a design system?▼

Point the audit at a view or component and it checks interaction states, data states, native primitive usage, theme compliance, and visual hierarchy. The output is a pass/fail list with file:line references and concrete fixes.

What design system issues can automated scripts not catch?▼

Scripts catch raw colors and hardcoded tokens, but not missing loading skeletons, empty states without CTAs, reinvented modal components, or broken visual hierarchy. Those semantic and structural issues require manual-style review.

Does this check color contrast and accessibility?▼

No. Color token violations are handled by a CI script, and measured contrast, focus traps, and screen reader concerns are delegated to a separate accessibility-audit skill. This audit covers states, primitives, themes, and hierarchy.

Why use native HTML elements like dialog instead of custom components?▼

Native elements like <dialog>, <details>, and popover provide focus management, keyboard navigation, and Escape handling built into the browser. A custom div-based component must reimplement all of this and often misses accessibility behavior.

What are the four data states every view should handle?▼

Loading (skeleton matching content shape, not a generic spinner), empty (icon, explanation, and guiding CTA), error (message plus retry action), and success. The empty state is the most commonly skipped and most product-defining.