Designlint

DesignLint

> TL;DR — AI agents produce interfaces that all look and feel the same. DesignLint fixes this in two modes: Create (understand the user, make 9 deliberate design decisions, resolve a creative tension, critique the result — before shipping) and Audit (diagnose an existing interface, identify what's generic, and produce a concrete improvement plan). The goal isn't just different. It's human.

---

The Problem This Skill Solves

AI coding agents converge — at every level. Left unconstrained, they default to:

UI convergence:

• Typography: Inter, Roboto, or system fonts
• Colors: Purple/blue gradients, white backgrounds, gray text
• Layout: Centered column, 4px grid multiples, predictable spacing
• Components: shadcn/ui defaults, rounded-xl cards, subtle shadows
• Motion: opacity fade-in, nothing else

UX convergence:

• Navigation: Tab bar (5 icons) → List → Push detail. Always.
• Actions: Tap → Modal → Form → Submit → Toast. Always.
• Feedback: Green toast bottom-right for success, red for error. Always.
• Empty states: Centered illustration + one CTA. Always.
• Onboarding: 3-screen carousel with illustrations. Always.
• Data entry: Full form with a Submit button. Always.

Human convergence (the deeper problem):

• No understanding of who uses the product or how they feel
• Aesthetic choices disconnected from context or audience
• Archetypes copied instead of used as departure points
• Generic microcopy ("Submit", "Cancel", "Are you sure?")
• No creative tension — just safe, obvious choices
• No self-critique — first draft ships as final

This skill breaks all three layers.

---

Two Modes

DesignLint operates in two modes depending on the task:

→ Create Mode (default)

When the user asks to build, design, or create an interface. Follows the full protocol: Phase 0 → Phase 1 (9 decisions) → Phase 2 (brief) → Phase 3 (build) → Phase 4 (audit) → Phase 5 (critique).

→ Audit Mode

When the user asks to review, critique, audit, fix, or improve an existing interface — whether provided as a screenshot, a URL, code, or a description. Follows the Audit Protocol documented at the end of this file: Diagnosis → Convergence Score → Improvement Brief → Execution.

How to detect which mode:

• "Build me a…" / "Create a…" / "Design a…" → Create Mode
• "What's wrong with this?" / "Review this UI" / "Improve this" / "Make this better" / "Audit this design" / "This looks generic" → Audit Mode
• "Redesign this" → Audit Mode first (diagnose), then Create Mode (rebuild with a fresh brief)

---

Create Mode

Quick Start (Express Mode)

Short on time? Make these 4 decisions minimum:

1. Who and how they feel — One sentence: who is the user and what emotional state are they in when they use this? (e.g., "A busy founder checking metrics between meetings — anxious, time-poor, wants reassurance")
2. Pick an archetype as departure point from references/archetypes.md — then name ONE thing you'll deliberately do differently from that archetype
3. Pick a palette from the Palette Library in the same file
4. Pick a UX paradigm from references/ux.md

Document:

/* Quick DDP: User=busy founder, anxious | Archetype=Linear (but warmer type) | Palette=Amber Night | UX=Command-First + Optimistic UI */

Then write code. For the full protocol (recommended for anything production-facing), continue below.

---

Phase 0: Understand Before You Design

Before touching archetypes or aesthetics, answer three questions about the human who will use this.

Step 0a — The User in Context

Ask: > "Who is this person, and what is their emotional state when they open this interface?"

This is not a persona exercise. It's a single sentence that anchors every decision that follows.

Examples:

• "A nurse checking patient vitals during a 12-hour shift — exhausted, needs clarity, zero tolerance for friction"
• "A teenager customizing their profile — excited, playful, wants to express identity"
• "A CFO reviewing quarterly numbers before a board meeting — stressed, skeptical, needs confidence in the data"
• "A first-time user who just downloaded an app from a friend's recommendation — curious but impatient"

The emotional context changes everything. A dashboard for an exhausted nurse and a dashboard for an excited teenager should feel fundamentally different — even if they display similar data.

→ Document: /* User: [who] — [emotional state] */

Step 0b — The Creative Tension

Great design lives in tension. Pick TWO qualities that seem contradictory, then commit to resolving both:

Example tensions:

• Dense BUT calm (Bloomberg data density + luxury whitespace)
• Technical BUT warm (monospace precision + serif softness)
• Playful BUT trustworthy (rounded/bouncy + structured layout)
• Minimal BUT expressive (almost nothing on screen + one bold signature)
• Fast BUT considered (snappy interactions + cinematic transitions on key moments)
• Powerful BUT invisible (deep functionality + zero learning curve)

The tension is your creative engine. Without it, you'll default to the obvious — and obvious is generic.

→ Document: /* Tension: [quality A] BUT [quality B] */

Step 0c — Read the Archetypes Library (as departure points)

Open references/archetypes.md. Read at least 5–6 archetypes. But read them as a designer reads references — not as templates to reproduce.

For each archetype, the library documents tokens (type, palette, spatial, motion). These are starting points, not specifications. A human designer looks at Linear and thinks "I love the density but the coldness doesn't fit my users." That transformation — taking what works, discarding what doesn't, adding what's missing — is what makes design human.

Select 1 primary archetype + optionally 1 secondary for contrast. Then ask: > "What would I KEEP from this archetype, what would I DISCARD, and what would I ADD that isn't in any archetype?"

→ Document: /* Archetype: [name] — Keep: [x], Discard: [y], Add: [z] */

Step 0d — Read the UX Reference

Open references/ux.md. This is your UX vocabulary — navigation paradigms, interaction models, data entry patterns, feedback systems, onboarding approaches.

Ask: > "Given my user's emotional state and context — what interaction model would reduce their friction the most? If I removed all visual styling, would the experience still feel different from every other app in its category?"

---

Phase 1: Design Decision Protocol (DDP)

Work through these 9 decisions in order. Document your choices in a comment block at the top of your code.

Decision 1 — Aesthetic Axis

Pick ONE from each column, then combine them:

| Mood | Treatment | |------|-----------| | Brutalist | Raw, exposed structure, heavy borders, no decoration | | Editorial | Magazine-like, strong typographic hierarchy | | Organic | Irregular shapes, natural textures, flowing | | Utilitarian | Tool-first, dense, functional, no-frills | | Luxury | Negative space, restraint, gold/cream accents | | Playful | Bouncy, rounded, expressive, friendly | | Industrial | Monospace, structured grids, technical | | Retro | Era-specific (70s, 80s, 90s, Y2K), nostalgia | | Neo-classical | Timeless, serif-forward, refined proportions | | Maximalist | Rich, layered, abundant, visual feast |

Check: Does your aesthetic axis serve the user's emotional context from Phase 0? A "Brutalist" axis for an anxious nurse is probably wrong. An "Industrial" axis for a teenager's profile is probably wrong. Let the user pull you toward the right aesthetic, not the other way around.

→ Document: /* Aesthetic: [axis] — because [why it serves the user] */

Decision 2 — Typography Contract

BANNED fonts (never use these as default choices):

• Inter, Roboto, Arial, Helvetica Neue, San Francisco (system-ui), DM Sans, Plus Jakarta Sans, Outfit, Nunito, Poppins, Space Grotesk

Exceptions: Helvetica Neue is allowed only for a committed Swiss International archetype. System fonts are allowed only as body fallbacks when the display font carries the full typographic identity.

Allowed sources: Google Fonts, Adobe Fonts, system serif stack, monospace stacks

Required: Pick a DISPLAY font + a BODY font. They must create contrast (e.g., a heavy slab serif display + light geometric body). Size scale must break from 16px body defaults — try 15px, 17px, 18px. Line heights must be intentional.

Examples of bold choices:

• Playfair Display (heavy) + Lora (body) → Neo-classical editorial
• Fragment Mono + IBM Plex Mono → Technical/industrial
• Abril Fatface + Source Serif 4 → Maximalist editorial
• Libre Baskerville + Karla → Approachable but grounded
• Bebas Neue + Karla → Urban/brutal contrast
• Cormorant Garamond + Lora → Luxury/Maison

→ Document: /* Type: [Display] + [Body] */

Decision 3 — Color System

BANNED palettes:

• Purple/indigo gradients on white (#7C3AED, #8B5CF6 family)
• Default blues (#3B82F6, #2563EB) as primary
• Generic dark mode (#1F2937 backgrounds)
• "Safe" neutrals with one blue accent
• Gradient on gradient on gradient

Required: Build a 5-token system:

--color-bg       (base canvas — could be cream, slate, warm black, sand, etc.)
--color-surface  (elevated elements — cards, panels)
--color-primary  (dominant brand/action color)
--color-accent   (sharp contrast, used sparingly)
--color-text     (main text — never pure #000000 or #FFFFFF)

Unexpected color moves:

• Warm off-whites (#FAF7F2, #F5F0E8) instead of #FFFFFF
• Deep forest greens (#1A2E1A) or burgundy (#2D0A1A) as backgrounds
• Terracotta (#C85A38), sage (#87A878), or gold (#C9A84C) as primaries
• Muted, dusty tones with one electric accent
• Monochromatic palettes with a single unexpected pop

⚠️ Accessibility check: Verify that your --color-text on --color-bg meets WCAG AA contrast ratio (4.5:1 for body text, 3:1 for large text). Muted text tokens must still meet 3:1 minimum. Non-standard palettes are encouraged, but illegible text is not differentiation — it's a bug.

→ Document: /* Palette: [bg] / [surface] / [primary] / [accent] / [text] — contrast verified */

Decision 4 — Spatial Grammar

BANNED defaults:

• Everything centered in a column
• Consistent 16px or 24px padding everywhere
• Cards with equal padding on all sides
• Predictable 8px grid applied uniformly

Required: Choose a spatial approach:

• Asymmetric: Heavy left gutter, light right — or deliberate imbalance
• Breathing room: Generous, almost excessive white space in key areas
• Dense utility: Compact, information-rich, tabular feel
• Editorial bleed: Elements that break the container, full-width moments
• Layered depth: Elements overlap, z-index used intentionally
• Off-grid: Intentionally break the grid at one key point

→ Document: /* Spatial: [chosen approach] */

Decision 5 — Motion Character

BANNED defaults:

• opacity: 0 → 1 fade-ins on everything
• Uniform 300ms transitions
• scale(0.95) → scale(1.0) as the only "entrance" animation
• Simultaneous animations (everything fades in at once)

Required: Motion must have personality. Pick a motion character:

• Snappy: Fast (150ms), sharp easing, almost instant feedback
• Elastic: Spring physics, slight overshoot on entrances
• Cinematic: Slower (600-800ms), smooth easing, deliberate pacing
• Mechanical: Linear timing, precise, no-nonsense
• Playful: Bounce, wobble, or stagger with personality
• None: Deliberately static — restraint IS a choice

For web: use cubic-bezier over generic ease. Use staggered delays for lists. For iOS/SwiftUI: use .spring(), .interpolatingSpring(), or custom Animation curves. For Android/Compose: use spring() with custom stiffness/damping, or tween() with specific easing.

→ Document: /* Motion: [character] at [timing]ms */

Decision 6 — Signature Detail

Every memorable interface has one thing you remember. Pick ONE signature detail that is unexpected for this context:

Examples:

• A monospace timestamp in the corner showing live time
• Hover states that reveal something hidden (text, border, color shift)
• A subtle grain/noise texture on the background
• A single decorative line (1px, colored) that runs across the header
• A custom bullet/list marker (→, ●, ▲, etc.) used consistently
• Border radius that is either 0 or very large — never "medium"
• An SVG pattern or subtle geometric background
• Tab/active states that feel physical (like pressing a key)
• A data point displayed in a typographically distinctive way

→ Document: /* Signature: [description] */

Decision 7 — UX Paradigm

This is the interaction layer. Read references/ux.md for the full vocabulary. Then define:

Navigation model — How does the user move through the product? Choose from: Command-First / Spatial-Canvas / Progressive Stack / Feed+Panel / Mode-Based / Ambient

Interaction model — How do users act on content? Choose from: Inline Editing / Swipe Vocabulary / Drag-First / Contextual Actions / Progressive Actions / Gesture-Native

Data entry — How does the user input information? Choose from: Conversational Step-by-Step / Progressive Disclosure / Direct Manipulation / AI-Assisted / Bulk Import-First

Feedback model — How does the system communicate state? Choose from: Optimistic UI / Contextual (no global toasts) / Ambient Loading / Undo-over-Confirmation

Empty & onboarding — What does a first-time user experience? Choose from: Progressive (learn by doing) / Template-First / Job-to-be-Done / Zero-Friction / Social Proof

→ Document:

/* UX:
 * Navigation:  [chosen model]
 * Interaction: [chosen model]
 * Data entry:  [chosen pattern]
 * Feedback:    [chosen model]
 * Onboarding:  [chosen paradigm]
 */

Decision 8 — Voice & Tone

The words in an interface are design. "Submit" is not the same as "Save changes", which is not the same as "Done", which is not the same as "Let's go." A human-feeling interface has a consistent voice.

Define the voice along these axes:

| Axis | Range | |------|-------| | Formality | Casual ←→ Formal | | Warmth | Friendly ←→ Neutral ←→ Clinical | | Confidence | Assertive ←→ Gentle | | Brevity | Terse (1-2 words) ←→ Conversational (full sentences) |

Then apply it to these common UI touchpoints:

• Primary CTA: What does the main button say? (not "Submit")
• Empty states: What do you say when there's nothing to show? (not "No items found")
• Error messages: How do you communicate failure? (not "An error occurred")
• Confirmations: How do you celebrate success? (not "Success!")
• Loading: What do you say while waiting? (not just a spinner)

Examples by voice:

• Warm + casual + brief: "Save" / "Nothing here yet — start one?" / "That didn't work. Try again?" / "Saved ✓" / "Hang tight…"
• Formal + confident + terse: "Confirm" / "No records" / "Operation failed. Retry." / "Confirmed" / (no text, progress bar only)
• Friendly + conversational: "Save your work" / "You haven't created anything yet — here are some ideas" / "Something went wrong on our end. We're looking into it." / "All saved! You're good." / "Getting things ready…"
• Playful + warm: "Ship it!" / "It's quiet in here… 🦗" / "Oops — that broke. Let's fix it." / "Nailed it! 🎯" / "Brewing…"

→ Document: /* Voice: [formality] + [warmth] + [confidence] + [brevity]. CTA=[x], Empty=[y], Error=[z] */

For conversion-focused interfaces (landing pages, pricing, signup flows): also read references/persuasion.md for CTA formulas, copy frameworks (PAS, BAB), microcopy examples, and psychology principles that shape how users act on your words.

Decision 9 — The Departure

This is the decision that makes the design yours, not a reproduction of an archetype.

Look back at your archetype from Phase 0c. You do

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rgranet
• Source: rgranet/designlint-skill
• License: MIT

Install and usage instructions live in the source repository linked above.