Visual Design
Workflow
- Commit to one aesthetic direction (see table below). Pick one — do not blend three.
- Document brand inputs: values, voice, existing tokens, audience, competitors.
- Define hierarchy plan: primary CTA, secondary content, tertiary, decoration — ranked.
- Choose type pair: distinctive display + refined body. Avoid Inter/Roboto/Arial/Space Grotesk defaults.
- Build tokens: colors (dominant + sharp accent), spacing scale, radii, shadows, motion timings.
- Implement: real code (HTML/CSS or framework), not mockups.
- Quality gate (before shipping):
- Run
npx pa11y <url> — zero contrast failures (WCAG AA: 4.5:1 body, 3:1 large text).
- Visual consistency: same spacing scale across all pages, same radius vocabulary, no orphan one-off colors.
- First-impression check: screenshot the hero, ask "would this be memorable in a Dribbble feed?"
- Reduced-motion: confirm
prefers-reduced-motion disables non-essential animation.
Aesthetic direction picker (one)
| Tone |
Use for |
Signal moves |
| Brutally minimal |
Dev tools, SaaS |
Mono type, hairline borders, no shadows |
| Luxury/refined |
Premium retail |
Serif display, restrained palette, generous whitespace |
| Editorial |
Content, blogs |
Dramatic type contrast, asymmetric grid, large imagery |
| Playful |
Consumer, kids |
Rounded shapes, bouncy easing, oversized elements |
| Retro-futurist |
Creative agency |
Neon accents, dark base, geometric shapes, scanlines |
| Organic |
Wellness, food |
Earth tones, hand-drawn marks, textured backgrounds |
| Brutalist/raw |
Art, counter-culture |
Exposed structure, system fonts used ironically |
| Industrial |
Dashboards |
Dense info, mono type, muted colors, grid-heavy |
| Maximalist |
Fashion, entertainment |
Mixed media, clashing palettes, controlled chaos |
| Glassmorphism |
Modern SaaS |
Frosted blur over vibrant backgrounds |
| Swiss |
Corporate, institutional |
Grid precision, Akzidenz-style type, clean geometry |
Full library + when-not-to-use guidance: aesthetic-principles.md.
Concrete example — editorial hero (HTML/CSS)
<section class="hero">
<p class="kicker">Issue 14 — Winter</p>
<h1 class="title">The <em>Quiet</em> Architecture<br/>of Better Tools</h1>
<p class="dek">A field report on craft software, written by the people who use it daily.</p>
<a class="cta" href="/read">Read the issue →</a>
</section>
<style>
:root {
--ink: #111; --paper: #f5f1ea; --accent: #c2410c; --rule: #111;
--serif: "Tiempos Headline", "Cormorant Garamond", Georgia, serif;
--mono: "JetBrains Mono", ui-monospace, monospace;
}
.hero { background: var(--paper); color: var(--ink); padding: clamp(3rem, 8vw, 8rem) clamp(1.5rem, 6vw, 6rem); border-bottom: 2px solid var(--rule); }
.kicker { font: 500 .8rem/1 var(--mono); letter-spacing: .12em; text-transform: uppercase; margin-bottom: 2rem; }
.title { font: 600 clamp(2.5rem, 7vw, 6rem)/0.95 var(--serif); letter-spacing: -0.02em; max-width: 14ch; margin: 0 0 1.5rem; }
.title em { color: var(--accent); font-style: italic; }
.dek { font: 400 1.125rem/1.5 var(--serif); max-width: 48ch; margin-bottom: 2.5rem; }
.cta { font: 500 .9rem/1 var(--mono); border-bottom: 1px solid currentColor; padding-bottom: 2px; text-decoration: none; color: var(--ink); }
.cta:hover { color: var(--accent); }
@media (prefers-reduced-motion: no-preference) {
.title { animation: rise .8s cubic-bezier(.2,.7,.2,1) both; }
@keyframes rise { from { opacity: 0; transform: translateY(1rem); } }
}
</style>
Concrete example — React + Motion staggered reveal
import { motion } from "motion/react";
export function FeatureRow({ items }: { items: { title: string; body: string }[] }) {
return (
<ul className="grid gap-12 md:grid-cols-3">
{items.map((it, i) => (
<motion.li key={it.title}
initial={{ opacity: 0, y: 24 }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, margin: "-10%" }}
transition={{ delay: i * 0.08, duration: 0.5, ease: [0.2, 0.7, 0.2, 1] }}>
<h3 className="font-serif text-2xl">{it.title}</h3>
<p className="text-neutral-600">{it.body}</p>
</motion.li>
))}
</ul>
);
}
Hard rules
- Pick a CLEAR direction (bold minimal OR maximalist) — never timid middle ground.
- One distinctive display font, one refined body font — no more.
- Dominant base color + one sharp accent. Avoid purple-gradient-on-white default.
- Match implementation effort to the tone: maximalist needs many details; minimal needs ruthless restraint.
- Vary across generations — never converge on Space Grotesk + purple + Inter.
Deeper context
- Visual Hierarchy — hierarchy tools, scanning patterns, golden ratio
- Brand Alignment — brand audit, mood board, extending vs evolving
- Aesthetic Principles — anti-patterns, tone library, Norman's three levels
Next Steps
1---2name: visual-design3description: Use when designing or coding a new interface that needs a distinctive aesthetic direction, when reviewing visuals for hierarchy/brand alignment, or when an existing UI feels generic ("AI slop") and needs production-grade visual polish.4---56# Visual Design78## Workflow9101. **Commit to one aesthetic direction** (see table below). Pick one — do not blend three.112. **Document brand inputs**: values, voice, existing tokens, audience, competitors.123. **Define hierarchy plan**: primary CTA, secondary content, tertiary, decoration — ranked.134. **Choose type pair**: distinctive display + refined body. Avoid Inter/Roboto/Arial/Space Grotesk defaults.145. **Build tokens**: colors (dominant + sharp accent), spacing scale, radii, shadows, motion timings.156. **Implement**: real code (HTML/CSS or framework), not mockups.167. **Quality gate** (before shipping):17 - Run `npx pa11y <url>` — zero contrast failures (WCAG AA: 4.5:1 body, 3:1 large text).18 - Visual consistency: same spacing scale across all pages, same radius vocabulary, no orphan one-off colors.19 - First-impression check: screenshot the hero, ask "would this be memorable in a Dribbble feed?"20 - Reduced-motion: confirm `prefers-reduced-motion` disables non-essential animation.2122## Aesthetic direction picker (one)2324| Tone | Use for | Signal moves |25|------|---------|--------------|26| Brutally minimal | Dev tools, SaaS | Mono type, hairline borders, no shadows |27| Luxury/refined | Premium retail | Serif display, restrained palette, generous whitespace |28| Editorial | Content, blogs | Dramatic type contrast, asymmetric grid, large imagery |29| Playful | Consumer, kids | Rounded shapes, bouncy easing, oversized elements |30| Retro-futurist | Creative agency | Neon accents, dark base, geometric shapes, scanlines |31| Organic | Wellness, food | Earth tones, hand-drawn marks, textured backgrounds |32| Brutalist/raw | Art, counter-culture | Exposed structure, system fonts used ironically |33| Industrial | Dashboards | Dense info, mono type, muted colors, grid-heavy |34| Maximalist | Fashion, entertainment | Mixed media, clashing palettes, controlled chaos |35| Glassmorphism | Modern SaaS | Frosted blur over vibrant backgrounds |36| Swiss | Corporate, institutional | Grid precision, Akzidenz-style type, clean geometry |3738Full library + when-not-to-use guidance: [aesthetic-principles.md](references/aesthetic-principles.md).3940## Concrete example — editorial hero (HTML/CSS)4142```html43<section class="hero">44 <p class="kicker">Issue 14 — Winter</p>45 <h1 class="title">The <em>Quiet</em> Architecture<br/>of Better Tools</h1>46 <p class="dek">A field report on craft software, written by the people who use it daily.</p>47 <a class="cta" href="/read">Read the issue →</a>48</section>4950<style>51:root {52 --ink: #111; --paper: #f5f1ea; --accent: #c2410c; --rule: #111;53 --serif: "Tiempos Headline", "Cormorant Garamond", Georgia, serif;54 --mono: "JetBrains Mono", ui-monospace, monospace;55}56.hero { background: var(--paper); color: var(--ink); padding: clamp(3rem, 8vw, 8rem) clamp(1.5rem, 6vw, 6rem); border-bottom: 2px solid var(--rule); }57.kicker { font: 500 .8rem/1 var(--mono); letter-spacing: .12em; text-transform: uppercase; margin-bottom: 2rem; }58.title { font: 600 clamp(2.5rem, 7vw, 6rem)/0.95 var(--serif); letter-spacing: -0.02em; max-width: 14ch; margin: 0 0 1.5rem; }59.title em { color: var(--accent); font-style: italic; }60.dek { font: 400 1.125rem/1.5 var(--serif); max-width: 48ch; margin-bottom: 2.5rem; }61.cta { font: 500 .9rem/1 var(--mono); border-bottom: 1px solid currentColor; padding-bottom: 2px; text-decoration: none; color: var(--ink); }62.cta:hover { color: var(--accent); }63@media (prefers-reduced-motion: no-preference) {64 .title { animation: rise .8s cubic-bezier(.2,.7,.2,1) both; }65 @keyframes rise { from { opacity: 0; transform: translateY(1rem); } }66}67</style>68```6970## Concrete example — React + Motion staggered reveal7172```tsx73import { motion } from "motion/react";7475export function FeatureRow({ items }: { items: { title: string; body: string }[] }) {76 return (77 <ul className="grid gap-12 md:grid-cols-3">78 {items.map((it, i) => (79 <motion.li key={it.title}80 initial={{ opacity: 0, y: 24 }}81 whileInView={{ opacity: 1, y: 0 }}82 viewport={{ once: true, margin: "-10%" }}83 transition={{ delay: i * 0.08, duration: 0.5, ease: [0.2, 0.7, 0.2, 1] }}>84 <h3 className="font-serif text-2xl">{it.title}</h3>85 <p className="text-neutral-600">{it.body}</p>86 </motion.li>87 ))}88 </ul>89 );90}91```9293## Hard rules9495- Pick a CLEAR direction (bold minimal OR maximalist) — never timid middle ground.96- One distinctive display font, one refined body font — no more.97- Dominant base color + one sharp accent. Avoid purple-gradient-on-white default.98- Match implementation effort to the tone: maximalist needs many details; minimal needs ruthless restraint.99- Vary across generations — never converge on Space Grotesk + purple + Inter.100101## Deeper context102103- [Visual Hierarchy](references/visual-hierarchy.md) — hierarchy tools, scanning patterns, golden ratio104- [Brand Alignment](references/brand-alignment.md) — brand audit, mood board, extending vs evolving105- [Aesthetic Principles](references/aesthetic-principles.md) — anti-patterns, tone library, Norman's three levels106107## Next Steps108109- **[Color Systems](../color-systems/SKILL.md)**: palettes, contrast, semantic tokens, dark mode110- **[Typography Systems](../typography-systems/SKILL.md)**: scales, pairing, fluid type111- **[Motion Design](../motion-design/SKILL.md)**: choreography, performance112- **[Grid Layout Systems](../grid-layout-systems/SKILL.md)**: column grids, spacing scales