Vibe coding has changed the speed of software creation. The idea, popularized by Andrej Karpathy in early 2025, is simple: you describe a feature in natural language and let an AI agent like Claude Code write the code. It feels less like programming and more like directing a very clever intern. Within minutes, you can have a full web page with interactive elements, API calls, and even a database schema. The speed is intoxicating.
But there is a hidden cost: design quality. The first generation of vibe-coded websites were technical successes but visual failures. They all seemed to share the same template: a centered hero, three feature cards, a section with a list, and a footer. The colors were muted blues and grays, the spacing was either too tight or too generous, and the buttons looked like they were designed by a committee that never met. This "AI look" erodes user trust, even when the product behind the interface is excellent.
The problem is not the AI's inability to design. Modern language models have seen millions of websites and can in principle produce high-quality UI. The issue is a lack of context. When you prompt "create a landing page," the model has no idea about your brand, your design preferences, or your frontend standards. It defaults to the statistical average of all the pages it has seen. That average is, well, average.
The solution is to give the AI a design system. And this is where Claude Code skills shine. A skill is essentially a bundle of instructions and reference materials that the AI loads when needed. By creating a skill that codifies your design tokens and component variants, you can close the design-quality gap without abandoning the flow of vibe coding. We call this the "Variant" skill, because it is built on the concept of design variants.
In this article, we will walk through a real-world case study: how we set up a repository with the Variant skill, used Claude Code to build a SaaS landing page, and measured the difference in design output. Along the way, we will cover the essentials of the skill system and provide code you can copy into your own project.
The Vibe Coding Boom and the Generic Design Problem
Vibe coding gained traction because it dramatically lowered the barrier to building web apps. Instead of setting up build tools, writing boilerplate, and debugging CSS, developers could focus on the user experience and let AI handle the implementation. However, the abstraction also removed the deliberate choices that define good design.
Let me give you a concrete example. In a traditional design workflow, a designer defines a type scale: 12, 14, 16, 20, 24, 32, 48, 64 pixels. They might define a spacing unit of 8 pixels. They would create a color palette with semantic names like --primary, --success, --danger. They would also define component variants: how a button looks when it is primary vs secondary, how a card looks when it is an alert vs a testimonial. This specificity is what makes a design feel polished and purposeful.
Without these constraints, an AI model has no reason to choose one font size over another. It will often use an 18px heading next to a 16px heading, resulting in a muddled hierarchy. It may set page padding to 90px on one section and 32px on another. It might pick a brand color and then use it at 50% opacity for text, making it illegible. These are the telltale signs of vibe-coded sites.
The problem is aggravated by the trending "vibe coding" culture of rapid iteration. Since it is so easy to regenerate, many developers accept the default output. But users notice. In our own testing, we found that usability drops when design is inconsistent. Even a simple task like comparing pricing plans becomes frustrating if the price cards are visually imbalanced.
So the question is: how do we inject design standards into an AI workflow without turning vibe coding into a tedious specification process? The answer is to use the AI's own learning loop.
Claude Code Skills: A Primer
Claude Code is Anthropic's command-line AI agent. It works directly in your terminal, reads your repository, and can edit files, run commands, and test results. In late 2025, Anthropic introduced a formal "skills" feature that allows developers to extend Claude's capabilities with reusable instructions.
You can read the official documentation at Anthropic's Claude Skills docs. According to the documentation, a skill is a folder containing a SKILL.md file with YAML front matter (name, description) and Markdown instructions. You can place skills in .claude/skills/ in your project, or in a global user directory. When you describe a task that matches a skill's description, Claude automatically loads the skill file and follows its instructions.
Skills are not code plugins in the traditional sense. They do not execute functions. Instead, they are "context injections" that shape how Claude generates responses. This makes them perfect for design systems: you can stuff a skill with all your CSS token values, component guidelines, and accessibility rules, and Claude will apply them to every relevant piece of code it writes.
The skill system is mature and stable. As of 2026, it is a first-class feature of Claude Code, and many open-source projects ship their own skills. This is encouraging because it means the pattern will not disappear.
Building the Variant Design Skill
The name "Variant" is intentionally generic. It represents a design approach where every component has multiple variation states. For example, a button isn't just a button; it has primary, secondary, ghost, destructive, and link variants. A card has default, hover, and elevated variants. A section has narrow, wide, and full-bleed variants. By requiring Claude to choose a variant based on context, you force it to think about hierarchy and purpose.
Here is the anatomy of the Variant skill we built:
1. The Folder Structure
Create a directory .claude/skills/variant/ in your repository. Inside, you will need:
SKILL.md- the main instructions filetokens.md- your design tokens in CSS or JSON formatcomponents.md- optional, but useful for detailed component guidance
2. The SKILL.md File
SKILL.md is the entry point. It should define the skill's purpose, describe when to activate it, and provide high-level rules. Here is a real example from our repo. Note that in a real file, each line would be at the start of the line; we have indented it here only for formatting.
---
name: variant-design
description: Apply Variant design system rules to all frontend code. Use when writing HTML, CSS, JSX, or any UI framework component that affects visual presentation.
---
# Variant Design System
This system ensures visual consistency across all generated interfaces.
## Core Principles
1. Always use semantic color tokens. Never hardcode hex values.
2. Use the 4px spacing scale. Multiples only (4, 8, 12, 16, 24, 32, 40, 64).
3. Maintain a clear visual hierarchy. Exactly one primary heading per section.
4. Use component variants as described in `components.md`. Choose the variant based on the component's role.
## Tokens
Refer to the CSS custom properties in `tokens.md`. For any style decision, first check if a token exists.
## Layout Rules
- Content container max-width: 1200px, centered with auto margin.
- Horizontal section padding: 24px on mobile, 48px on desktop.
- Vertical section padding: 64px on mobile, 96px on desktop.
- Grid columns: 12-column layout, use `gap: 24px`.
## Accessibility
- Ensure all text has contrast ratio >= 4.5:1 against its background.
- Use semantic HTML (header, main, nav, section, article, footer).
- Add `aria-label` to any icon-only or non-text control.
- Focus states must be visible (2px outline, `outline-offset: 2px`).
## Checklist Before Generating UI
- [ ] Has the component role been identified?
- [ ] Are colors pulled from tokens?
- [ ] Is spacing based on the 4px grid?
- [ ] Does the component have a variant assigned?
- [ ] Are accessibility rules applied?
3. The tokens.md File
Design tokens are the atomic variables of a design system. They ensure the AI does not invent new colors or sizes. We wrote our tokens as CSS custom properties so Claude can use them directly. Again, in the actual file these lines start at column zero.
:root {
--color-background: #ffffff;
--color-surface-subtle: #f9fafb;
--color-surface-raised: #ffffff;
--color-primary: #2563eb;
--color-primary-hover: #1d4ed8;
--color-secondary: #6b7280;
--color-border: #e5e7eb;
--color-text-default: #111827;
--color-text-muted: #6b7280;
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 24px;
--space-6: 32px;
--space-7: 40px;
--space-8: 64px;
--space-9: 96px;
--font-xs: 0.75rem;
--font-sm: 0.875rem;
--font-base: 1rem;
--font-lg: 1.125rem;
--font-xl: 1.25rem;
--font-2xl: 1.5rem;
--font-3xl: 1.875rem;
--font-4xl: 2.25rem;
--font-5xl: 3rem;
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-full: 9999px;
}
You can extend this file with shadows, gradients, and breakpoints. The key is consistency: if the model always sees these tokens, it will match them.
4. The components.md File (Optional but Recommended)
Component definitions help Claude understand which variant to use. For each component, describe the variant, its purpose, and its style. We will add an example for buttons.
# Button Variants
- **primary**: Main action. Background: --color-primary; Text: white.
- **secondary**: Alternative action. Background: transparent; Border: 1px solid --color-border; Text: --color-text-default.
- **ghost**: Inline action. Background: none; Text: --color-primary.
- **destructive**: Dangerous action. Background: red; Text: white.
- **link**: Inline text link. Text: --color-primary; Underline.
All buttons: min-height 40px, padding 0 16px, border-radius --radius-md, font-weight 500.
Repo Setup: Putting It Together
Now that you have the skill files, the repo setup is straightforward. We will use a simple vanilla HTML/CSS/JS project for clarity, but the same pattern works with React, Vue, or Svelte.
Step 1: Initialize the Repository
mkdir vibe-coded-landing
cd vibe-coded-landing
git init
Step 2: Install and Configure Claude Code
Make sure you have Claude Code installed globally. If you are using the latest version, you can install it with:
npm
install -g @anthropic-ai/claude-code
Once that finishes, confirm the installation worked:
claude --version
You should see a version number. If you prefer not to install globally, you can run `npx @anthropic-ai/claude-code` instead — just swap that in wherever you see `claude` below.
### Step 3: Create the Skills Directory
Claude Code looks for skill files in `.claude/skills/` at the project root. Let's create that structure:
mkdir -p .claude/skills
touch .claude/skills/design-system.md
touch .claude/skills/components.md
```
Step 4: Add the CLAUDE.md File
The CLAUDE.md file is your project's persistent context — Claude reads it automatically at the start of every session. This is where you put the
Comments