Mastering `web-design-guidelines`: The Complete Guide

In the era of Vibe Coding, speed is no longer the bottleneck. With tools like Gemini CLI and the Pencil MCP server, you can scaffold a functional React dashboard or a sophisticated landing page in the time it takes to brew a cup of coffee. However, this velocity introduces a new, more insidious problem: The AI Aesthetic Curse.

We’ve all seen it. You prompt an agent to build a “modern, sleek interface,” and it returns a functional but visually disjointed layout. The buttons lack consistent padding, the color contrast fails accessibility standards, and the information hierarchy is a chaotic “bento-grid” hallucination. It works, but it doesn’t feel professional. It doesn’t inspire trust.

This is where the web-design-guidelines skill becomes your secret weapon. It is the bridge between “AI-generated code” and “Production-grade UI.” This guide will show you exactly how to master this skill to ensure your Vibe Coding projects aren’t just fast, but flawless.

Core Concepts: How `web-design-guidelines` Works

The web-design-guidelines skill isn’t just a static list of “do’s and don’ts.” It is an intelligent, context-aware auditing engine designed to review your UI code against three primary pillars of modern web design:

1. The Heuristic Layer

The skill draws from foundational UX principles, including Nielsen’s 10 Usability Heuristics and Steve Krug’s “Don’t Make Me Think” philosophy. When you activate this skill, the agent doesn’t just look at your CSS; it evaluates whether a user can intuitively understand the state of the system.

Example: Does that “Delete” button look too much like the “Save” button? The skill identifies these affordance mismatches.

2. The Cognitive Laws

The agent applies psychological laws of interface design, such as:

Hick’s Law: Detecting if you’ve overwhelmed the user with too many navigation choices.
Fitts’s Law: Checking if your “Call to Action” buttons are too small for comfortable interaction on mobile.
The Law of Proximity: Ensuring related elements are grouped correctly through consistent spacing (margins/padding).

3. The Technical Compliance Gate

This is the most actionable part of the skill. It audits your code for:

WCAG 2.2 Accessibility: Checking for aria-label tags, semantic HTML (using <nav> instead of <div>), and color contrast ratios.
Responsive Integrity: Identifying hard-coded pixel widths that will break on a tablet or small smartphone.
Design System Consistency: Ensuring your Tailwind colors or CSS variables aren’t deviating into “magic numbers” (e.g., using text-[#345321] instead of text-primary-600).

The Problem Solved: Why Vibe Coders Need This

Vibe Coding is built on the premise of high-level intent. You describe the “vibe,” and the AI handles the implementation. But AI models are often “lazy” with CSS. They might use a z-index: 9999 to fix a layout bug or ignore mobile-first principles because the training data for desktop layouts is more prevalent.

Without a dedicated guidelines skill, your workflow looks like this:

Prompt: “Build a pricing table.”
AI: Generates a table that looks okay on your monitor.
Deploy: Users on mobile find it unreadable.
Manual Fix: You spend 2 hours “noodling” with CSS to fix what the AI broke.

With web-design-guidelines, the workflow becomes Self-Correcting:

Prompt: “Build a pricing table.”
Command: activate_skill web-design-guidelines
Command: run "Review the pricing table for UX consistency and mobile responsiveness"
AI: Finds 4 violations, fixes them automatically before you even see the code.

Interactive / Practical Example: The “Messy Hero” Transformation

Let’s look at a real-world scenario. Imagine you’ve just used an agent to generate a Hero section for a SaaS product. The AI gives you this:

<!-- Messy AI-Generated Hero -->
<div style="background: linear-gradient(blue, purple); height: 500px; display: flex; align-items: center; justify-content: center;">
  <div style="width: 800px;">
    <h1 style="font-size: 50px; color: white;">Welcome to Our App</h1>
    <p style="color: #ccc;">We do things better than anyone else. Click below.</p>
    <button onclick="alert('Hi')">Get Started</button>
  </div>
</div>

Step 1: Activation and Audit

You invoke the skill within your Gemini CLI session: Gemini: activate_skill web-design-guidelines

Then, you issue a directive: Gemini: "Review hero.html against web-design-guidelines and provide an audit report."

Step 2: The Audit Findings

The skill returns a structured report:

Critical: Hard-coded 800px width will cause horizontal scrolling on mobile. (Violation of Responsive Integrity).
Warning: Button lacks semantic styling and hover states. (Violation of User Feedback).
Accessibility: Background gradient/text color ratio is 3.1:1. WCAG AA requires 4.5:1. (Violation of Contrast).
Structural: Inline styles detected. (Violation of Maintainability).

Step 3: The Automated Refactor

Because the skill is active, you can simply say: Gemini: "Fix all findings from the audit using Tailwind CSS."

The Result:

// Professional Refactored Hero
export const Hero = () => (
  <section className="relative min-h-[60vh] flex items-center justify-center bg-gradient-to-br from-blue-700 to-purple-900 px-4 py-20 lg:py-32">
    <div className="max-w-4xl w-full text-center lg:text-left">
      <h1 className="text-4xl md:text-6xl font-extrabold text-white tracking-tight leading-tight mb-6">
        Elevate Your Workflow <br className="hidden md:block" /> with Intelligence
      </h1>
      <p className="text-lg md:text-xl text-blue-100 max-w-2xl mb-10 leading-relaxed">
        Experience the next generation of task management. Built for speed, 
        verified by design, and ready for production.
      </p>
      <div className="flex flex-col sm:flex-row gap-4 justify-center lg:justify-start">
        <button className="px-8 py-4 bg-white text-blue-700 font-bold rounded-lg shadow-lg hover:bg-blue-50 transition-all focus:ring-4 focus:ring-blue-300 active:scale-95">
          Get Started Free
        </button>
        <button className="px-8 py-4 bg-transparent border-2 border-white text-white font-semibold rounded-lg hover:bg-white/10 transition-colors">
          Watch Demo
        </button>
      </div>
    </div>
  </section>
);

The transformation isn’t just cosmetic. The refactored version includes responsive padding, accessible contrast, interactive states (hover/active), and semantic typography. This is the power of the skill in action.

Best Practices & Tips for Vibe Design

To get the most out of web-design-guidelines, follow these three rules of thumb:

1. Audit Before You Polish

Don’t wait until the end of your project to run an audit. Run it at the component level. If you are building a Navbar, audit it immediately. This prevents “Layout Debt” from accumulating, where a mistake in the Navbar’s height forces you to use “hacky” CSS in the rest of the page.

2. Combine with `pencil` for Visual Validation

The pencil MCP server is your editor, but web-design-guidelines is your brain. Use snapshot_layout from the Pencil toolset alongside the design guidelines.

Tip: Ask the agent: “Use Pencil to snapshot the layout of the mobile view, then run a web-design-guidelines check to see if any elements are overlapping or too close together.”

3. Establish a “Core Design Token” Standard

When you activate the skill, feed it your design tokens first. Gemini: "Here are my branding colors: Primary=#2563eb, Secondary=#f59e0b. Ensure all future design-guideline audits enforce these tokens." This ensures that the “Consistency” pillar of the skill is locked to your specific brand.

Advanced: The 4 Pillars of a Perfect Audit

When you use the skill, keep these four objectives in mind. You can even prompt the agent to focus on one specifically:

I. Visual Hierarchy

The user’s eye should naturally flow from the most important element (H1) to the least (Footer links). If the agent sees two “Primary” buttons on one screen, the guidelines skill should flag it as a conflict of hierarchy.

II. Feedback Loops

Digital interfaces must feel reactive. If a user clicks a button, there should be a state change (loading spinner, color shift). The web-design-guidelines skill checks for the existence of :hover, :focus, and :active states in your CSS/Tailwind classes.

III. Empty States & Errors

Professional apps handle the “unhappy path.” What does your data table look like when there are 0 rows? The skill will often suggest adding an “Empty State” illustration or message to prevent the UI from looking broken.

IV. Spacing Systems (The 8pt Grid)

Inconsistent spacing is the #1 giveaway of AI-generated code. The skill enforces a mathematical spacing system (usually increments of 4px or 8px). It will suggest changing a mt-7 (28px) to mt-8 (32px) to align with a standard grid.

Conclusion: Designing at the Speed of Thought

Vibe Coding is about removing the friction between an idea and its execution. But an idea executed poorly is just a prototype. To build a product, you need discipline.

The web-design-guidelines skill provides that discipline autonomously. It allows you to maintain the “Senior Designer” perspective without ever leaving your terminal. By integrating this skill into your daily Vibe Coding routine, you stop being a “prompter” and start being an Architect.

Your code will be more accessible, your layouts more resilient, and your “vibes” will finally match the professional reality of a production-ready application. Stop settling for “AI-Generated.” Start delivering “Design-Verified.”

Ready to level up? Try running activate_skill web-design-guidelines in your next session and ask: “Perform a deep UX audit on my current project and find 3 ways to make it feel more premium.”

Mastering web-design-guidelines: The Complete Guide

Core Concepts: How web-design-guidelines Works