161 lines
7.4 KiB
Markdown
161 lines
7.4 KiB
Markdown
# Frontend Design Skill
|
||
|
||
> A modular design-quality skill for AI agents building websites. Output that reads as if made by a senior designer at a top studio — not as if generated by an LLM guessing at "modern web design."
|
||
|
||
**7,842 lines. 18 files. Zero purple-to-blue gradients.**
|
||
|
||
---
|
||
|
||
## The problem
|
||
|
||
Ask an AI agent to build you a landing page. You will get:
|
||
|
||
- A purple-to-blue gradient hero.
|
||
- Centered headline. Two CTA buttons. A "trusted by 10,000+" logo bar.
|
||
- Three identical feature cards in a row, repeated three times.
|
||
- A testimonial carousel with stock headshots.
|
||
- Lorem ipsum-level copy that says nothing.
|
||
|
||
This is **AI slop** — the visual shorthand for "an LLM made this." It is what every AI defaults to, because it is what every AI has seen ten thousand times in its training set. It is the gravitational center of generative output, and everything has to actively push against it.
|
||
|
||
The skill files in this repo push against it.
|
||
|
||
---
|
||
|
||
## What's inside
|
||
|
||
```
|
||
SKILL.md 212 lines Core principles, process, identity (Agent Skills frontmatter)
|
||
aesthetics.md 320 lines 7 style directions with references
|
||
minimal-ui-patterns.md 924 lines 11 SaaS sub-styles (Linear, Stripe, Vercel, ...)
|
||
editorial-patterns.md 476 lines 6 editorial sub-styles (Pentagram, NYT Mag, ...)
|
||
brutalist-patterns.md 437 lines 5 brutalist sub-styles (Bandcamp, Working Format)
|
||
product-ui-patterns.md 1434 lines 10 Linear-style components, code-first
|
||
typography.md 351 lines Typefaces, scale, pairs, code
|
||
color.md 303 lines Tokens, palettes, contrast
|
||
layout.md 295 lines Containers, spacing scale, grids, responsive
|
||
anti-patterns.md 376 lines 28 AI-slop patterns with before/after
|
||
components.md 420 lines Buttons, forms, cards, states
|
||
motion.md 293 lines Animation, easing, a11y
|
||
content.md 272 lines Headlines, body, CTAs, microcopy
|
||
accessibility.md 269 lines Semantics, keyboard, focus, ARIA, testing
|
||
performance.md 210 lines Budgets, fonts, images, Core Web Vitals
|
||
imagery.md 226 lines CSS/SVG compositions, icons, favicon/og
|
||
code-style.md 850 lines Code quality, no GPT-slop
|
||
checklist.md 174 lines Pre-ship QA
|
||
```
|
||
|
||
**Total: 7,842 lines across 18 files.** Each file is independently loadable, so an agent can pull only what it needs without burning context on irrelevant guidance.
|
||
|
||
---
|
||
|
||
## How it works
|
||
|
||
The skill is built around a single principle: **restraint over decoration.** Every element must earn its place. If you can remove it without losing meaning — remove it.
|
||
|
||
That principle is applied across:
|
||
|
||
- **Aesthetic selection** — the agent picks one of 7 directions (Refined Minimal, Editorial, Swiss, Brutalist, Soft, Technical, Playful) instead of shipping the same generic "modern SaaS" look every time.
|
||
- **Typography** — concrete typefaces with concrete weights, sizes, leading, and tracking. The hero headline defaults to 60–160px, not the standard 36–48px.
|
||
- **Color** — one accent color used on less than 10% of pixels. No `linear-gradient(135deg, #667eea, #764ba2)` anywhere.
|
||
- **Layout** — one container system, one spacing scale, asymmetric splits (5/7, 3/9) instead of identical thirds, structure changes at breakpoints.
|
||
- **Anti-patterns** — a catalog of 28 specific patterns to reject, with examples and replacements. Not "avoid generic design." *Purple-to-blue gradients are slop. Replace with warm paper + ink + editorial red.*
|
||
- **Components** — every interactive element has default, hover, focus-visible, active, and disabled states defined. The places amateurs stop and pros begin.
|
||
- **Motion** — one entrance system, one hover system, one transition pattern. Plus `prefers-reduced-motion` honored.
|
||
- **Accessibility** — semantics first, keyboard contracts, designed focus, ARIA minimalism, and a 15-minute testing protocol. WCAG 2.2 AA as the floor.
|
||
- **Performance** — budgets before building: LCP < 2.5s, CLS < 0.1, ≤ 4 font files, zero blocking JS. An HTML+CSS page with no JS is the norm.
|
||
- **Imagery** — the no-stock decision tree: CSS/SVG compositions built from tokens, honest photo direction, one icon set, a real favicon and og:image.
|
||
- **Content** — concrete headlines ("Ship features 3x faster"), not "Empowering businesses to thrive." Real names, real numbers, real dates.
|
||
- **A pre-ship checklist** — 70+ items covering typography, color, layout, components, motion, accessibility, edge cases, and a final "would a senior designer ship this?" test.
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
**Minimum viable load** (fast, fewer tokens):
|
||
1. `SKILL.md`
|
||
2. `aesthetics.md` (pick a direction)
|
||
3. `checklist.md` (before shipping)
|
||
|
||
**Standard load** (recommended):
|
||
1. `SKILL.md`
|
||
2. `aesthetics.md`
|
||
3. `typography.md`
|
||
4. `color.md`
|
||
5. `layout.md`
|
||
6. `checklist.md`
|
||
|
||
**Deep work** (full quality pass):
|
||
Load all 18 files. The agent will only pull the deep files when the context demands it.
|
||
|
||
---
|
||
|
||
## Who this is for
|
||
|
||
- **AI agent builders** who want higher-quality frontend output from their tools.
|
||
- **Designers** who use AI agents and are tired of fixing the same five slop patterns every time.
|
||
- **Developers** who don't have a senior designer on hand but want their AI-generated sites to look considered, not generated.
|
||
- **Founders** shipping fast and trying not to ship ugly.
|
||
|
||
It is not for designers who already produce great work — you don't need it. It is for everyone who is downstream of an LLM and wants to upgrade the output.
|
||
|
||
---
|
||
|
||
## What it is not
|
||
|
||
- **Not a Figma plugin.** It is a markdown skill for AI agents, not a design tool for humans.
|
||
- **Not a CSS framework.** It produces no code; it shapes the code the agent writes.
|
||
- **Not a replacement for taste.** The skill raises the floor. The ceiling is still up to you.
|
||
- **Not magic.** A skill file is a set of instructions. The agent still has to follow them. If it doesn't, the output is still slop.
|
||
|
||
---
|
||
|
||
## Example: a hero, before and after
|
||
|
||
**Before** (typical AI output):
|
||
|
||
```
|
||
[purple-to-blue gradient hero, full-bleed]
|
||
Welcome to AcmeCloud
|
||
The platform for modern teams
|
||
[Get Started] [Learn More]
|
||
Trusted by 10,000+ companies
|
||
[8 generic logos of companies you've never heard of]
|
||
```
|
||
|
||
**After** (with the skill applied, Editorial direction):
|
||
|
||
```
|
||
Halftone is a four-person studio working from
|
||
Lisbon and Stockholm. We make identities, books,
|
||
and digital interfaces for brands that want to
|
||
be understood — not just seen.
|
||
|
||
Founded Spring 2017
|
||
People 4 partners, no contractors
|
||
Studios Lisbon · Stockholm
|
||
Practice Identity, editorial, interface
|
||
Currently Booking Q3 2026
|
||
```
|
||
|
||
Different words. Different structure. Different feel. The second one reads like a real studio. The first one reads like every other SaaS site ever generated.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT. Use it, modify it, redistribute it. If you ship something good with it, that's the thanks.
|
||
|
||
---
|
||
|
||
## Credits
|
||
|
||
Built from patterns observed across:
|
||
|
||
- **Product design:** Linear, Stripe, Vercel, Arc, Cron, Mercury, Pitch, Height
|
||
- **Studio work:** Pentagram, &Walsh, DIA Studio, Manual, Working Format, Locomotive, Bureau Mirko Borsche, Studio Dumbar
|
||
- **Editorial reference:** NYT Magazine, Bloomberg Businessweek, It's Nice That, Wallpaper*, Apartamento
|
||
- **Swiss / International Typographic:** Müller-Brockmann, Massimo Vignelli, Jan Tschichold, Wim Crouwel
|
||
- **Type design:** Erik Spiekermann, Stefan Sagmeister, Paula Scher, Tibor Kalman, Michael Bierut
|
||
|
||
If you recognise the patterns, that's the point. If you don't — read the references, then read the code.
|