visual-design

name	visual-design
description	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.
metadata	{"references":["references/aesthetic-principles.md","references/brand-alignment.md","references/visual-hierarchy.md"]}

Visual Design

Workflow

1. Commit to one aesthetic direction (see table below). Pick one — do not blend three.
2. Document brand inputs: values, voice, existing tokens, audience, competitors.
3. Define hierarchy plan: primary CTA, secondary content, tertiary, decoration — ranked.
4. Choose type pair: distinctive display + refined body. Avoid Inter/Roboto/Arial/Space Grotesk defaults.
5. Build tokens: colors (dominant + sharp accent), spacing scale, radii, shadows, motion timings.
6. Implement: real code (HTML/CSS or framework), not mockups.
7. 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: (--ink); : (, , ) (, , ); :  solid (--rule); }
 { :  ./ (--mono); : .; : uppercase; : ; }
 { :  (, , )/ (--serif); : -; : ; :   ; }
  { : (--accent); : italic; }
 { :  / (--serif); : ; : ; }
 { :  ./ (--mono); :  solid currentColor; : ; : none; : (--ink); }
 { : (--accent); }
 (: no-preference) {
   { : rise . (.,.,.,) both; }
   rise {  { : ; : (); } }
}

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}
        
      ))}
    
  );
}

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

• Color Systems: palettes, contrast, semantic tokens, dark mode
• Typography Systems: scales, pairing, fluid type
• Motion Design: choreography, performance
• Grid Layout Systems: column grids, spacing scales