Frontend Design Skill
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Follow the phased workflow below. Each phase has concrete reference material — use it, don't invent from scratch.
Phased Workflow
Phase 1: Design Direction
Before touching any code, commit to a clear aesthetic direction. Answer these:
Context questions:
- What problem does this interface solve? Who uses it?
- What's the one thing someone will remember about this design?
- What aesthetic direction fits? (Choose ONE — don't blend randomly)
Aesthetic directions to pick from:
Brutally minimal · Maximalist chaos · Retro-futuristic · Organic/natural · Luxury/refined · Playful/toy-like · Editorial/magazine · Brutalist/raw · Art deco/geometric · Soft/pastel · Industrial/utilitarian · Sci-fi/cyberpunk
CRITICAL: Every generation must make a fresh choice. Never default to the same direction twice. Vary light/dark themes, fonts, and palettes across generations.
Deliverables from Phase 1:
- ✓ Named aesthetic direction (e.g., "editorial luxury, dark theme")
- ✓ Font pairing selected from
references/typography.md
- ✓ Color palette selected from
references/color-palettes.md
- ✓ Layout composition(s) selected from
references/layout-compositions.md
Phase 2: Token System
Set up the design token foundation before writing any component code.
- Copy
examples/design-tokens.css into the project
- Override the palette primitives with your chosen palette's HSL values
- Override
--font-display and --font-body with your chosen font pairing
- Add the Google Fonts
@import to your HTML <head> (with preconnect hints)
<!-- Always preconnect BEFORE the font stylesheet -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="[your @import from typography.md]">
Deliverables from Phase 2:
- ✓
design-tokens.css (or equivalent) in place with chosen palette/fonts
- ✓ All colors, spacing, typography, shadows, and motion defined as CSS variables
- ✓ No hardcoded color values or magic numbers anywhere in component code
Phase 3: Build
Load the framework module for your target and implement components using design tokens.
Framework modules — load the relevant one:
| Target |
Module |
Vue 3 (<script setup>) |
frameworks/vue.md |
| HTML + Vanilla CSS/JS |
frameworks/html-css.md |
Build principles:
- Implement components from the layout compositions you chose
- Apply motion patterns from
references/motion-patterns.md at high-impact moments: page load, scroll reveals, hover states
- Use only
transform and opacity for animations — never width, height, top, left
- Every interactive element needs a hover state AND a focus-visible state
- Stagger entrance animations for groups of elements (cards, list items)
Mobile responsive (load references/mobile-responsive.md):
- Write CSS mobile-first: base styles for phone,
min-width queries for larger screens
- Every tap target: ≥ 44×44px (
min-height: 44px; min-width: 44px)
- Use
100svh not 100vh for full-screen sections (iOS Safari compatibility)
- Add
env(safe-area-inset-*) padding on fixed bottom elements
- Test at 375px, 768px, and 1280px minimum — use the decision matrix in the module
PWA readiness (load references/pwa-checklist.md for production apps):
- Add
manifest.json with correct name, icons (192 + 512 + maskable), theme_color
- Add PWA meta tags to
<head> (theme-color, apple-mobile-web-app-capable, apple-touch-icon)
- Register a service worker with appropriate caching strategy
- Create an offline fallback page (
offline.html)
- For Vite projects: prefer
vite-plugin-pwa over manual SW
Phase 4: Polish & Verify
Visual polish checklist:
Accessibility verification:
# Run the visual audit after starting your dev server
bash .agents/skills/frontend-design/scripts/visual-audit.sh http://localhost:[port]
The audit checks:
- Color contrast violations (WCAG AA minimum — 4.5:1 for text)
- Missing alt text, accessible names, and ARIA labels
- Skip link presence
- Semantic heading structure (one
<h1> per page)
- Font loading performance (CLS)
prefers-reduced-motion override presence
Fix all CRITICAL issues before marking the task complete. Warnings are acceptable if documented.
Anti-Pattern Catalog
These are the most common ways agents produce generic output. Identify and avoid them.
| Anti-Pattern |
What It Looks Like |
Fix |
| Gradient Soup |
Purple-to-blue gradient on white cards everywhere |
Use one deliberate gradient for ONE element (hero BG, accent bar). Source from color-palettes.md. |
| Font Stack Collapse |
Entire page in Inter, Roboto, or system fonts |
Pick a pairing from typography.md. Always use 2 distinct fonts with clear display/body roles. |
| Shadow Boxing |
box-shadow: 0 4px 6px rgba(0,0,0,0.1) on every card |
Use --shadow-sm for resting, --shadow-md for hover. Never apply the same shadow everywhere. |
| Animation Scatter |
Random transition: all 0.3s ease on dozens of elements |
Use --transition-all-interactions only for interactive elements. Apply entrance animations sparingly. |
| Whitespace Desert |
Cramped layout with 16px gaps between everything |
Section padding minimum --space-16. Hero sections minimum 100svh. Let content breathe. |
| Button Rainbow |
5 different button colors across a single page |
One --primary button, one --secondary, one --ghost. That's the system. |
| Flat Backgrounds |
Solid #1a1a2e with nothing else |
Add texture: gradient mesh, noise overlay, subtle pattern, or a layered radial gradient. |
| Generic Layout |
Centered content, full-width rows, constant padding |
Use a layout composition from references/layout-compositions.md. Break the grid deliberately. |
| Hover Nothing |
No state change on hover for interactive elements |
Every card, button, and link needs a hover state. Minimum: color change. Better: lift + shadow. |
| One-Size Typography |
Body text size used for everything |
Use the full type scale. Hero in --text-hero, section headings in --text-3xl, body in --text-base. |
| Desktop-First CSS |
max-width breakpoints everywhere, mobile layout breaks |
Write base styles for mobile. Layer up with min-width. See mobile-responsive.md. |
| Tiny Tap Targets |
24px buttons, links with no padding on mobile |
Minimum 44×44px interactive area. Expand with padding or ::after pseudo-element. |
Reference Modules
Load these when implementing. Don't rely on memory — read the module.
| Module |
When to Load |
references/typography.md |
Choosing fonts — 30 curated pairings |
references/color-palettes.md |
Choosing colors — 15 named palettes, light + dark |
references/motion-patterns.md |
Implementing animations — entrance, hover, scroll, micro |
references/layout-compositions.md |
Structuring pages — 15 named compositions |
references/frontend-layout.md |
Framework-neutral project layout (vertical slices, shared by React/Vue) |
references/mobile-responsive.md |
Mobile-first methodology, touch targets, viewport units, navigation patterns |
references/pwa-checklist.md |
Manifest, service worker, offline fallback, install prompt, Lighthouse PWA |
frameworks/vue.md |
Building in Vue 3 |
frameworks/html-css.md |
Building in HTML/CSS |
examples/design-tokens.css |
Starting a token system |
Rule Compliance
Before marking complete, verify:
- Project Structure — component organization follows
project-structure.md
- Testing — component tests follow
testing-strategy.md
- Security — XSS prevention, no
innerHTML with unescaped user data (security-principles.md)
- Accessibility — WCAG AA contrast, keyboard navigation, semantic HTML (
accessibility-principles.md)
- Audit script — visual-audit.sh passes with no CRITICAL failures
IMPORTANT: Implementation complexity must match the aesthetic vision. Maximalist designs require elaborate animation. Minimalist designs require meticulous spacing precision. Both fail if executed without care.
Remember: you are capable of extraordinary creative work. These references exist to ground your output in concrete, actionable choices — not to constrain your creativity. Use them as a launching pad.
1---2name: frontend-design3description: Generates distinctive, production-grade frontend interfaces and artifacts (React, Vue, HTML/CSS). Prioritizes bold aesthetics, unique typography, and motion to avoid generic designs. Use when building websites, landing pages, dashboards, posters, or when the user requests to style, beautify, or create visually striking UI.4---56# Frontend Design Skill78This skill guides creation of **distinctive, production-grade frontend interfaces** that avoid generic "AI slop" aesthetics. Follow the phased workflow below. Each phase has concrete reference material — use it, don't invent from scratch.910---1112## Phased Workflow1314### Phase 1: Design Direction1516Before touching any code, commit to a clear aesthetic direction. Answer these:1718**Context questions:**19- What problem does this interface solve? Who uses it?20- What's the one thing someone will remember about this design?21- What aesthetic direction fits? (Choose ONE — don't blend randomly)2223**Aesthetic directions to pick from:**24Brutally minimal · Maximalist chaos · Retro-futuristic · Organic/natural · Luxury/refined · Playful/toy-like · Editorial/magazine · Brutalist/raw · Art deco/geometric · Soft/pastel · Industrial/utilitarian · Sci-fi/cyberpunk2526**CRITICAL:** Every generation must make a fresh choice. Never default to the same direction twice. Vary light/dark themes, fonts, and palettes across generations.2728**Deliverables from Phase 1:**29- ✓ Named aesthetic direction (e.g., "editorial luxury, dark theme")30- ✓ Font pairing selected from `references/typography.md`31- ✓ Color palette selected from `references/color-palettes.md`32- ✓ Layout composition(s) selected from `references/layout-compositions.md`3334---3536### Phase 2: Token System3738Set up the design token foundation before writing any component code.39401. Copy `examples/design-tokens.css` into the project412. Override the palette primitives with your chosen palette's HSL values423. Override `--font-display` and `--font-body` with your chosen font pairing434. Add the Google Fonts `@import` to your HTML `<head>` (with preconnect hints)4445```html46<!-- Always preconnect BEFORE the font stylesheet -->47<link rel="preconnect" href="https://fonts.googleapis.com">48<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>49<link rel="stylesheet" href="[your @import from typography.md]">50```5152**Deliverables from Phase 2:**53- ✓ `design-tokens.css` (or equivalent) in place with chosen palette/fonts54- ✓ All colors, spacing, typography, shadows, and motion defined as CSS variables55- ✓ No hardcoded color values or magic numbers anywhere in component code5657---5859### Phase 3: Build6061Load the framework module for your target and implement components using design tokens.6263**Framework modules — load the relevant one:**6465| Target | Module |66|---|---|67| Vue 3 (`<script setup>`) | `frameworks/vue.md` |68| HTML + Vanilla CSS/JS | `frameworks/html-css.md` |6970**Build principles:**71- Implement components from the layout compositions you chose72- Apply motion patterns from `references/motion-patterns.md` at high-impact moments: page load, scroll reveals, hover states73- Use only `transform` and `opacity` for animations — never `width`, `height`, `top`, `left`74- Every interactive element needs a hover state AND a focus-visible state75- Stagger entrance animations for groups of elements (cards, list items)7677**Mobile responsive (load `references/mobile-responsive.md`):**78- Write CSS mobile-first: base styles for phone, `min-width` queries for larger screens79- Every tap target: ≥ 44×44px (`min-height: 44px; min-width: 44px`)80- Use `100svh` not `100vh` for full-screen sections (iOS Safari compatibility)81- Add `env(safe-area-inset-*)` padding on fixed bottom elements82- Test at 375px, 768px, and 1280px minimum — use the decision matrix in the module8384**PWA readiness (load `references/pwa-checklist.md` for production apps):**85- Add `manifest.json` with correct `name`, `icons` (192 + 512 + maskable), `theme_color`86- Add PWA meta tags to `<head>` (theme-color, apple-mobile-web-app-capable, apple-touch-icon)87- Register a service worker with appropriate caching strategy88- Create an offline fallback page (`offline.html`)89- For Vite projects: prefer `vite-plugin-pwa` over manual SW9091---9293### Phase 4: Polish & Verify9495**Visual polish checklist:**96- [ ] Typography: Are display and body fonts visually distinct and harmonious?97- [ ] Color: Is the palette cohesive? Do accents draw the eye to the right places?98- [ ] Spacing: Is there enough breathing room between sections? (minimum `--space-20` between major sections)99- [ ] Motion: Does the page feel alive on load? Are hover states immediate and satisfying?100- [ ] Backgrounds: Is there depth, texture, or gradient — or is it a flat color?101- [ ] Responsive: Does it look great at 375px? 768px? 1280px? No horizontal overflow?102- [ ] Touch: Are all interactive targets ≥ 44px? Does navigation work on mobile?103- [ ] PWA (if applicable): Does Lighthouse PWA score 100? Is offline fallback working?104105**Accessibility verification:**106```bash107# Run the visual audit after starting your dev server108bash .agents/skills/frontend-design/scripts/visual-audit.sh http://localhost:[port]109```110111The audit checks:112- Color contrast violations (WCAG AA minimum — 4.5:1 for text)113- Missing alt text, accessible names, and ARIA labels114- Skip link presence115- Semantic heading structure (one `<h1>` per page)116- Font loading performance (CLS)117- `prefers-reduced-motion` override presence118119**Fix all CRITICAL issues before marking the task complete.** Warnings are acceptable if documented.120121---122123## Anti-Pattern Catalog124125These are the most common ways agents produce generic output. Identify and avoid them.126127| Anti-Pattern | What It Looks Like | Fix |128|---|---|---|129| **Gradient Soup** | Purple-to-blue gradient on white cards everywhere | Use one deliberate gradient for ONE element (hero BG, accent bar). Source from `color-palettes.md`. |130| **Font Stack Collapse** | Entire page in Inter, Roboto, or system fonts | Pick a pairing from `typography.md`. Always use 2 distinct fonts with clear display/body roles. |131| **Shadow Boxing** | `box-shadow: 0 4px 6px rgba(0,0,0,0.1)` on every card | Use `--shadow-sm` for resting, `--shadow-md` for hover. Never apply the same shadow everywhere. |132| **Animation Scatter** | Random `transition: all 0.3s ease` on dozens of elements | Use `--transition-all-interactions` only for interactive elements. Apply entrance animations sparingly. |133| **Whitespace Desert** | Cramped layout with 16px gaps between everything | Section padding minimum `--space-16`. Hero sections minimum `100svh`. Let content breathe. |134| **Button Rainbow** | 5 different button colors across a single page | One `--primary` button, one `--secondary`, one `--ghost`. That's the system. |135| **Flat Backgrounds** | Solid `#1a1a2e` with nothing else | Add texture: gradient mesh, noise overlay, subtle pattern, or a layered radial gradient. |136| **Generic Layout** | Centered content, full-width rows, constant padding | Use a layout composition from `references/layout-compositions.md`. Break the grid deliberately. |137| **Hover Nothing** | No state change on hover for interactive elements | Every card, button, and link needs a hover state. Minimum: color change. Better: lift + shadow. |138| **One-Size Typography** | Body text size used for everything | Use the full type scale. Hero in `--text-hero`, section headings in `--text-3xl`, body in `--text-base`. |139| **Desktop-First CSS** | `max-width` breakpoints everywhere, mobile layout breaks | Write base styles for mobile. Layer up with `min-width`. See `mobile-responsive.md`. |140| **Tiny Tap Targets** | 24px buttons, links with no padding on mobile | Minimum 44×44px interactive area. Expand with padding or `::after` pseudo-element. |141142---143144## Reference Modules145146Load these when implementing. Don't rely on memory — read the module.147148| Module | When to Load |149|---|---|150| `references/typography.md` | Choosing fonts — 30 curated pairings |151| `references/color-palettes.md` | Choosing colors — 15 named palettes, light + dark |152| `references/motion-patterns.md` | Implementing animations — entrance, hover, scroll, micro |153| `references/layout-compositions.md` | Structuring pages — 15 named compositions |154| `references/frontend-layout.md` | Framework-neutral project layout (vertical slices, shared by React/Vue) |155| `references/mobile-responsive.md` | Mobile-first methodology, touch targets, viewport units, navigation patterns |156| `references/pwa-checklist.md` | Manifest, service worker, offline fallback, install prompt, Lighthouse PWA |157| `frameworks/vue.md` | Building in Vue 3 |158| `frameworks/html-css.md` | Building in HTML/CSS |159| `examples/design-tokens.css` | Starting a token system |160161---162163## Rule Compliance164165Before marking complete, verify:166- **Project Structure** — component organization follows `project-structure.md`167- **Testing** — component tests follow `testing-strategy.md`168- **Security** — XSS prevention, no `innerHTML` with unescaped user data (`security-principles.md`)169- **Accessibility** — WCAG AA contrast, keyboard navigation, semantic HTML (`accessibility-principles.md`)170- **Audit script** — visual-audit.sh passes with no CRITICAL failures171172**IMPORTANT:** Implementation complexity must match the aesthetic vision. Maximalist designs require elaborate animation. Minimalist designs require meticulous spacing precision. Both fail if executed without care.173174Remember: you are capable of extraordinary creative work. These references exist to ground your output in concrete, actionable choices — not to constrain your creativity. Use them as a launching pad.
irahardianto