home / skills / phrazzld / claude-config / audit-design

audit-design skill

Q: What output format does the audit produce?

A standardized list of findings: [SEVERITY] file:line, Issue, Found, Fix, plus a summary with totals and a prioritized fix list.

Q: How are severities assigned?

Critical visual or accessibility regressions (banned callout patterns, hardcoded status colors, banned fonts) are HIGH; missing components or arbitrary colors are MEDIUM; typographic and animation optimizations are LOW.

safe

/skills/heartbeat/audit-design

This skill audits Heartbeat components for Kyoto Moss design system compliance, detecting token violations, banned patterns, typography and animation issues to

npx playbooks add skill phrazzld/claude-config --skill audit-design

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: audit-design
description: |
  Audit Heartbeat components for Kyoto Moss design system compliance.
  Scans for token violations, banned patterns, typography issues, animation problems.
  Use when: checking Heartbeat UI compliance, design system audit, Kyoto Moss violations.
effort: high
---

# Audit Kyoto Moss Design System

Scan Heartbeat components for design system violations.

## Role

Design system auditor enforcing Kyoto Moss conventions.

## Objective

Find and report all design token violations, banned patterns, and accessibility gaps in Heartbeat components.

## Audit Categories

### 1. Token Usage
- `bg-[#...]`, `text-[#...]` arbitrary values
- Tailwind defaults without semantic mapping (`bg-blue-500`)
- Hardcoded `bg-white`, `bg-black`, `text-gray-*`
- Correct: `bg-up`, `bg-degraded`, `bg-down`, CSS variables

### 2. Component Patterns
- Inline implementations instead of `<StatusIndicator />`, `<Button />`, `<Card />`
- Missing `cn()` utility for className composition

### 3. Alert/Callout (CRITICAL)
- **BANNED**: `border-l-* rounded-*` (left border accent + rounded corners)
- Correct: icon-led with background tint, top/bottom border, full outline, or bg-only

### 4. Typography
- `font-sans` without override (should be `font-body`)
- Missing `text-balance` on headlines, `text-pretty` on body, `tabular-nums` on numbers

### 5. Animation
- Custom animation without reduced-motion handling
- `transition-all` (too broad)
- Animations >200ms for interaction feedback

### 6. Status Semantics
- Generic colors for status instead of `up`/`degraded`/`down`
- Missing aria-label on status indicators

## Output

```
[SEVERITY] file:line
  Issue: Description
  Found: Problematic code
  Fix: Suggested correction
```

HIGH: Left-border alerts, hardcoded status colors, banned fonts
MEDIUM: Missing CVA components, arbitrary colors
LOW: Typography improvements, animation optimizations

Summary: total violations by severity, most common types, prioritized fix list.

Overview

This skill audits Heartbeat components for Kyoto Moss design system compliance. It identifies token misuse, banned visual patterns, typography issues, animation problems, and missing accessibility semantics, then produces line-by-line findings and a prioritized summary.

How this skill works

The auditor scans component files for class tokens, inline implementations, banned alert styles, typography classes, animation patterns, and status semantics. For each violation it emits a standardized report entry with severity, location, a concise description, the offending code snippet, and a suggested fix.

When to use it

Before merging UI changes that touch Heartbeat components
During periodic design system compliance sweeps
When onboarding new contributors to enforce Kyoto Moss conventions
Prior to release to ensure accessibility and consistent status semantics
When refactoring components to use shared primitives

Best practices

Use semantic tokens (bg-up, bg-degraded, bg-down, CSS variables) instead of arbitrary hex or Tailwind defaults
Replace inline implementations with shared components like <StatusIndicator />, <Button />, and <Card />
Avoid banned left-border + rounded combos for callouts; use icon-led or full-outline alternatives
Apply typography utilities: font-body, text-balance for headlines, text-pretty for body, and tabular-nums for numeric contexts
Respect reduced-motion and avoid transition-all; constrain animations to <=200ms for interaction feedback
Add aria-labels to status indicators and use semantic status colors rather than generic hues

Example use cases

Run the audit on a feature branch to catch hardcoded colors or banned alert patterns before review
Use the report to prioritize fixes: high severity first (left-border alerts, hardcoded status colors, banned fonts)
Automate the auditor in CI to block merges with critical Kyoto Moss violations
Draft targeted PRs that replace inline classes with componentized implementations and cn() composition
Create a remediation plan showing counts by severity and the most common violation types

FAQ

What output format does the audit produce?

A standardized list of findings: [SEVERITY] file:line, Issue, Found, Fix, plus a summary with totals and a prioritized fix list.

How are severities assigned?

Critical visual or accessibility regressions (banned callout patterns, hardcoded status colors, banned fonts) are HIGH; missing components or arbitrary colors are MEDIUM; typographic and animation optimizations are LOW.