vercel-design-guidelines
SKILL.md
Vercel Design Guidelines
Review web interfaces against Vercel's comprehensive design guidelines and propose fixes.
How It Works
- Read the user's code (components, CSS, HTML)
- Check against Vercel design guidelines (interactions, animations, layout, content, forms, performance, design, copywriting)
- Report violations with specific line references
- Propose concrete fixes with code examples
Usage
When a user asks to review their UI or check against design guidelines:
- Fetch the guidelines from both URLs below
- Read the relevant source files (components, styles, HTML)
- Analyze the code against each applicable guideline category
- Report findings grouped by category with severity
Guidelines URLs:
- Structured rules: https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/refs/heads/main/AGENTS.md (MUST/SHOULD/NEVER directives)
- Full details: https://vercel.com/design/guidelines (rich explanations and examples)
Fetch both for comprehensive coverage — AGENTS.md for structured checklist, full site for context and examples.
Audit Categories
Interactions
- Keyboard accessibility
- Focus management
- Hit targets (minimum 24px, 44px on mobile)
- Loading states
- URL persistence
Animations
- Reduced motion support (
prefers-reduced-motion) - GPU acceleration
- Easing functions
- Interruptibility
- No
transition: all
Layout
- Optical adjustment
- Alignment
- Responsive testing
- Safe areas
Content
- Inline help
- Skeleton states
- Empty states
- Typography
- Accessibility
Forms
- Labels (always associated with inputs)
- Validation
- Autocomplete
- Error handling
- Submit behavior
Performance
- Re-renders
- Layout thrashing
- Virtualization
- Preloading
Design
- Shadows
- Borders
- Border radii
- Contrast (APCA standards)
- Color accessibility
Copywriting
- Active voice
- Title case
- Clarity
- Error messaging (show how to fix, not just what's wrong)
Output Format
Present findings as:
## {Category} Issues
### {Severity}: {Guideline Name}
**File:** `path/to/file.tsx:42`
**Issue:** {Description of the violation}
**Guideline:** {Brief guideline reference}
**Fix:**
```{language}
{Proposed code fix}
Severity levels:
- **Critical**: Accessibility violations, broken functionality
- **Warning**: UX issues, performance concerns
- **Suggestion**: Polish, best practices
## Example Review
Interactions Issues
Critical: Keyboard Accessibility
File: components/Modal.tsx:28
Issue: Modal lacks focus trap - keyboard users can tab outside
Guideline: Implement focus traps per WAI-ARIA patterns
Fix:
// Add focus trap using @radix-ui/react-focus-guards or similar
import { FocusScope } from "@radix-ui/react-focus-scope";
<FocusScope trapped>
<ModalContent>{children}</ModalContent>
</FocusScope>;
Warning: Loading State Duration
File: components/Button.tsx:15
Issue: No minimum loading duration - causes flicker on fast responses
Guideline: Add 150-300ms delay and 300-500ms minimum visibility
Fix:
const [isLoading, setIsLoading] = useState(false);
const minimumLoadingTime = 300;
async function handleClick() {
setIsLoading(true);
const start = Date.now();
await action();
const elapsed = Date.now() - start;
if (elapsed < minimumLoadingTime) {
await new Promise((r) => setTimeout(r, minimumLoadingTime - elapsed));
}
setIsLoading(false);
}
## Quick Checklist
For rapid reviews, check these high-impact items first:
- [ ] All interactive elements keyboard accessible
- [ ] Visible focus rings on focusable elements
- [ ] Hit targets ≥24px (44px on mobile)
- [ ] Form inputs have associated labels
- [ ] Loading states don't flicker
- [ ] `prefers-reduced-motion` respected
- [ ] No `transition: all`
- [ ] Errors show how to fix, not just what's wrong
- [ ] Color contrast meets APCA standards
- [ ] No zoom disabled
## Present Results to User
After reviewing:
Design Guidelines Audit
Reviewed {N} files against Vercel design guidelines.
Summary
- Critical: {N} issues
- Warning: {N} issues
- Suggestions: {N} items
{Detailed findings by category}
Recommended Priority
- {First critical fix}
- {Second critical fix} ...