kumaran-is/claude-code-onboarding

Iron Law

FETCH THE LIVE GUIDELINES BEFORE REVIEWING ANY FILE. Never apply remembered or assumed rules — always fetch fresh from the source URL. If WebFetch fails, report the failure and do not proceed with guessed rules.

Web Interface Guidelines Review

Audits UI code against Vercel's Web Interface Guidelines. Outputs structured file:line findings.

When to Use This Skill

Load this skill when the user asks to:

• "Review my UI"
• "Check accessibility"
• "Audit design"
• "Review UX"
• "Check my site/component against guidelines"
• Run a design compliance check before a PR

How It Works

1. Fetch guidelines — retrieve the latest rules from the source URL using WebFetch
2. Read files — read the specified files (or ask user which files/pattern to review)
3. Apply rules — check all files against every rule in the fetched guidelines
4. Output findings — report violations in file:line: [rule violated] format

Guidelines Source

Fetch fresh guidelines before each review session:

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

Use WebFetch to retrieve the latest rules. The fetched content contains all rules and output format instructions. Do not cache or remember rules across sessions — always fetch fresh.

Usage

When user provides files or a path pattern:

1. Fetch guidelines from source URL
2. Read the specified files
3. Apply all rules from the fetched guidelines
4. Output findings using the format specified in the guidelines

When no files are specified:

Ask the user: "Which files or directories should I review? (e.g. src/app/features/dashboard/ or *.component.html)"

Output format

Follow the format specified in the fetched guidelines exactly. Default structure:

file:line — [Rule name]: [Description of violation]

Example:

dashboard.component.html:34 — Empty State: No empty state defined for zero-data condition
dashboard.component.html:67 — Focus Management: Interactive element lacks visible focus indicator
order-list.component.ts:89 — Loading State: Async operation has no loading feedback

Failure Handling

If WebFetch fails to retrieve the guidelines URL:

1. Report: "Could not fetch Web Interface Guidelines from source URL. Fetch failed: [error]"
2. Do NOT proceed with guessed or remembered rules
3. Suggest: "Try again, or check network access to raw.githubusercontent.com"

Never fabricate rule findings if the fetch fails.

How This Fits the Review Stack

This skill is the third layer of UI review — run all three for complete coverage:

Layer	Tool	What It Catches
Layer 1 — Design tokens	/lint-design-system	Hardcoded colors, raw spacing, inline typography, touch target violations
Layer 2 — WCAG accessibility	accessibility-auditor agent	Contrast ratios, ARIA labels, keyboard nav, semantic HTML
Layer 3 — Web interface patterns	web-design-guidelines (this skill)	Loading states, empty states, error handling, interaction patterns, focus management

Related Skills

• frontend-design — run BEFORE this skill to establish aesthetic direction and DFII score
• design-system — token compliance enforcement (Angular + Flutter)
• angular-ui-patterns — Angular-specific loading/error/empty state doctrine
• accessibility-audit — WCAG 2.1 AA compliance auditor