spurnout/design-intelligence

Design Intelligence

Mission

Use this skill to make repeatable UI decisions under real constraints.

This skill is for:

• creating a new interface with deliberate structure instead of default AI patterns
• adopting an existing app, design system, or codebase without bulldozing it
• repairing existing UI for correctness, accessibility, clarity, performance, and completeness
• auditing UI output with explicit severity and routing

This skill is not for:

• forcing a signature aesthetic onto every surface
• treating taste preferences as hard law
• re-theming existing work unless the user asks for that
• replacing product thinking with visual novelty

Assume React, TypeScript, and Tailwind examples when useful. Keep the reasoning framework portable to other stacks.

Operating Modes

Create

Use when the task is greenfield or the user explicitly wants a new surface, component, or page.

Default behavior:

• derive structure from task, surface, and hierarchy first
• establish component choices before styling details
• use strong defaults aggressively
• run audit on complex or ship-intended work

Adopt

Use when the task happens inside an existing app, design system, or codebase with visible patterns.

Default behavior:

• inspect existing components, tokens, spacing, typography, icon family, and motion level first
• preserve system rhythm unless the user asked for a redesign
• prefer minimal diffs and local changes
• escalate only when the existing system is actively causing a Class A failure

Repair

Use when the task is to fix, critique, harden, refactor, or improve existing UI.

Default behavior:

• identify the failure class before changing aesthetics
• fix correctness, accessibility, state completeness, and performance before style refinements
• keep scope narrow
• audit before and after if the task is high risk

Execution Profiles

Profiles modify behavior inside the chosen mode. They do not replace the mode.

conservative

• reduce design variance
• prefer existing or highly conventional patterns
• minimize new dependencies and new motion
• good for Adopt, admin surfaces, and late-cycle fixes

expressive

• allow more layout emphasis, stronger visual hierarchy, and more distinctive style
• still obey Class A and Class B rules
• good for marketing, landing pages, launches, and explicit brand work

fast

• choose simpler structures and fewer custom patterns
• keep modules loaded to the minimum needed to ship a safe answer quickly
• avoid speculative exploration

shipping

• bias toward completeness checks, state coverage, and audit discipline
• force stronger validation on responsiveness, accessibility, and missing states
• treat polish as secondary to correctness and clarity

Surface Types

Surface type changes layout, density, hierarchy, motion, and acceptable variation.

• marketing page: narrative persuasion, proof, features, conversion
• landing page: campaign-specific conversion page with one dominant ask
• dashboard/app shell: persistent navigation, live status, overview, work orchestration
• settings/admin: configuration, permissions, operational clarity, safe actions
• form flow: multi-step or focused input completion
• content/docs: reading, reference, scanning, information retention
• data display: tables, charts, lists, metrics, filters, evidence-heavy surfaces
• mobile-first interface: constrained viewport, touch-first priorities, single-path flows
• embedded component: a bounded element inserted into an existing surface
• workspace/split-pane: parallel context, inspectors, panels, high task continuity
• list-detail: collections plus focused record view
• auth/onboarding: trust-building, low-friction start, recovery, progressive disclosure

Dials

Dials are modifiers, not laws.

• DESIGN_VARIANCE: how far the layout and styling can depart from plain defaults
• MOTION_INTENSITY: how much movement is allowed for feedback, transition, and emphasis
• VISUAL_DENSITY: how compact the interface should feel

Use calibration.md for anchor behavior.

Detection Logic

Detect Mode

Use this order:

1. If the user explicitly says audit, critique, fix, harden, debug, improve, or refactor existing UI, choose Repair.
2. If the user explicitly says add to an existing app, follow the current system, or work inside an existing codebase, choose Adopt.
3. If the user asks for a new page, flow, component, or concept without an established local system, choose Create.
4. If the repo already contains the target surface and the task is additive, prefer Adopt over Create.
5. If the target already exists and the user wants behavior or quality improvements, prefer Repair over Adopt.

When uncertain inside an existing codebase, choose Adopt.

Detect Surface

Use prompt language, target file location, and page intent:

• hero, pricing, CTA, testimonials, launch, waitlist, campaign -> landing page or marketing page
• sidebar, workspace, shell, panels, command center -> dashboard/app shell or workspace/split-pane
• preferences, roles, billing, feature flags, permissions -> settings/admin
• wizard, signup, checkout, application, stepper -> form flow or auth/onboarding
• docs, help center, changelog, article, knowledge base -> content/docs
• table, records, analytics, metrics, filters, chart -> data display
• mobile app, handset, bottom nav, thumb reach -> mobile-first interface
• embed, widget, card component, panel section -> embedded component
• inbox + detail, list + inspector, master-detail -> list-detail

If a surface combines two patterns, choose the dominant one and load the secondary module guidance as needed.

Decide Module Load

Always load:

• enforcement.md
• the mode logic in this file

Then load selectively:

• components.md when choosing, creating, or repairing components
• layout.md when page structure, hierarchy, density, or responsiveness matter
• taste.md when visual strategy, typography, color, or distinctiveness matter
• assets.md when icons, imagery, video, motion implementation, or media performance matter
• audit.md when reviewing output, shipping UI, or fixing non-trivial regressions
• examples.md when the task is ambiguous and a worked pattern will help
• calibration.md when dial values are provided or need translation

When To Run Audit

Run at least a quick audit when:

• the user asked for a review or critique
• the output includes interactive UI beyond simple text and links
• the surface contains forms, tables, dialogs, menus, tabs, drawers, toasts, or navigation
• the change is intended for shipping
• the user asks for "better," "more polished," or "more distinct" and the risk of vague advice is high

Run a full audit when:

• you touched multiple dimensions at once
• the work is a landing page, dashboard, settings surface, or multi-step form
• the first pass introduced custom layout, motion, or component logic
• the user asked for severity, routing, or ship-readiness

When To Stay Conservative

Stay conservative when any of these are true:

• existing system patterns are strong and consistent
• the user asked for minimal diff
• the surface is settings/admin, dense workflow, or operational UI
• brand direction is unknown
• time is limited and the safest path is clear
• the UI carries safety, permissions, billing, destructive actions, or mission-critical workflow

Pipeline

Use this sequence unless the user explicitly narrows scope:

1. detect mode and surface
2. load enforcement.md
3. derive information architecture and content structure
4. choose components from components.md
5. synthesize layout using layout.md
6. synthesize style and visual strategy using taste.md
7. resolve icons, images, media, and motion implementation with assets.md
8. generate or revise the output
9. audit with audit.md if the task or risk level justifies it
10. iterate based on the audit findings, starting with the highest-severity issue

Precedence Hierarchy

Use this order whenever guidance conflicts:

1. explicit user instruction
2. existing system constraints
3. hard fails
4. strong defaults
5. taste warnings
6. style choices

Never let a style preference overrule an accessibility, semantics, or correctness requirement.

Override Protocol

If the user explicitly wants something that this system would normally discourage:

1. comply if it does not create a Class A failure
2. acknowledge the tradeoff briefly
3. stop arguing after the acknowledgement

Example:

• user asks for a centered hero inside a campaign page
• comply if the surface supports it
• note only that conversion clarity and proof placement still matter

Do not keep trying to "save" the user from a deliberate style choice.

Module Loading Matrix

| Task | Highest-priority modules | | --- | --- | | Dashboard | enforcement, layout, components, assets, audit | | Landing page | enforcement, layout, taste, assets, audit | | Settings page | enforcement, components, layout, audit | | Form flow | enforcement, components, layout, audit, assets | | Audit only | enforcement, audit, then whichever module owns the finding | | Component creation | enforcement, components, audit | | Redesign in existing system | enforcement, layout, components, taste, audit, with Adopt protections active |

Anti-Bloat Rule

Do not restate whole support modules inside this file.

Use SKILL.md to:

• route
• detect mode and surface
• decide module load
• set precedence
• define pipeline

Use support files for the detailed rules, schemas, and examples.