Learning Web Design Best Practices from Vercel's Guidelines Skill: A Practical Case Study

Introduction

In our previous article “Agent Skills as Best Practices”, we explored how Agent Skills represent codified SOPs that can accelerate learning. But theory is one thing—seeing it in action is another.

Today, we’re going to dive deep into a concrete example: Vercel’s web-design-guidelines skill. This skill perfectly illustrates why learning through skills is so powerful. It’s not just a tool for AI agents—it’s a masterclass in web design and accessibility, distilled from years of real-world production experience.

What is the web-design-guidelines Skill?

Source: vercel-labs/agent-skills

The web-design-guidelines skill is a Vercel-authored Agent Skill that reviews UI code for compliance with their internal Web Interface Guidelines. What makes it remarkable is its scope and depth:

• 50+ specific rules across 8 major categories
• Covers: Accessibility, Forms, Animation, Typography, Performance, Navigation, Touch & Interaction, and Dark Mode
• Actionable: Each rule is specific and testable
• Battle-tested: Reflects Vercel’s experience building products used by millions

This isn’t just a checklist—it’s Vercel’s accumulated wisdom on building accessible, performant, and polished web interfaces.

How the Skill Works

The skill follows a simple but elegant workflow:

1. Fetch the latest guidelines from Vercel's repository
2. Read the specified files to review
3. Check against all rules in the guidelines
4. Output findings in a terse file:line format

Key innovation: The skill fetches fresh guidelines before each review. This means as Vercel updates their practices, your skill stays current automatically. You’re always learning from their latest thinking.

What This Skill Teaches Us

Let’s examine some of the best practices encoded in this skill and what we can learn from them.

1. Accessibility: Non-Negotiable Foundations

Vercel treats accessibility as foundational, not an afterthought. Consider this rule:

## Focus States
- Interactive elements need visible focus: focus-visible:ring-* or equivalent
- Never outline-none / outline: none without focus replacement
- Use :focus-visible over :focus (avoid focus ring on click)
- Group focus with :focus-within for compound controls

What this teaches: Accessibility isn’t optional—it’s core to good UX. But it’s nuanced:

• Don’t remove focus indicators (outline-none)
• Show focus only for keyboard users (:focus-visible)
• Handle compound controls (:focus-within)

This single rule encapsulates years of accessibility work. Without this skill, you might learn this through trial and error, user complaints, or painful audits. With it, you get the answer immediately.

Practical example:

// Bad: No focus indication
<button className="focus:outline-none">Click me</button>

// Good: Keyboard-visible focus ring
<button className="focus-visible:ring-2 ring-blue-500">
  Click me
</button>

// Better: Compound control with group focus
<div className="focus-within:ring-2 ring-blue-500">
  <input type="text" />
  <button>Submit</button>
</div>

2. Forms: The Devil’s in the Details

Forms are where web apps succeed or fail. Vercel’s guidelines show deep attention to detail:

## Forms
- Inputs need autocomplete and meaningful name
- Use correct type (email, tel, url, number) and inputmode
- Never block paste (onPaste + preventDefault)
- Labels clickable (htmlFor or wrapping control)
- Disable spellcheck on emails, codes, usernames (spellCheck={false})
- Checkboxes/radios: label + control share single hit target (no dead zones)

What this teaches: Great forms think about:

• User experience: Correct keyboards on mobile (inputmode)
• Accessibility: Screen reader support (name, htmlFor)
• Convenience: Don’t block paste—let users work efficiently
• Polish: Disable spellcheck where inappropriate

Real-world impact:

// Before: Basic form
<input type="text" placeholder="Email" />
<button>Submit</button>

// After: Following Vercel's guidelines
<input
  type="email"
  inputMode="email"
  name="email"
  autoComplete="email"
  spellCheck={false}
  id="email-input"
  placeholder="your@email.com…"
/>
<label htmlFor="email-input" className="sr-only">
  Email address
</label>
<button type="submit">Submit</button>

The difference? The second version:

• Shows the correct keyboard on mobile devices
• Auto-fills from password managers
• Works with screen readers
• Prevents spellcheck underline distractions
• Has an accessible label (hidden visually but available to screen readers)

3. Performance: Preventing Common Pitfalls

Performance principles are encoded throughout:

## Performance
- Large lists (>50 items): virtualize (virtua, content-visibility: auto)
- No layout reads in render (getBoundingClientRect, offsetHeight, etc.)
- Batch DOM reads/writes; avoid interleaving
- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke

What this teaches: Performance requires understanding browser rendering:

• Layout reads force synchronous reflows
• Interleaved reads/writes cause multiple reflows
• Virtualization prevents DOM bloat

Example transformation:

// Bad: Layout thrashing
function BadComponent() {
  const list = items.map(item => {
    const height = item.ref.current.offsetHeight; // Read
    item.ref.style.height = `${height * 2}px`; // Write
    return <li key={item.id} ref={item.ref}>{item.name}</li>;
  });
  return <ul>{list}</ul>;
}

// Good: Batch reads and writes
function GoodComponent() {
  // Phase 1: Read all
  const heights = items.map(item =>
    item.ref.current.offsetHeight
  );

  // Phase 2: Write all
  items.forEach((item, i) => {
    item.ref.style.height = `${heights[i] * 2}px`;
  });

  return <ul>{items.map(...)}</ul>;
}

The knowledge encoded here—batch DOM operations—represents performance optimization expertise that typically takes years to accumulate.

4. Animation: Compositor-Friendly Patterns

Animation guidelines show deep browser understanding:

## Animation
- Honor prefers-reduced-motion (provide reduced variant or disable)
- Animate transform/opacity only (compositor-friendly)
- Never transition: all—list properties explicitly
- Set correct transform-origin
- Animations interruptible—respond to user input mid-animation

What this teaches: Great animations are:

• Accessible: Respect user preferences
• Performant: Only animate transform and opacity (GPU-accelerated)
• Maintainable: Explicit property lists, not transition: all
• Responsive: Allow users to interrupt

/* Bad: Everything animates, janky */
.button {
  transition: all 0.3s;
}

/* Good: Only GPU-accelerated properties */
.button {
  transition: transform 0.2s, opacity 0.2s;
}

/* Better: Respects motion preferences */
@media (prefers-reduced-motion: reduce) {
  .button {
    transition: none;
  }
}

5. Typography: Polish That Users Notice

The details matter:

## Typography
- … not ...
- Curly quotes " " not straight "
- Non-breaking spaces: 10 MB, ⌘ K, brand names
- Loading states end with …: "Loading…", "Saving…"
- font-variant-numeric: tabular-nums for number columns/comparisons
- Use text-wrap: balance or text-pretty on headings (prevents widows)

What this teaches: Professional polish comes from details:

• Use proper typographic symbols (ellipsis, quotes)
• Prevent awkward line breaks (non-breaking spaces, text-wrap: balance)
• Make numbers readable (tabular nums align digits)

These are the touches that separate amateur from professional interfaces.

Why This Skill is a Learning Powerhouse

1. Compressed Expertise

This skill captures what would take years to learn through:

• Trial and error
• User complaints
• Accessibility audits
• Performance profiling
• Cross-browser testing

Instead, you get a distilled, actionable checklist in minutes.

2. Context-Rich Learning

Unlike generic blog posts, this skill is specific:

• When to apply each rule
• Why it matters (performance, a11y, UX)
• How to implement it (code examples)
• What to avoid (anti-patterns)

3. Immediate Application

You can use this skill on your own code:

# Install the skill
npx skills add vercel-labs/agent-skills

# Review your component
npx claude "Review src/components/Form.tsx using web-design-guidelines"

You get immediate, actionable feedback based on Vercel’s standards.

4. Living Documentation

The skill fetches fresh guidelines each time. As Vercel learns and evolves, so does your knowledge base. You’re not learning from a static snapshot—you’re learning from their ongoing experience.

Comparative Analysis: Traditional vs. Skills-Based Learning

Let’s compare learning web design best practices through traditional methods vs. this skill:

The difference isn’t just incremental—it’s exponential.

Practical Exercise: Apply the Skill

Let’s walk through applying this skill to a real component.

Problem: A Basic Form Component

function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    await login(email, password);
    setLoading(false);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
      />
      <button type="submit">
        {loading ? 'Loading...' : 'Submit'}
      </button>
    </form>
  );
}

Running the Skill

Ask your AI agent:

“Review this component using the web-design-guidelines skill”

Issues Found

Based on Vercel’s guidelines, the skill would identify:

1. Wrong input type: type="text" for email → should be type="email"
2. Missing autocomplete: No autocomplete attribute
3. Missing inputmode: No mobile keyboard optimization
4. No spellcheck control: Email shouldn’t show spellcheck
5. No labels: Screen readers can’t describe inputs
6. Paste blocked: No explicit paste handling
7. Button stays enabled: Should disable during loading
8. No error handling: No inline error display
9. Unsafe navigation: No warning before leaving with unsaved changes
10. Generic placeholder: Should show example pattern with …

Refactored Component

function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(false);
  const [errors, setErrors] = useState({ email: '', password: '' });

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    // Validate
    const newErrors = {
      email: !email ? 'Email is required' : '',
      password: !password ? 'Password is required' : ''
    };

    if (newErrors.email || newErrors.password) {
      setErrors(newErrors);
      // Focus first error
      if (newErrors.email) document.getElementById('email')?.focus();
      return;
    }

    try {
      setLoading(true);
      await login(email, password);
    } catch (err) {
      setErrors({ email: 'Invalid email or password', password: '' });
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit} noValidate>
      <div>
        <label htmlFor="email" className="sr-only">
          Email address
        </label>
        <input
          id="email"
          type="email"
          inputMode="email"
          name="email"
          autoComplete="email"
          spellCheck={false}
          placeholder="your@email.com…"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          aria-invalid={!!errors.email}
          aria-describedby={errors.email ? 'email-error' : undefined}
        />
        {errors.email && (
          <span id="email-error" role="alert">
            {errors.email}
          </span>
        )}
      </div>

      <div>
        <label htmlFor="password" className="sr-only">
          Password
        </label>
        <input
          id="password"
          type="password"
          name="password"
          autoComplete="current-password"
          placeholder="Password…"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          aria-invalid={!!errors.password}
          aria-describedby={errors.password ? 'password-error' : undefined}
        />
        {errors.password && (
          <span id="password-error" role="alert">
            {errors.password}
          </span>
        )}
      </div>

      <button type="submit" disabled={loading}>
        {loading ? 'Signing in…' : 'Sign in'}
      </button>
    </form>
  );
}

The difference: The refactored version:

• ✅ Shows correct mobile keyboards
• ✅ Auto-fills from password managers
• ✅ Works with screen readers
• ✅ Handles errors gracefully
• ✅ Prevents duplicate submissions
• ✅ Uses proper typography (ellipsis)
• ✅ Follows all of Vercel’s guidelines

You didn’t just “fix a form”—you learned comprehensive form best practices from a team that builds world-class interfaces.

Connecting to the Bigger Picture

This single skill exemplifies the thesis from our Agent Skills as Best Practices article:

1. Codified SOPs

The web-design-guidelines skill is a Standard Operating Procedure. It’s Vercel’s workflow for reviewing interfaces, encoded as executable rules.

2. Expert Knowledge Access

By studying this skill, you’re accessing knowledge that would otherwise require:

• Working at Vercel
• Years of web development experience
• Multiple accessibility audits
• Extensive performance work

3. Learning Acceleration

Instead of learning each best practice through painful debugging, user complaints, or audit failures, you get:

• Immediate, actionable rules
• Context for why each rule matters
• Examples of correct implementation

4. Consistency and Quality

When you use this skill:

• You apply consistent standards
• You catch issues you’d miss
• You learn patterns that scale

How to Use This Skill for Learning

Step 1: Study the Skill

Read the skill file directly:

cat ~/.claude/skills/web-design-guidelines/SKILL.md

Pay attention to:

• What categories it covers
• What it prioritizes (a11y first!)
• What patterns it recommends

Step 2: Fetch the Guidelines

The skill fetches from:

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

Read the full guidelines to understand the depth of knowledge encoded.

Step 3: Apply to Your Code

Use the skill on your own components:

# Ask your AI agent
"Review src/components/Header.tsx using web-design-guidelines"

Study the output. Each finding is a learning opportunity.

Step 4: Manual Application

Before using the skill, try to review a component manually. Then compare with the skill’s output.

What did you miss?

• Those gaps are your learning opportunities
• Add those rules to your mental checklist

Step 5: Teach Others

Explain the skill’s guidelines to a teammate. Teaching reinforces learning.

The Meta-Lesson: Learning How to Learn

The web-design-guidelines skill teaches us more than just web design—it teaches us how to learn effectively in the AI era.

Traditional Learning Model

1. Read scattered documentation
2. Try to apply it
3. Learn from mistakes
4. Repeat

Skills-Based Learning Model

1. Study expert-compiled skills
2. Apply using AI agents
3. Get immediate feedback
4. Internalize patterns
5. Repeat faster

The difference: Skills compress the learning loop from months to minutes.

Creating Your Own Learning Skills

Once you’ve internalized the web-design-guidelines skill, create your own:

# Use skill-creator
npx skills add anthropics/skills

# Build your skill
"Use skill-creator to help me create a skill for [your domain]"

Examples:

• database-review-skill: Your team’s database optimization patterns
• api-design-skill: Your API design principles
• testing-strategy-skill: Your testing best practices
• code-review-skill: Your code review checklist

By creating skills, you:

• Solidify your knowledge: Teaching is learning
• Scale your expertise: Help your team
• Build a legacy: Codify your best practices

Article Word Cloud

Here’s a visual summary of the key concepts discussed in this article:

The word cloud above captures the essence of our discussion—Agent Skills, Vercel, learning, best practices, accessibility, performance, and web design all feature prominently, reflecting the core themes we’ve explored.

Conclusion

Vercel’s web-design-guidelines skill is a perfect example of why Agent Skills are revolutionary for learning:

What It Provides

• ✅ 50+ specific, actionable rules
• ✅ Years of production experience
• ✅ Comprehensive coverage of web design
• ✅ Live, evolving guidelines
• ✅ Immediate application to your code

What It Enables

• 🚀 Learn in minutes what took years
• 🎯 Apply expert patterns immediately
• 📈 Improve code quality consistently
• 💡 Build intuition through repetition

This single skill demonstrates why learning through codified SOPs is exponentially more efficient than traditional methods.

As we discussed in Agent Skills as Best Practices, we’re witnessing a paradigm shift in how we learn and share knowledge. Companies like Vercel are leading the way by publishing their internal practices as Agent Skills.

The opportunity: Study these skills, apply them, internalize them, and create your own.

The result: Faster learning, better code, and a growing collection of codified expertise.

Resources

• Vercel web-design-guidelines skill: https://github.com/vercel-labs/agent-skills
• Vercel Web Interface Guidelines: https://github.com/vercel-labs/web-interface-guidelines
• Related Article: Agent Skills as Best Practices
• Skills.sh Directory: https://skills.sh/
• Skill Creator: https://github.com/anthropics/skills/tree/main/skill-creator

Start learning from Vercel’s expertise today—install their skills and study them carefully. Your future self will thank you. 🎓