The Problem with Raw AI Code Generation
AI models are trained on vast amounts of code, but that code varies wildly in quality. Ask a model to "build a landing page" and you might get inline styles mixed with Tailwind classes, inconsistent spacing, hardcoded colors, missing responsive breakpoints, and accessibility violations. The model knows how to write code — it does not inherently know how to write good code.
The solution is not a better model. It is better instructions.
What Are Design Skills?
VULK's Design Skills are modular instruction sets that get injected into the AI's system prompt before generation begins. Each skill is a focused document covering one domain — design systems, React component patterns, Tailwind CSS conventions, animation techniques, and so on.
Think of skills as specialized training manuals. Instead of hoping the AI remembers best practices from its training data, VULK explicitly tells it the standards to follow for every project.
The system currently includes 9 skills:
| Skill | Domain | What It Teaches | |-------|--------|----------------| | Design System | Visual consistency | Color tokens, spacing scale, elevation levels, border radii, consistent visual language | | React Patterns | Component architecture | Composition over inheritance, proper prop interfaces, custom hooks, state management patterns | | Tailwind | CSS framework | Utility-first classes, responsive prefixes, dark mode variants, avoiding class conflicts | | Animations | Motion design | Entry animations, scroll-triggered reveals, micro-interactions, performance-safe transforms | | Backend | Server-side code | API route structure, database schema conventions, authentication patterns, error handling | | Layouts | Page structure | Grid systems, sidebar patterns, responsive containers, sticky headers, content flow | | Typography | Text styling | Type scale, line heights, font weight hierarchy, readable line lengths, responsive sizing | | Accessibility | Inclusive design | ARIA labels, keyboard navigation, focus management, color contrast, screen reader support | | GSAP | Advanced animation | ScrollTrigger timelines, SplitText effects, pinning, parallax, stagger sequences |
How Skills Are Loaded
Skills are not all loaded at once. Loading all 9 skills for every generation would consume token budget on irrelevant instructions. Instead, VULK uses a scoring system that matches skills to the user's prompt.
The process works like this:
User prompt: "Build a restaurant website with a photo gallery,
animated menu sections, and a reservation form"
Skill scoring:
design-system → always loaded (core)
react-patterns → always loaded (core)
tailwind → always loaded (core)
animations → 0.8 score (matched: "animated")
gsap → 0.6 score (matched: "animated", "sections")
layouts → 0.4 score (matched: "gallery", "sections")
accessibility → 0.3 score (matched: "form", "reservation")
typography → 0.0 (no triggers matched)
backend → 0.0 (no triggers matched)
Loaded: design-system, react-patterns, tailwind,
animations, gsap, layouts, accessibility
Three skills — Design System, React Patterns, and Tailwind — are always loaded as core skills. They establish the baseline quality standard for every project. The remaining six are loaded based on trigger keyword matching, ranked by relevance, with a maximum of four optional skills per generation to control token usage.
For web projects, the Animation skill is also always included, since motion design is expected in modern web applications.
What Each Skill Contains
Each skill is a structured instruction document. Here is what they cover in practice:
Design System defines the visual vocabulary. It specifies how to use color tokens instead of raw hex values, how to apply consistent spacing (4px base grid), how to handle elevation with box shadows, and how to maintain visual hierarchy across components. The skill includes specific rules like "never use opacity for disabled states — use a dedicated disabled color token" and "maintain 4:1 contrast ratio minimum for all text."
React Patterns covers component architecture. It instructs the AI to use composition over prop drilling, extract reusable hooks for shared logic, type all props with TypeScript interfaces (not inline types), use forwardRef when building base components, and structure files with exports at the bottom. It explicitly prohibits patterns like putting business logic in components or using any types.
Tailwind ensures consistent use of the utility framework. It covers responsive design order (mobile-first with sm:, md:, lg: prefixes), dark mode with the dark: variant, avoiding conflicting utilities on the same element, using the @apply directive sparingly, and extracting component classes for repeated patterns.
Animations teaches motion design principles. It covers entry animations (fade, slide, scale), scroll-triggered reveals, staggered sequences for lists, hover micro-interactions, and exit animations. Performance rules are explicit: only animate transform and opacity, use will-change sparingly, respect prefers-reduced-motion.
Backend provides server-side conventions. Database table naming (singular, snake_case), REST endpoint structure, authentication middleware patterns, input validation, error response format, and Prisma schema conventions. It ensures generated backends follow a consistent, predictable architecture.
Layouts covers page structure patterns. Responsive grid systems, sidebar and header combinations, sticky navigation, content containers with max-width constraints, and mobile-first responsive breakpoints. It includes specific patterns for common layouts: dashboard (sidebar + content), marketing (full-width sections), and form-heavy (centered card).
Typography establishes text hierarchy. It defines a type scale (heading 1 through body text), line height ratios, font weight usage (regular for body, medium for labels, semibold for headings, bold sparingly), maximum line width for readability, and responsive font sizing.
Accessibility covers inclusive design standards. Every interactive element gets an ARIA label. Focus states are visible and styled. Keyboard navigation works through all interactive flows. Color is never the sole indicator of state. Form inputs have associated labels. Images have descriptive alt text.
GSAP provides advanced animation patterns for projects that need them. ScrollTrigger integration, timeline composition, SplitText character animations, pin and parallax effects, and proper cleanup in React (using useGSAP hook and context.revert()).
The Scoring Algorithm
The scoring function is straightforward. Each skill has a list of trigger keywords — terms that indicate relevance. The scorer checks how many of a skill's triggers appear in the user's prompt:
function scoreSkill(skill: Skill, prompt: string): number {
const lower = prompt.toLowerCase();
let hits = 0;
for (const trigger of skill.triggers) {
if (lower.includes(trigger.toLowerCase())) hits++;
}
return Math.min(hits / Math.max(skill.triggers.length * 0.3, 1), 1);
}
Skills with a score above 0 are candidates. The top 4 optional skills (by score) are loaded alongside the 3 core skills. This keeps the total skill payload manageable — typically 7 skills maximum per generation.
Before and After
The difference between generation with and without skills is measurable. Here are concrete examples:
Color handling:
- Without skills:
bg-[#6366f1],text-[#1f2937],border-[#e5e7eb]— raw hex values scattered throughout - With skills:
bg-primary,text-foreground,border-muted— semantic tokens that adapt to theming
Component structure:
- Without skills: 300-line monolithic component with inline state, effects, and rendering
- With skills: Separated into a custom hook for logic, a container for layout, and presentational sub-components
Responsive design:
- Without skills: Desktop layout only, or inconsistent breakpoint usage
- With skills: Mobile-first with progressive enhancement at
sm:,md:,lg:breakpoints
Accessibility:
- Without skills: Click handlers on
<div>elements, no focus management, missing labels - With skills: Semantic HTML (
<button>,<nav>,<main>), ARIA labels, keyboard-navigable
Animations:
- Without skills: CSS transitions on random properties, no scroll awareness, janky transforms
- With skills: GPU-accelerated transforms only, scroll-triggered reveals with intersection observer, respects reduced motion preference
Why Not Fine-Tune the Model?
Fine-tuning a model on high-quality code is an alternative approach. VULK chose runtime skill injection for three reasons:
1. Flexibility. Skills can be updated instantly without retraining. When Tailwind releases a new version or React introduces a new pattern, the skill documents are updated and every generation immediately benefits.
2. Composability. Different projects need different skill combinations. A static site needs typography and layout skills but not backend. An API service needs backend skills but not animations. Dynamic loading means no wasted context.
3. Model independence. Skills work with any AI model — Claude, GPT-4o, Gemini, DeepSeek, or models connected through BYOM. The same quality standards apply regardless of which model generates the code.
Extending the System
The skill architecture is designed for growth. Adding a new skill requires three things:
- A name and description
- A list of trigger keywords
- The instruction content
Future skills on the roadmap include: E-commerce (product listings, cart patterns, checkout flows), Data Visualization (chart libraries, dashboard layouts, real-time updates), Forms (multi-step wizards, validation patterns, file uploads), and SEO (meta tags, structured data, sitemap generation).
The skill system is also open for contribution. If you have domain expertise and want to improve the code VULK generates in a specific area, the skill format is straightforward to work with.
The Result
Design Skills are not visible to the user — you do not interact with them directly. They operate behind the scenes, shaping every file the AI writes. The effect is cumulative: consistent color usage, proper component architecture, responsive layouts, accessible interfaces, and smooth animations — all from the same natural language prompt.
The goal is simple: every VULK-generated project should look and feel like it was built by someone who knows what they are doing.
Documentation: support.vulk.dev/skills