Jonathon's AI Wiki

Frontend Design Deep Dive

8 min read

Source: skill files (frontend-design SKILL.md, typography.md, color-and-contrast.md, spatial-design.md, motion-design.md, interaction-design.md, responsive-design.md, ux-writing.md)

The frontend-design skill is the master skill in the design stack. Every other design skill operates within the creative frame it establishes. It is not a code generator --- it is a design philosophy enforcer that gathers context, commits to a bold direction, and then builds with that direction governing every decision. Understanding this skill deeply is the single most impactful thing you can do for your UI quality.

Context Gathering Protocol

This is the most overlooked part. The skill follows a strict 3-stage order before writing a single line of code:

Stage 1: Check instructions. Read CLAUDE.md, any project-level instructions, and the current conversation for explicit design direction from the user.

Stage 2: Check .impeccable.md. If this file exists (created by teach-impeccable), it contains the project’s design context: target users, brand identity, aesthetic preferences, and design principles. The skill reads and follows it.

Stage 3: Run teach-impeccable. If neither Stage 1 nor Stage 2 provides context, the skill invokes teach-impeccable to create the .impeccable.md file through a guided interview.

Why this matters: You cannot infer design context from code alone. A SaaS dashboard for enterprise finance clients and a SaaS dashboard for indie game developers might share identical technical architecture but need completely different aesthetics. Without context, the skill defaults to safe, generic output --- which is exactly the AI slop you are trying to avoid.

Design Direction

The skill commits to a BOLD aesthetic direction before building. It does not hedge. The available directions are:

  • Brutally minimal --- extreme reduction, aggressive whitespace, stark contrasts
  • Maximalist chaos --- dense, layered, visually overwhelming on purpose
  • Retro-futuristic --- analog nostalgia meets sci-fi speculation
  • Organic/natural --- soft curves, natural textures, earth tones
  • Luxury/refined --- premium materials, restrained palette, meticulous details
  • Playful/toy-like --- rounded forms, bright colors, tactile feel
  • Editorial/magazine --- asymmetric layouts, dramatic type, photographic focus
  • Art deco/geometric --- bold geometry, metallic accents, ornamental patterns
  • Soft/pastel --- gentle gradients, muted tones, calming feel
  • Industrial/utilitarian --- exposed structure, raw materials, function over form

The key principle: pick one and commit. Mixed directions produce the muddy, “AI made this” aesthetic. A committed direction --- even an unusual one --- reads as intentional.

Typography Rules

DO

  • Use a modular type scale with fluid sizing via clamp() (e.g., clamp(1rem, 0.5rem + 1.5vw, 1.5rem))
  • Choose fonts that match the aesthetic direction --- Geist for technical, Outfit for friendly, Cabinet Grotesk for editorial, Satoshi for modern, Fraunces for luxury
  • Create hierarchy through size contrast, weight contrast, and spacing --- not just bold vs. regular
  • Use optical sizing when available
  • Set body text at 16-20px with 1.5-1.7 line-height

DON’T

  • Use Inter, Roboto, Arial, Open Sans, or system defaults --- these are the typographic fingerprint of AI-generated UI
  • Use monospace fonts as lazy “dev tool” shorthand --- monospace is for actual code display, not aesthetic shortcuts
  • Set identical sizes for all text levels
  • Skip the type scale --- eyeballing sizes produces inconsistent results

Color and Theme

DO

  • Use oklch() for perceptually uniform color manipulation
  • Use color-mix() for tint/shade generation from a single base
  • Use light-dark() for adaptive theming
  • Tint your neutrals --- warm neutrals (amber undertone) or cool neutrals (blue undertone) instead of raw grays
  • Build palettes with the 60/30/10 rule (60% dominant, 30% secondary, 10% accent)

DON’T

  • Use gray on a colored background --- use a shade of the background color instead
  • Use pure black (#000) or pure white (#fff) --- always tint slightly (e.g., 0a0a0a, fafaf9)
  • Use the “AI color palette”: cyan on dark backgrounds, purple-to-blue gradients, neon accents on dark mode. This is the single most recognizable AI aesthetic pattern.
  • Use gradient text --- it screams AI. Use weight and size hierarchy instead.
  • Default to dark mode with glowing accents --- this is the lazy AI approach. Choose your theme intentionally.

Layout and Space

DO

  • Create visual rhythm through varied spacing --- not uniform gaps between everything
  • Use asymmetry intentionally --- left-heavy, right-heavy, offset grids
  • Use CSS Grid for 2D layouts --- it is more expressive than flexbox math
  • Mix container types: full-bleed sections, constrained content, offset panels
  • Design for content hierarchy, not container symmetry

DON’T

  • Wrap everything in cards --- cards should group related information, not be a default container
  • Nest cards inside cards --- flatten the visual hierarchy instead
  • Use identical card grids (3 equal cards in a row) --- this is the most common AI layout pattern. Use asymmetric bento grids, masonry, or varied widths instead.
  • Use the hero metric template (big number + label + trend arrow, repeated in a row) --- find unique ways to present data
  • Center everything --- left-aligned content with asymmetric negative space reads as more sophisticated

Visual Details

DON’T

  • Use glassmorphism everywhere --- glass/blur effects are an accent, not a default surface
  • Use rounded elements with a thick colored border on one side --- this is a specific AI visual tic
  • Use sparklines as decoration --- sparklines should represent real data or not exist

Motion

DO

  • Use exponential easing: ease-out-quart, ease-out-quint, ease-out-expo. These feel natural and responsive.
  • Use 150-300ms for micro-interactions (hovers, toggles, small state changes)
  • Use 500-800ms for entrance animations and larger transitions
  • Prefer transform and opacity --- they are GPU-composited and do not trigger layout recalculation
  • Use prefers-reduced-motion to respect user preferences

DON’T

  • Animate layout properties (width, height, top, left, margin, padding) --- these trigger layout recalculation and produce jank
  • Use bounce or elastic easing --- it looks playful in isolation but cheap in production
  • Use linear or ease-in-out as defaults --- they feel mechanical. Exponential easing feels alive.
  • Add animation for animation’s sake --- every motion should communicate state change, draw attention, or provide feedback

Interaction

DO

  • Use progressive disclosure --- show what matters now, reveal details on demand
  • Design empty states --- a blank screen with “No items” is a missed opportunity. Empty states should guide the user toward their first action.
  • Use inline validation --- don’t wait for form submission to show errors
  • Provide immediate visual feedback for every interaction (hover, focus, active, disabled states)

DON’T

  • Repeat information --- if a chart title says “Revenue Over Time,” the axis label should not also say “Revenue”
  • Make every button primary --- if everything is emphasized, nothing is. One primary action per view.
  • Show all options simultaneously when 80% of users need only 2-3 of them

The AI Slop Test

This is the skill’s core quality gate:

“If you showed this to someone and said AI made this, would they believe you immediately? If yes, that is the problem.”

The test is subjective but powerful. AI-generated UI has recognizable fingerprints:

  • Purple/blue gradients on dark backgrounds
  • Equal-width card grids
  • Inter or Roboto font
  • Centered layouts with uniform spacing
  • Glassmorphism on every surface
  • Generic placeholder data (John Doe, 99.99%, Lorem Ipsum)
  • Dark mode with neon accents as the default

If your UI triggers pattern recognition for “AI made this,” the design skill has failed regardless of technical quality. See anti-ai-slop-guide for the complete banned pattern list.

Implementation Principles

  • Match complexity to vision. A brutally minimal design needs minimal code. A maximalist editorial layout needs complex CSS Grid. Do not over-engineer simple designs or under-build ambitious ones.
  • Interpret creatively. “Make a dashboard” has a thousand possible executions. The skill should pick an unexpected one that fits the established direction.
  • NEVER converge on common choices. If you can predict the output before running the skill, the output is wrong. The skill should surprise you.
  • Vary between projects. Different themes, different fonts, different aesthetics, different layout structures. Repetition across projects is a sign the skill is running on autopilot.

Reference Files

The frontend-design skill includes detailed reference documents for each design dimension:

  • typography.md --- modular scales, fluid sizing, pairing rules, optical sizing
  • color-and-contrast.md --- oklch workflows, contrast requirements, palette construction
  • spatial-design.md --- spacing scales, rhythm, negative space, grid systems
  • motion-design.md --- easing curves, timing, choreography, reduced motion
  • interaction-design.md --- states, feedback, progressive disclosure, form patterns
  • responsive-design.md --- breakpoint strategy, fluid design, container queries
  • ux-writing.md --- microcopy, error messages, labels, tone

These files are loaded progressively --- only when the skill needs that specific design dimension.

Key Takeaways

  • The 3-stage context gathering protocol (instructions → .impeccable.md → teach-impeccable) is non-negotiable. Without context, you get generic output.
  • Commit to one bold aesthetic direction and do not hedge. Mixed directions produce AI slop.
  • The banned patterns are more important than the recommended patterns. Avoiding Inter, gradient text, equal card grids, and purple-on-dark eliminates 80% of AI aesthetics.
  • The AI Slop Test is the ultimate quality gate: would someone immediately believe AI made this?
  • Every design decision must trace back to the established direction. Random decorative choices break coherence.
  • This skill does not replace design thinking --- it enforces it. You still need to understand your users and your product.

Try It

  1. Run /teach-impeccable in your current project if you have not already --- answer the questions honestly about your users and brand
  2. On your next UI task, say “Build this with the frontend-design skill” and watch the 3-stage context gathering happen
  3. After the build, apply the AI Slop Test: screenshot the result, imagine showing it to a designer friend, and ask yourself if they would immediately say “AI made that”
  4. If the answer is yes, identify which banned patterns are present and explicitly ask the skill to eliminate them
  5. Compare before/after --- the difference is what this skill is for

Graph View

Backlinks