Skill: tommygeoco/ui-audit (version 1.0.1)

--- name: ui-audit description: "AI skill for automated UI audits. Evaluate interfaces against proven UX principles for visual hierarchy, accessibility, cognitive load, navigation, and more. Based on Making UX Decisions by Tommy Geoco." author: Tommy Geoco homepage: https://audit.uxtools.co logo: logo-light.png logoDark: logo-dark.png --- # UI Audit Skill Evaluate interfaces against proven UX principles. Based on [Making UX Decisions](https://uxdecisions.com) by Tommy Geoco. ## When to Use This Skill - Making UI/UX design decisions under time pressure - Evaluating design trade-offs with business context - Choosing appropriate UI patterns for specific problems - Reviewing designs for completeness and quality - Structuring design thinking for new interfaces ## Core Philosophy **Speed ≠ Recklessness.** Designing quickly is not automatically reckless. Recklessly designing quickly is reckless. The difference is intentionality. ## The 3 Pillars of Warp-Speed Decisioning 1. **Scaffolding** — Rules you use to automate recurring decisions 2. **Decisioning** — Process you use for making new decisions 3. **Crafting** — Checklists you use for executing decisions ## Quick Reference Structure ### Foundational Frameworks - `references/00-core-framework.md` — 3 pillars, decisioning workflow, macro bets - `references/01-anchors.md` — 7 foundational mindsets for design resilience - `references/02-information-scaffold.md` — Psychology, economics, accessibility, defaults ### Checklists (Execution) - `references/10-checklist-new-interfaces.md` — 6-step process for designing new interfaces - `references/11-checklist-fidelity.md` — Component states, interactions, scalability, feedback - `references/12-checklist-visual-style.md` — Spacing, color, elevation, typography, motion - `references/13-checklist-innovation.md` — 5 levels of originality spectrum ### Patterns (Reusable Solutions) - `references/20-patterns-chunking.md` — Cards, tabs, accordions, pagination, carousels - `references/21-patterns-progressive-disclosure.md` — Tooltips, popovers, drawers, modals - `references/22-patterns-cognitive-load.md` — Steppers, wizards, minimalist nav, simplified forms - `references/23-patterns-visual-hierarchy.md` — Typography, color, whitespace, size, proximity - `references/24-patterns-social-proof.md` — Testimonials, UGC, badges, social integration - `references/25-patterns-feedback.md` — Progress bars, notifications, validation, contextual help - `references/26-patterns-error-handling.md` — Form validation, undo/redo, dialogs, autosave - `references/27-patterns-accessibility.md` — Keyboard nav, ARIA, alt text, contrast, zoom - `references/28-patterns-personalization.md` — Dashboards, adaptive content, preferences, l10n - `references/29-patterns-onboarding.md` — Tours, contextual tips, tutorials, checklists - `references/30-patterns-information.md` — Breadcrumbs, sitemaps, tagging, faceted search - `references/31-patterns-navigation.md` — Priority nav, off-canvas, sticky, bottom nav ## Usage Instructions ### For Design Decisions 1. Read `00-core-framework.md` for the decisioning workflow 2. Identify if this is a recurring decision (use scaffold) or new decision (use process) 3. Apply the 3-step weighing: institutional knowledge → user familiarity → research ### For New Interfaces 1. Follow the 6-step checklist in `10-checklist-new-interfaces.md` 2. Reference relevant pattern files for specific UI components 3. Use fidelity and visual style checklists to enhance quality ### For Pattern Selection 1. Identify the core problem (chunking, disclosure, cognitive load, etc.) 2. Load the relevant pattern reference 3. Evaluate benefits, use cases, psychological principles, and implementation guidelines ## Decision Workflow Summary When facing a UI decision: ``` 1. WEIGH INFORMATION ├─ What does institutional knowledge say? (existing patterns, brand, tech constraints) ├─ What are users familiar with? (conventions, competitor patterns) └─ What does research say? (user testing, analytics, studies) 2. NARROW OPTIONS ├─ Eliminate what conflicts with constraints ├─ Prioritize what aligns with macro bets └─ Choose based on JTBD support 3. EXECUTE └─ Apply relevant checklist + patterns ``` ## Macro Bet Categories Companies win through one or more of: | Bet | Description | Design Implication | |-----|-------------|-------------------| | **Velocity** | Features to market faster | Reuse patterns, find metaphors in other markets | | **Efficiency** | Manage waste better | Design systems, reduce WIP | | **Accuracy** | Be right more often | Stronger research, instrumentation | | **Innovation** | Discover untapped potential | Novel patterns, cross-domain inspiration | Always align micro design bets with company macro bets. ## Key Principle: Good Design Decisions Are Relative A design decision is "good" when it: - Supports the product's jobs-to-be-done - Aligns with company macro bets - Respects constraints (time, tech, team) - Balances user familiarity with differentiation needs There is no universally correct UI solution—only contextually appropriate ones. --- ## Generating Audit Reports When asked to audit a design, generate a comprehensive report. Always include these sections: ### Required Sections (always include) 1. **Visual Hierarchy** — Headings, CTAs, grouping, reading flow, type scale, color hierarchy, whitespace 2. **Visual Style** — Spacing consistency, color usage, elevation/depth, typography, motion/animation 3. **Accessibility** — Keyboard navigation, focus states, contrast ratios, screen reader support, touch targets ### Contextual Sections (include when relevant) 4. **Navigation** — For multi-page apps: wayfinding, breadcrumbs, menu structure, information architecture 5. **Usability** — For interactive flows: discoverability, feedback, error handling, cognitive load 6. **Onboarding** — For new user experiences: first-run, tutorials, progressive disclosure 7. **Social Proof** — For landing/marketing pages: testimonials, trust signals, social integration 8. **Forms** — For data entry: labels, validation, error messages, field types ### Audit Output Format ```json { "title": "Design Name — Screen/Flow", "project": "Project Name", "date": "YYYY-MM-DD", "figma_url": "optional", "screenshot_url": "optional - URL to screenshot", "macro_bets": [ { "category": "velocity|efficiency|accuracy|innovation", "description": "...", "alignment": "strong|moderate|weak" } ], "jtbd": [ { "user": "User Type", "situation": "context without 'When'", "motivation": "goal without 'I want to'", "outcome": "benefit without 'so I can'" } ], "visual_hierarchy": { "title": "Visual Hierarchy", "checks": [ { "label": "Check name", "status": "pass|warn|fail|na", "notes": "Details" } ] }, "visual_style": { ... }, "accessibility": { ... }, "priority_fixes": [ { "rank": 1, "title": "Fix title", "description": "What and why", "framework_reference": "XX-filename.md → Section Name" } ], "notes": "Optional overall observations" } ``` ### Checks Per Section (aim for 6-10 each) **Visual Hierarchy**: heading distinction, primary action clarity, grouping/proximity, reading flow, type scale, color hierarchy, whitespace usage, visual weight balance **Visual Style**: spacing consistency, color palette adherence, elevation/shadows, typography system, border/radius consistency, icon style, motion principles **Accessibility**: keyboard operability, visible focus, color contrast (4.5:1), touch targets (44px), alt text, semantic markup, reduced motion support **Navigation**: clear current location, predictable menu behavior, breadcrumb presence, search accessibility, mobile navigation pattern **Usability**: feature discoverability, feedback on actions, error prevention, recovery options, cognitive load management, loading states

path: CLAUDE.md
content: # UI Audit Framework

A comprehensive UI design decision-making framework. Use for rapid, intentional interface design.

## When to Use

- Making UI/UX design decisions under time pressure
- Evaluating design trade-offs with business context
- Choosing appropriate UI patterns for specific problems
- Reviewing designs for completeness and quality

## Core Process

1. **Weigh Information** — Institutional knowledge → User familiarity → Research
2. **Narrow Options** — Eliminate conflicts, prioritize by macro bet alignment
3. **Execute** — Apply relevant checklist + patterns

## Reference Files

Load as needed:

| Category | File |
|----------|------|
| Core Framework | `references/00-core-framework.md` |
| New Interfaces | `references/10-checklist-new-interfaces.md` |
| Fidelity | `references/11-checklist-fidelity.md` |
| Visual Style | `references/12-checklist-visual-style.md` |
| Visual Hierarchy | `references/23-patterns-visual-hierarchy.md` |
| Social Proof | `references/24-patterns-social-proof.md` |
| Navigation | `references/31-patterns-navigation.md` |

## Macro Bets

| Bet | Design Implication |
|-----|-------------------|
| **Velocity** | Reuse patterns, find metaphors |
| **Efficiency** | Design systems, reduce WIP |
| **Accuracy** | Stronger research, instrumentation |
| **Innovation** | Novel patterns, cross-domain inspiration |


path: README.md
content: <p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png" />
    <source media="(prefers-color-scheme: light)" srcset="logo-light.png" />
    <img src="logo-light.png" alt="UI Audit" width="50" />
  </picture>
</p>

<p align="center">
  <strong>AI skill for automated UI audits</strong><br>
  Evaluate interfaces against proven UX principles.
</p>

<p align="center">
  <a href="https://audit.uxtools.co">Guidelines</a> •
  <a href="https://clawdhub.com/skills/ui-audit">ClawdHub</a> •
  <a href="https://npmjs.com/package/ui-audit">npm</a>
</p>

---

## What is this?

A skill that gives AI assistants the ability to perform structured UI audits. Based on [Making UX Decisions](https://uxdecisions.com) by Tommy Geoco.

**Audits include:**
- Visual hierarchy & typography
- Visual style & spacing
- Accessibility & contrast
- Navigation & wayfinding
- Cognitive load & information architecture
- Social proof & trust signals
- Onboarding & empty states

## Installation

```bash
# Agent Skills (Vercel)
npx skills add uxtools/ui-audit

# ClawdHub
clawdhub install ui-audit

# npm
npm install ui-audit
```

## Usage

Ask your AI assistant:

```
Audit this design: [figma-url]
Review this landing page for accessibility issues
What visual hierarchy patterns should I use for a pricing page?
```

## What's Included

```
ui-audit/
├── SKILL.md                    # Main skill instructions
├── CLAUDE.md                   # Claude-specific quick reference
└── references/
    ├── 00-core-framework.md    # Decision-making process
    ├── 10-checklist-*.md       # Execution checklists
    └── 2*-patterns-*.md        # UI pattern libraries
```

## Guidelines

View the full list of principles at **[audit.uxtools.co](https://audit.uxtools.co)**

### Decisioning
- Weigh information in order: Institutional knowledge → User familiarity → Research
- Align every decision with macro bets: Velocity, Efficiency, Accuracy, or Innovation
- Define jobs-to-be-done first

### Visual Hierarchy
- Primary action is obvious within 3 seconds
- 2:1 ratio minimum between heading levels
- Related items are grouped (Law of Proximity)

### Accessibility
- Keyboard works everywhere
- Focus is always visible
- Color is not the only indicator

[View all guidelines →](https://audit.uxtools.co)

## Author

**[Tommy Geoco](https://x.com/designertom)** — [uxtools.co](https://uxtools.co) • [uxdecisions.com](https://uxdecisions.com)

## License

MIT


path: package.json
content: {
  "name": "ui-audit",
  "version": "1.0.1",
  "description": "AI skill for automated UI audits. Evaluate interfaces against proven UX principles for visual hierarchy, accessibility, cognitive load, and more. Based on Making UX Decisions by Tommy Geoco.",
  "keywords": [
    "ux",
    "design",
    "ui",
    "audit",
    "checklist",
    "ai-skill",
    "claude",
    "codex",
    "clawdbot",
    "ui-audit",
    "accessibility",
    "visual-hierarchy"
  ],
  "author": "Tommy Geoco <[REDACTED_SECRET]> (https://uxtools.co)",
  "license": "MIT",
  "homepage": "https://audit.uxtools.co",
  "repository": {
    "type": "git",
    "url": "https://github.com/tommygeoco/ui-audit"
  },
  "files": [
    "SKILL.md",
    "CLAUDE.md",
    "references/"
  ],
  "exports": {
    ".": "./SKILL.md",
    "./skill": "./SKILL.md",
    "./claude": "./CLAUDE.md",
    "./references/*": "./references/*"
  },
  "scripts": {
    "postinstall": "echo '\\n📖 UI Audit skill installed. Add to your project:\\n   - Clawdbot: Copy to ~/clawd/skills/ui-audit/\\n   - Claude: Copy CLAUDE.md to your project root\\n'"
  }
}


path: references/00-core-framework.md
content: # Core Framework: Warp-Speed Decisioning

## The 3 Pillars

### 1. Scaffolding
Rules that automate recurring decisions. Pre-made defaults so you don't re-decide the same things.

**Components:**
- Design psychology reference (laws, principles)
- Economics fundamentals (market forces)
- Accessibility reference (WCAG/POUR)
- Default typefaces and type scale
- Icon library choice
- Design system reference
- Default design rules

### 2. Decisioning
Process for making new decisions when scaffolds don't apply.

**Workflow:**
1. Inform simplicity — gather minimum viable context
2. Narrow options — eliminate conflicts, prioritize alignment
3. Weigh information — institutional knowledge → familiarity → research
4. Arrive at decision — commit and document reasoning

### 3. Crafting
Checklists for executing decisions consistently.

**Types:**
- Checklists for new interfaces
- Checklists for improving fidelity
- Checklists for visual style
- Checklists for innovation

---

## The Decisioning Workflow (Detail)

### Step 1: What Does Institutional Knowledge Say?

Institutional knowledge = existing patterns, brand guidelines, tech stack, team capabilities, business constraints.

**Questions:**
- Does an existing component/pattern solve this?
- What does our design system prescribe?
- What are our technical constraints?
- What has leadership/stakeholders indicated?

**Rule:** Always check internal resources before external inspiration.

### Step 2: What Are Users Familiar With?

User familiarity = conventions from similar products, learned behaviors, competitor patterns.

**Questions:**
- What do competitors do for this pattern?
- What's the platform convention (iOS/Android/Web)?
- What prior experience do users bring?
- Jakob's Law: Users spend most time on *other* sites

**Rule:** Familiarity reduces cognitive load. Novelty requires justification.

### Step 3: What Does Research Say?

Research = user testing, analytics, academic studies, heuristic evaluation.

**Questions:**
- Do we have usability data on this pattern?
- What does instrumentation tell us?
- Are there published studies on this interaction?
- Have we tested this with users?

**Rule:** Research trumps opinion, but absence of research ≠ decision paralysis.

### Arriving at a Decision

After weighing all three sources:
1. If clear winner exists → choose it
2. If conflict exists → prioritize by macro bet alignment
3. If uncertainty remains → choose fastest to validate, plan to learn

**Document your reasoning.** Future you (and teammates) will thank you.

---

## Staging Your Bets

### Why Bets Matter

Every design decision is a bet. You're wagering time and resources on an outcome. The question is whether you're betting intentionally or accidentally.

### Macro vs. Micro Bets

**Macro bets** = Company-level strategic bets on how to win the market
**Micro bets** = Individual design decisions within an interface

**Critical Rule:** Micro bets are only valid when intentionally supporting macro bets.

### The 4 Categories of Macro Bets

| Category | We win by... | Design implications |
|----------|--------------|---------------------|
| **Velocity** | Getting features to market faster | Reduce time-to-delivery, reuse components, find metaphors in other markets |
| **Efficiency** | Managing waste better | Design systems, reuse patterns, reduce WIP |
| **Accuracy** | Being right more frequently | Stronger research, measure with instrumentation, discovery sprints |
| **Innovation** | Discovering untapped market potential | Uncover "fog of war" with better discovery, find parallels in other markets |

### How to Stage Your Bets

1. **Analyze your industry** — Level of competition, market maturity, disruption threats
2. **Analyze competitors** — Leading vs. lagging, their bets, their gaps
3. **Define customer goals** — Jobs-to-be-done statements
4. **Name your bets** — Explicit statements of what you're betting on and why

### Jobs-to-be-Done (JTBD) Format

```
When [situation],
I want to [motivation],
So I can [desired outcome].
```

**Good JTBD:** "When I get emails, I want to organize them so I don't lose important information."

**Bad JTBD:** "Let me add tags, labels, and folders to my email so I can sort things according to my system."

The difference: Good JTBD focuses on outcome, bad focuses on feature.

---

## Informing Simplicity

Before diving into design:

1. **Define 2-3 primary JTBD** — What are users trying to accomplish?
2. **Identify your macro bets** — Which category is the company prioritizing?
3. **Understand your constraints** — Time, team, tech, budget
4. **Know your competition** — Where are they winning/losing?

**Author's Note:** Do this fast or don't do it at all. Don't get stuck whiteboarding JTBD. Trust your intuition. The goal is informed speed, not perfect analysis.


path: references/01-anchors.md
content: # The 7 Anchors: Foundational Mindsets

Anchors are mental models and principles that form your foundation. They keep you grounded when product development gets chaotic.

## Why Anchors Matter

1. **Clarity in chaos** — Quickly align decisions with core values when juggling priorities
2. **Confidence** — Make bold decisions under pressure
3. **Resilience** — Bounce back from setbacks
4. **Growth** — Framework for continuous learning (anchors evolve with you)

---

## Anchor 1: Pursue Your Purpose

**What:** Connect your work to a larger purpose. Inspired by Ikigai (reason for being).

**The 4 Elements:**
- What you love
- What you're good at
- What the world needs
- What you can be paid for

**When to rely on it:**
- Deciding which projects to take on
- Feeling unfulfilled or burnt out
- Prioritizing features or initiatives
- Considering career moves

**How to apply:**
- Define a personal mission statement
- Evaluate projects against the 4 elements
- Prioritize purpose-aligned work
- Connect even mundane tasks to larger goals
- Regularly reflect on alignment

---

## Anchor 2: Embrace the Marathon Mindset

**What:** Product design is a long game, not a sprint. Sustainable pace beats heroic bursts.

**Key principles:**
- Burnout is a feature, not a bug, of unsustainable work
- Small consistent progress compounds
- Recovery is part of the work
- Career success is measured in decades, not sprints

**When to rely on it:**
- Facing unrealistic deadlines
- Tempted to sacrifice quality for speed
- Building habits and systems
- Evaluating trade-offs with long-term consequences

**How to apply:**
- Protect your energy and attention
- Build systems, not just outputs
- Say no to protect yes
- Invest in learning that compounds

---

## Anchor 3: Be Intentional

**What:** Every design decision should be traceable to a reason. Accidental design is reckless design.

**Intentionality spectrum:**
- Unconscious incompetence (don't know what you don't know)
- Conscious incompetence (know gaps, learning)
- Conscious competence (deliberate, effortful mastery)
- Unconscious competence (intuitive mastery)

**When to rely on it:**
- Making any design decision
- Explaining choices to stakeholders
- Reviewing others' work
- Feeling autopilot taking over

**How to apply:**
- Document your reasoning
- Challenge "it's always been done this way"
- Ask "why this choice?" for every element
- Build decision logs

---

## Anchor 4: Embrace Your Unique Perspective

**What:** Your specific combination of experiences, skills, and viewpoints is an asset, not a liability.

**Key insight:** The industry doesn't need more average designers. It needs your particular blend of weird.

**When to rely on it:**
- Feeling imposter syndrome
- Comparing yourself to others
- Deciding what to learn next
- Positioning yourself professionally

**How to apply:**
- Identify your unique combination of skills
- Lean into interests others find "off-topic"
- Share your perspective, especially when different
- Build on strengths rather than only fixing weaknesses

---

## Anchor 5: Practice Just-in-Time Learning

**What:** Learn what you need when you need it, not in advance "just in case."

**Why it matters:**
- Knowledge decays without application
- The field changes faster than curricula
- Context makes learning stick
- You can't pre-learn everything

**When to rely on it:**
- Feeling overwhelmed by what you "should" know
- Deciding what to learn next
- Facing an unfamiliar problem
- Evaluating courses/resources

**How to apply:**
- Learn in response to real problems
- Apply immediately after learning
- Maintain a "learn when needed" list vs. "learn someday" list
- Trust your ability to figure things out

---

## Anchor 6: Challenge Assumptions

**What:** Actively question what "everyone knows" and what you've always believed.

**Common assumption traps:**
- "Users would never..."
- "That's just how it's done..."
- "The data shows..." (but does it really?)
- "We tried that and it didn't work" (in what context?)

**When to rely on it:**
- Inheriting existing designs
- Hearing "we've always done it this way"
- Receiving secondhand user feedback
- Feeling certain about something unvalidated

**How to apply:**
- Ask "what would have to be true for this assumption to be false?"
- Seek disconfirming evidence, not just confirming
- Run cheap experiments before committing
- Distinguish observation from interpretation

---

## Anchor 7: Two Truths Exist

**What:** Seemingly contradictory ideas can both be true simultaneously. Embrace paradox instead of forcing false choices.

**Examples:**
- Design can be both fast AND thoughtful
- Simplicity requires complexity in implementation
- User needs AND business needs can coexist
- Convention AND innovation both have value
- Data AND intuition are both valid inputs

**When to rely on it:**
- Facing "either/or" framing
- Mediating stakeholder conflicts
- Feeling stuck between opposing ideas
- Making trade-off decisions

**How to apply:**
- Reframe "or" as "and" — how might both be true?
- Look for higher-order solutions that satisfy multiple constraints
- Accept tension as feature, not bug
- Avoid premature resolution of ambiguity

---

## Using Anchors in Practice

**Before a project:** Review relevant anchors, set intentions

**During pressure:** Pause, identify which anchor applies, act accordingly

**After setbacks:** Return to anchors to regain footing

**Periodically:** Reflect on how your anchors are evolving

Anchors aren't rules to follow—they're foundations to build on.


path: references/02-information-scaffold.md
content: # Information Scaffold: Psychology, Economics, Accessibility, Defaults

Your scaffold = pre-made decisions for recurring situations. Build once, reuse forever.

---

## Design Psychology Reference

Psychological principles categorized by the problem they solve:

### Filtering (Helping users focus)

| Principle | Definition | Application |
|-----------|------------|-------------|
| **Hick's Law** | More options = harder decisions | Reduce choices, progressive disclosure |
| **Law of Proximity** | Close objects perceived as related | Group related items spatially |
| **Law of Similarity** | Visually similar elements perceived as related | Consistent styling for related items |
| **Nudging** | Subtle cues influence behavior | Defaults, visual emphasis, copy |
| **Priming** | Cues influence decision-making | Strategic first impressions, context setting |
| **Progressive Disclosure** | Reveal information gradually | Hide complexity until needed |
| **Tesler's Law** | Complexity must exist somewhere | Absorb complexity in design, not user's head |
| **Von Restorff Effect** | Distinctive items remembered | Make key actions visually distinct |

### Sense-making (Helping users understand)

| Principle | Definition | Application |
|-----------|------------|-------------|
| **Chunking** | Group info into digestible units | Cards, sections, tabs |
| **Cognitive Load Theory** | Working memory is limited | Minimize extraneous info |
| **Jakob's Law** | Users expect your site to work like others | Follow conventions |
| **Law of Common Region** | Fenced objects perceived as related | Use containers, borders |
| **Law of Prägnanz** | Simpler objects easier to process | Reduce visual complexity |
| **Law of Uniform Connectedness** | Connected elements perceived as related | Use lines, shared containers |
| **Occam's Razor** | Prefer simpler explanations | Simplify UI and messaging |
| **Social Proof** | People conform to observed behavior | Testimonials, user counts |

### Efficiency (Helping users act faster)

| Principle | Definition | Application |
|-----------|------------|-------------|
| **Fitt's Law** | Larger, closer targets faster to hit | Size CTAs appropriately, reduce distance |
| **Goal Gradient Effect** | Motivation increases near goal completion | Progress indicators, milestone celebrations |
| **Hyperbolic Discounting** | Immediate rewards valued higher | Quick wins, instant feedback |
| **IKEA Effect** | People value what they helped create | Customization, personalization |
| **Investment Loops** | Engagement increases with investment | Progressive commitment |
| **Pareto Principle** | 80% of effects from 20% of causes | Optimize critical paths |
| **Parkinson's Law** | Work expands to fill time available | Set clear scope, deadlines |
| **Second-Order Effects** | Consequences have consequences | Consider downstream impact |
| **Sunk Cost Effect** | Continued investment despite poor returns | Beware over-commitment |
| **Weber's Law** | Large changes more noticeable | Meaningful differences in UI states |

### Recall (Helping users remember)

| Principle | Definition | Application |
|-----------|------------|-------------|
| **Fresh Start Effect** | Motivation at new beginnings | Leverage time-based resets |
| **Miller's Law** | 7±2 items in short-term memory | Chunk information |
| **Peak-End Rule** | Experiences judged by peak and end | Design strong endings |
| **Picture Superiority Effect** | Images more memorable than text | Use visuals for key info |
| **Serial Position Effect** | First/last items most memorable | Place key items at start/end |
| **Zeigarnik Effect** | Incomplete tasks remembered more | Use incomplete states strategically |

---

## Economics Fundamentals

Design decisions have business implications. Know these concepts:

| Concept | Definition | Design Implication |
|---------|------------|-------------------|
| **Economies of Scale** | More production = lower unit cost | Reusable components pay dividends at scale |
| **Opportunity Cost** | What you give up by choosing | Every design choice excludes alternatives |
| **Time Value of Money** | Money now > money later | Ship valuable features sooner |
| **Supply & Demand** | Scarcity drives price | Exclusive features, limited access can increase perceived value |
| **Zero Marginal Cost** | Digital copies cost nothing extra | Design for scale, not scarcity |
| **Network Effects** | Value increases with users | Prioritize collaboration, sharing features |
| **Diseconomies of Scale** | Too big = inefficient | Complexity costs increase; keep systems manageable |
| **Economies of Scope** | Cheaper to do multiple things together | Shared components across products |
| **Veblen Goods** | Higher price = higher demand (luxury) | Premium positioning affects design choices |
| **Invisible Hand** | Markets self-regulate | User choice will surface winners |

---

## Accessibility Reference (POUR)

WCAG's four principles. Accessibility is not optional.

### Perceivable
- Text alternatives for non-text content
- Captions/transcripts for multimedia
- User can change presentation
- Content easier to see and hear

### Operable
- All functionality accessible via keyboard
- Users have enough time to read/use content
- No seizure-inducing content
- Easy navigation and content finding
- Input modalities beyond keyboard

### Understandable
- Text and UI readable and understandable
- Content operates in predictable ways
- Help users avoid and correct mistakes

### Robust
- Compatible with browsers and assistive tech
- Valid markup

**Minimum baseline:** 4.5:1 contrast ratio for text, focus indicators, alt text, semantic HTML.

---

## Default Typefaces

Choose one neutral sans-serif to start. Add personality later.

**Recommended starting typefaces:**
- Inter
- Nunito Sans
- Mona Sans
- SF Pro (Apple ecosystem)
- Segoe UI (Microsoft ecosystem)

### Default Type Scale

Start with 16px base (browser default). Use this scale:

| Size | Use |
|------|-----|
| 12px | Captions, labels, metadata |
| 14px | Secondary text, descriptions |
| 16px | Body text (base) |
| 18px | Large body, intro text |
| 20px | Small headings |
| 24px | Section headings |
| 30px | Page headings |
| 36px | Feature headings |
| 48px | Hero headings |
| 60px+ | Display text |

---

## Default Design Rules

Establish these defaults to avoid re-deciding:

### Spacing
- Base unit: 8px
- Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96
- Use consistent rhythm

### Colors
- One primary action color
- One or two neutral grays
- Semantic colors: error (red), success (green), warning (yellow), info (blue)
- Ensure contrast ratios

### Icons
Pick one library and stick to it:
- Feather Icons (minimal)
- Heroicons (Tailwind)
- Phosphor Icons (flexible)
- Material Icons (comprehensive)

### Radius
- Consistent border-radius across components
- Common: 4px (subtle), 8px (soft), 16px+ (rounded)

### Shadows/Elevation
- 3-4 levels of elevation
- Consistent shadow direction
- Use for layering, not decoration

---

## Atomic Design Principles

Design systems built on composition:

1. **Atoms** — Basic elements (buttons, inputs, labels)
2. **Molecules** — Simple component groups (search box = input + button)
3. **Organisms** — Complex components (header, card grid)
4. **Templates** — Page layouts without content
5. **Pages** — Templates with real content

Build from small to large. Composition enables reuse.

---

## Nielsen's 10 Usability Heuristics

Quick reference for heuristic evaluation:

1. **Visibility of system status** — Keep users informed
2. **Match between system and real world** — Speak users' language
3. **User control and freedom** — Support undo, exits
4. **Consistency and standards** — Follow conventions
5. **Error prevention** — Prevent problems before they occur
6. **Recognition over recall** — Make options visible
7. **Flexibility and efficiency** — Shortcuts for experts
8. **Aesthetic and minimalist design** — Remove unnecessary elements
9. **Help users recognize, diagnose, recover from errors** — Clear error messages
10. **Help and documentation** — Easy to search, task-focused


path: references/10-checklist-new-interfaces.md
content: # Checklist: Designing New Interfaces

A 6-step process for approaching any new interface from scratch.

---

## Step 1: Define the System

Understand the technical and contextual landscape before designing.

### Key Questions

☐ **What type of system is this?**
- Web application — Cross-platform, easy updates, limited hardware access
- Mobile app — Native performance, deep device integration, separate iOS/Android
- Desktop software — Full processing power, deep system access, requires updates
- Embedded system — Fixed hardware, task-specific, constrained resources

☐ **What are the platform constraints?**
- Screen sizes and orientations
- Input methods (touch, mouse, keyboard, voice)
- Performance requirements
- Offline capabilities needed?

☐ **What data inputs/outputs exist?**
- How do users get data in?
- How do users get data out?
- What integrations are required?

### Best Practices
- Match the system type to user needs and contexts
- Consider browser extensions, mobile companions for web apps
- Prioritize input methods that fit user context

---

## Step 2: Model User Tasks

Define who users are and what they need to accomplish.

### Key Questions

☐ **Who are the different user types?**
- What roles exist?
- What permissions should each role have?
- What are their distinct needs?

☐ **What are primary tasks users need to accomplish?**
- What are the jobs-to-be-done?
- How do tasks break into step-by-step workflows?
- What are entry points, decision points, and endpoints?

☐ **How will users CRUD data?**
- Create, Read, Update, Delete flows
- Necessary sequencing and granularity
- Bulk operations needed?

☐ **What are key data entities?**
- What objects do users interact with?
- How are entities related? (1:1, 1:many, many:many)
- What's the data model?

### Best Practices
- Focus on most frequent and important tasks first
- Use simple, clear language for task descriptions
- Validate task models with user research or feedback
- Label buttons with actions ("Add Content" not "Submit")

---

## Step 3: Organize Information

Structure content and navigation before visual design.

### Key Questions

☐ **What are the high-level categories/sections?**
- Main content areas or features?
- How can categories be logically grouped?

☐ **What are relationships and hierarchies?**
- What's the hierarchy of importance?
- Which entities relate to which? (1:many, many:many)

☐ **What are primary and secondary navigation patterns?**
- Main nav menu structure?
- Contextual or in-page nav needed?
- Breadcrumbs? Secondary nav?

☐ **What content and actions should be prioritized?**
- What info is critical for task completion?
- How can visual hierarchy guide users?

### Best Practices
- Use card sorting or tree testing to validate IA
- Follow established conventions for nav
- Provide clear labels and signposts
- Use breadcrumbs for deep hierarchies

---

## Step 4: Gather Design Inspiration

Research before creating. Stand on shoulders of giants.

### Choose Your Originality Level

1. **Direct copies** — Replicate existing patterns exactly (fastest, least differentiation)
2. **Remixes** — Combine elements from multiple sources
3. **Indirect parallels** — Inspiration from different domains solving similar problems
4. **Metaphors/analogies** — Real-world concepts informing design
5. **True innovation** — New patterns from first principles (slowest, highest risk)

### Inspiration Sources

**Standard:**
- Dribbble, Behance, Awwwards, Pinterest

**More interesting:**
- ProductHunt — How startups differentiate
- Layers.to — Higher quality than Dribbble
- Pageflows.com — User flows of popular apps
- Mobbin.com — Mobile pattern library
- Teardowns.ai — AI feature patterns

### Best Practices
- Focus on examples matching your project constraints
- Look beyond direct competitors to adjacent domains
- Create moodboards and organized collections
- Annotate what works and what doesn't

---

## Step 5: Generate Rapid Ideas

Quantity before quality. Explore widely before refining.

### Key Activities

☐ **Sketch 6+ low-fidelity concepts**
- Don't judge while creating
- Set a timer (15-30 min)
- Explore diverse approaches

☐ **Vary the fundamentals**
- Different layouts
- Different navigation approaches
- Different information hierarchies
- Different interaction patterns

☐ **Focus on structure, not style**
- Boxes and labels, not colors and fonts
- Workflow and flow, not polish

### Idea Generation Techniques

- **Crazy 8s** — 8 ideas in 8 minutes
- **Worst possible idea** — Then invert
- **How would [X company] do this?** — Steal mental models
- **Analogy mapping** — How does [unrelated domain] solve this?
- **Constraint removal** — What if we had no [budget/time/tech] limits?

### Best Practices
- Timebox ideation to prevent overthinking
- Don't fall in love with first idea
- Involve others for diverse perspectives
- Compare against JTBD to evaluate

---

## Step 6: Enhance Fidelity

Move from concept to detailed design.

### Fidelity Progression

1. **Wireframes** — Structure and layout
2. **Low-fi mockups** — Basic styling, real content
3. **High-fi mockups** — Full visual design
4. **Interactive prototypes** — Testable flows

### Key Questions for Enhancement

☐ **Are all component states defined?**
- Default, hover, active, focus, disabled, loading, error

☐ **Are all interactions specified?**
- Primary interactions (clicks, taps)
- Secondary interactions (hovers, long-press)
- Gestures and shortcuts

☐ **Is content scalability addressed?**
- Empty states
- Minimal content
- Maximum/overflow content
- Edge cases

☐ **Is system feedback clear?**
- Loading states
- Success/error feedback
- Progress indicators

☐ **Is user input handled?**
- Validation states
- Error messages
- Help text

☐ **Is navigation complete?**
- All pages/views connected
- Back navigation
- Deep linking

### Best Practices
- Apply fidelity checklists (see 11-checklist-fidelity.md)
- Apply visual style checklists (see 12-checklist-visual-style.md)
- Test with real content, not lorem ipsum
- Review against JTBD and macro bets

---

## Quick Reference: 6-Step Summary

| Step | Focus | Output |
|------|-------|--------|
| 1. Define System | Platform, constraints, data | System requirements doc |
| 2. Model Tasks | Users, workflows, entities | Task flows, CRUD maps |
| 3. Organize Info | Categories, hierarchy, nav | Information architecture |
| 4. Gather Inspiration | Research, patterns, references | Moodboard, pattern library |
| 5. Generate Ideas | Divergent exploration | 6+ wireframe concepts |
| 6. Enhance Fidelity | Detail, polish, edge cases | High-fi designs, prototypes |

**Rule:** Resist the urge to skip to Step 6. Steps 1-5 make Step 6 dramatically faster and better.


path: references/11-checklist-fidelity.md
content: # Checklist: Improving Fidelity

Systematic checks for completing interface designs beyond the happy path.

---

## Component States

Every interactive component needs these states defined:

### Core States

☐ **Default** — Resting state, no interaction
☐ **Hover** — Cursor over element (desktop)
☐ **Active/Pressed** — During click/tap
☐ **Focus** — Keyboard navigation highlight
☐ **Disabled** — Not currently interactive
☐ **Loading** — Processing/fetching
☐ **Error** — Invalid state
☐ **Success** — Action completed

### Additional States by Component Type

**Buttons:**
☐ Primary, secondary, tertiary variants
☐ Icon-only versions
☐ With/without icons
☐ Size variants (small, medium, large)

**Inputs:**
☐ Empty, filled, placeholder
☐ Valid, invalid, warning
☐ With helper text, error message
☐ Required indicator
☐ Read-only, disabled

**Checkboxes/Radios:**
☐ Unchecked, checked, indeterminate
☐ Disabled states for each

**Toggles:**
☐ On, off, disabled
☐ With labels, without labels

**Links:**
☐ Default, visited, hover, active, focus

---

## Primary Interactions

Main actions users take with the interface.

### Click/Tap Interactions

☐ **Touch targets** — Minimum 44x44px (mobile), 32x32px (desktop)
☐ **Hit areas** — Larger than visual element when needed
☐ **Feedback** — Immediate visual response to tap
☐ **Double-click/tap** — Behavior defined or prevented

### Form Submissions

☐ **Submit button states** — Enabled only when valid
☐ **In-progress feedback** — Loading indicator
☐ **Success confirmation** — Clear completion message
☐ **Error handling** — What happens when it fails?
☐ **Re-submission** — Can users retry?

### Selection Interactions

☐ **Single selection** — Radio buttons, dropdowns
☐ **Multi-selection** — Checkboxes, multi-select
☐ **Range selection** — Shift-click behavior
☐ **Select all/none** — Bulk selection

---

## Secondary Interactions

Supporting interactions beyond primary actions.

### Hover Interactions (Desktop)

☐ **Tooltips** — Delay before showing (300-500ms)
☐ **Preview cards** — Information on hover
☐ **Menu reveals** — Dropdown on hover vs. click
☐ **State changes** — Visual feedback on hover

### Long-Press (Mobile)

☐ **Context menus** — What actions appear?
☐ **Drag initiation** — Does long-press start drag?
☐ **Haptic feedback** — Vibration on trigger?

### Keyboard Interactions

☐ **Tab order** — Logical focus sequence
☐ **Enter/Space** — Activate focused element
☐ **Escape** — Close modals, cancel actions
☐ **Arrow keys** — Navigate within components
☐ **Shortcuts** — Power user key combinations

### Gestures (Mobile/Touch)

☐ **Swipe** — Horizontal/vertical actions
☐ **Pinch/zoom** — Image viewing, maps
☐ **Pull-to-refresh** — List refresh
☐ **Drag and drop** — Reordering

---

## Content Scalability

Designs must handle variable content.

### Empty States

☐ **First-time user** — No data yet, clear CTA to start
☐ **No results** — Search/filter with no matches
☐ **Deleted content** — After removing items
☐ **Error state** — Failed to load

**Empty state must include:**
- Explanation of why empty
- What user can do (CTA)
- Visual to reduce starkness

### Minimal Content

☐ **One item in list** — Does layout still work?
☐ **Short text** — Single word titles, descriptions
☐ **Missing optional fields** — Graceful absence

### Maximum Content

☐ **Long text** — Truncation with ellipsis, tooltips
☐ **Many items** — Pagination, infinite scroll, virtualization
☐ **Long words** — Word-break behavior
☐ **Large images** — Aspect ratio handling

### Edge Cases

☐ **Special characters** — Unicode, emoji, RTL text
☐ **Numbers** — Negative, decimals, large numbers
☐ **Dates** — Different formats, timezones
☐ **Names** — Mononyms, very long names, special characters

---

## System Feedback

How the interface communicates state to users.

### Loading States

☐ **Initial load** — Skeleton screens, spinners
☐ **Action processing** — Button loading state
☐ **Background loading** — Subtle indicators
☐ **Partial loading** — Progressive content reveal

**Rules:**
- < 100ms: No indicator needed
- 100ms-1s: Simple spinner
- 1s+: Progress indicator or skeleton
- 10s+: Background processing with notification

### Success Feedback

☐ **Inline confirmation** — Check marks, color changes
☐ **Toast notifications** — Non-blocking success messages
☐ **Page transitions** — Navigate to success state
☐ **Celebrations** — Milestone achievements

### Error Feedback

☐ **Inline errors** — Field-level validation
☐ **Summary errors** — Form-level error list
☐ **System errors** — Server/network failures
☐ **Recovery guidance** — What can user do?

### Progress Indicators

☐ **Determinate** — Known duration (progress bar with %)
☐ **Indeterminate** — Unknown duration (spinner)
☐ **Steps** — Multi-step process indicator
☐ **Upload/download** — File transfer progress

---

## User Input

Handling all forms of user data entry.

### Text Input

☐ **Character limits** — Max length with counter
☐ **Input masks** — Phone, credit card, date formats
☐ **Autocomplete** — Suggestions while typing
☐ **Auto-capitalization** — Appropriate for input type
☐ **Spell check** — Enabled/disabled appropriately

### Validation

☐ **Real-time validation** — Validate as user types
☐ **On-blur validation** — Validate when leaving field
☐ **On-submit validation** — Final check before submit
☐ **Error message placement** — Below field, inline
☐ **Error message content** — Clear, actionable

### Input Types

☐ **Text** — Default, email, password, URL, search
☐ **Number** — With constraints (min, max, step)
☐ **Date/time** — Native or custom pickers
☐ **File upload** — Drag-drop, click to browse
☐ **Rich text** — Formatting toolbar

### Accessibility

☐ **Labels** — Every input has a label
☐ **Placeholders** — Not used as labels
☐ **Error announcements** — Screen reader accessible
☐ **Required fields** — Clearly indicated

---

## Navigation

Moving through the interface.

### Global Navigation

☐ **Current location** — Where am I?
☐ **Available destinations** — Where can I go?
☐ **Path taken** — How did I get here? (breadcrumbs)
☐ **Return path** — How do I go back?

### State Preservation

☐ **Browser back** — Does it work as expected?
☐ **Deep linking** — Can users share URLs to specific states?
☐ **Form state** — Is data preserved on navigation?
☐ **Scroll position** — Preserved or reset appropriately?

### Transitions

☐ **Page transitions** — Consistent animation pattern
☐ **Loading transitions** — Skeleton to content
☐ **Modal/drawer open/close** — Smooth animations
☐ **List additions/removals** — Animated changes

---

## Quick Fidelity Audit

Use this for rapid checks:

| Category | ✓ | Notes |
|----------|---|-------|
| All component states defined | | |
| Primary interactions specified | | |
| Secondary interactions specified | | |
| Empty states designed | | |
| Max content handling defined | | |
| Loading states defined | | |
| Success/error feedback defined | | |
| All inputs validated | | |
| Navigation complete | | |
| Keyboard accessible | | |


path: references/12-checklist-visual-style.md
content: # Checklist: Improving Visual Style

Systematic checks for visual design consistency and quality.

---

## Spacing

Consistent rhythm creates visual harmony.

### Spacing System

☐ **Base unit defined** — Usually 4px or 8px
☐ **Scale established** — e.g., 4, 8, 12, 16, 24, 32, 48, 64
☐ **Consistent application** — Same spacing for same relationships

### Spacing Types

☐ **Padding** — Space inside containers
☐ **Margin** — Space between elements
☐ **Gap** — Space in flex/grid layouts
☐ **Gutters** — Space between columns

### Spacing Relationships

☐ **Related items closer** — Law of Proximity
☐ **Unrelated items farther** — Visual grouping
☐ **Hierarchy through spacing** — More space = more importance
☐ **Breathing room** — Adequate whitespace

### Common Issues

- Inconsistent spacing between similar elements
- Too little whitespace (cramped)
- Too much whitespace (disconnected)
- Padding/margin not on the spacing scale

---

## Colors

Color communicates meaning and creates hierarchy.

### Color System

☐ **Primary color** — Brand/action color
☐ **Secondary color** — Supporting accent
☐ **Neutral palette** — Grays for text, backgrounds, borders
☐ **Semantic colors** — Error, success, warning, info

### Color Usage

☐ **Text colors** — Primary, secondary, disabled, placeholder
☐ **Background colors** — Surface hierarchy (elevated, base, sunken)
☐ **Border colors** — Default, focus, error
☐ **Interactive states** — Hover, active, focus variations

### Color Accessibility

☐ **Contrast ratios** — 4.5:1 for normal text, 3:1 for large text
☐ **Not color alone** — Don't rely solely on color to convey info
☐ **Color blindness** — Test with simulators
☐ **Dark mode** — Colors work in both modes

### Common Issues

- Too many colors (lack of cohesion)
- Insufficient contrast
- Inconsistent semantic usage (different reds for errors)
- Color used as only differentiator

---

## Elevation

Visual layers create depth and hierarchy.

### Elevation Levels

☐ **Level 0** — Base surface (no shadow)
☐ **Level 1** — Slight elevation (cards, sections)
☐ **Level 2** — Moderate elevation (dropdowns, popovers)
☐ **Level 3** — High elevation (modals, dialogs)
☐ **Level 4** — Highest elevation (toasts, tooltips above modals)

### Shadow Properties

☐ **Consistent direction** — Light source consistent
☐ **Blur radius** — Increases with elevation
☐ **Spread** — Usually minimal
☐ **Opacity** — Decreases with distance
☐ **Color** — Usually dark gray/black, can be colored

### Elevation Usage

☐ **Interactive elements** — Buttons may elevate on hover
☐ **Overlay content** — Modals, drawers clearly elevated
☐ **Sticky elements** — Headers/navs elevated when scrolling
☐ **Focus indication** — Can supplement or replace outlines

### Common Issues

- Inconsistent shadow direction
- Too many elevation levels
- Shadows too harsh or too subtle
- Elevation doesn't match interaction hierarchy

---

## Iconography

Icons support comprehension and reduce text.

### Icon System

☐ **Single icon library** — Consistent style
☐ **Consistent stroke/fill** — Don't mix styles
☐ **Size scale** — 16, 20, 24, 32, 48 (or similar)
☐ **Consistent grid** — Icons align to same grid

### Icon Usage

☐ **With text labels** — For unclear icons
☐ **Standalone** — Only for universally understood (close, search, home)
☐ **In buttons** — Left or right of text consistently
☐ **In navigation** — Supplement text, not replace
☐ **As status** — Error, success, warning indicators

### Icon Accessibility

☐ **Alt text/aria-label** — For meaningful icons
☐ **aria-hidden** — For decorative icons
☐ **Touch targets** — 44x44px minimum for tappable icons
☐ **Color contrast** — Icons meet contrast requirements

### Common Issues

- Mixed icon styles (outline + filled)
- Icons without labels where meaning unclear
- Inconsistent icon sizes
- Too many unique icons

---

## Typography

Text is the primary interface. Make it work.

### Type Scale

☐ **Scale established** — Limited set of sizes (7-10)
☐ **Consistent usage** — Same size for same purpose
☐ **Responsive scaling** — Appropriate for device

### Type Hierarchy

☐ **H1-H6** — Clear heading hierarchy
☐ **Body text** — Primary and secondary
☐ **Captions/labels** — Small supporting text
☐ **Display text** — Hero/feature text

### Type Properties

☐ **Line height** — 1.4-1.6 for body, 1.1-1.3 for headings
☐ **Letter spacing** — Adjusted for size (tighter large, looser small)
☐ **Font weight** — 2-3 weights max
☐ **Max line length** — 45-75 characters for readability

### Type Accessibility

☐ **Minimum size** — 16px for body text
☐ **Contrast** — 4.5:1 ratio
☐ **Scalability** — Works when user zooms
☐ **Font choice** — Legible at small sizes

### Common Issues

- Too many font sizes
- Inconsistent line heights
- Lines too long (hard to read)
- Insufficient contrast on secondary text

---

## Imagery & Illustrations

Visual content enhances understanding and tone.

### Image Usage

☐ **Consistent style** — Photography style or illustration style
☐ **Appropriate aspect ratios** — Consistent crops
☐ **Quality** — High resolution, appropriate compression
☐ **Relevance** — Images support content, not decorate

### Image Treatments

☐ **Placeholders** — Loading states for images
☐ **Error states** — Broken image handling
☐ **Cropping** — Consistent crop ratios
☐ **Filters/overlays** — Consistent treatment

### Image Accessibility

☐ **Alt text** — Descriptive for meaningful images
☐ **Empty alt** — For decorative images
☐ **Text in images** — Avoided or duplicated in HTML
☐ **Color contrast** — Text over images readable

### Illustration Guidelines

☐ **Consistent style** — Same illustrator or style guide
☐ **Color palette** — Within brand colors
☐ **Stroke weights** — Consistent with icons
☐ **Character design** — If using people, consistent representation

---

## Motion & Animation

Movement creates meaning and delight.

### Animation Purposes

☐ **Feedback** — Response to user action
☐ **Orientation** — Help users understand spatial relationships
☐ **Attention** — Draw focus to important changes
☐ **Continuity** — Smooth transitions between states

### Animation Properties

☐ **Duration** — 100-500ms typical (faster = less important)
☐ **Easing** — Ease-out for entrances, ease-in for exits
☐ **Consistency** — Same duration for same type of animation
☐ **Purpose** — Every animation has a reason

### Animation Best Practices

☐ **Prefer transforms** — translate, scale, rotate, opacity (performant)
☐ **Avoid layout thrash** — Don't animate width, height, position
☐ **Reduce motion** — Respect prefers-reduced-motion
☐ **Subtlety** — Most animations should be barely noticed

### Common Issues

- Animations too slow (feel sluggish)
- Animations too fast (miss the feedback)
- Gratuitous animation (no purpose)
- Inconsistent easing/duration
- Ignoring accessibility preferences

---

## Texture & Patterns

Surface treatments add depth and character.

### Texture Types

☐ **Subtle gradients** — Add depth without distraction
☐ **Background patterns** — Subtle, non-distracting
☐ **Noise/grain** — Adds warmth to flat colors
☐ **Glass effects** — Blur, transparency (use sparingly)

### Usage Guidelines

☐ **Subtlety** — Textures shouldn't compete with content
☐ **Purpose** — Differentiate surfaces, add depth
☐ **Consistency** — Same treatment for same surface type
☐ **Performance** — Consider render cost

### Common Issues

- Textures too prominent
- Inconsistent texture usage
- Performance impact from complex textures
- Reduced legibility from background patterns

---

## Visual Style Audit

Quick checks for visual consistency:

| Element | ✓ | Notes |
|---------|---|-------|
| Spacing on scale | | |
| Color palette limited | | |
| Contrast accessible | | |
| Elevation consistent | | |
| Single icon style | | |
| Type scale limited | | |
| Line heights consistent | | |
| Images consistent style | | |
| Animations purposeful | | |
| Reduced motion respected | | |


path: references/13-checklist-innovation.md
content: # Checklist: Innovation & Originality

The 5 levels of the originality spectrum and when to use each.

---

## The Originality Spectrum

Not all design work requires innovation. Choose your level intentionally.

```
Lower Risk                                                    Higher Risk
Faster                                                        Slower
├─────────┼─────────┼─────────┼─────────┼─────────┤
Direct    Remixes   Indirect   Metaphors  True
Copies              Parallels  & Analogies Innovation
```

---

## Level 1: Direct Copies

**What:** Replicate existing design patterns exactly.

### When to Use

- Velocity is critical, differentiation isn't
- Users expect familiar patterns
- Internal tools, admin interfaces
- Proven patterns for common problems
- Low-stakes decisions

### How to Execute

☐ Identify the pattern you're copying
☐ Understand *why* it works (not just *what*)
☐ Copy the principles, adapt the details
☐ Ensure it fits your context
☐ Give credit where appropriate

### Examples

- Using a competitor's checkout flow structure
- Implementing Material Design's data table exactly
- Copying iOS settings page patterns

### Risks

- Legal issues (if copying proprietary designs too closely)
- Doesn't differentiate your product
- May not fit your specific context

---

## Level 2: Remixes

**What:** Combine elements from multiple sources into a new composition.

### When to Use

- Want some differentiation with low risk
- Multiple good patterns exist, none perfect
- Combining best practices from different products
- Adapting patterns to new contexts

### How to Execute

☐ Identify 2-3 source patterns
☐ Extract the best elements from each
☐ Combine intentionally (not randomly)
☐ Test the combination works cohesively
☐ Document the sources and your reasoning

### Examples

- Slack's message composer (combines messaging patterns from multiple products)
- Notion's database views (combines spreadsheet + database + card patterns)
- A mobile nav that combines iOS and Android conventions

### Risks

- Frankensteining (incoherent combinations)
- Losing what made original patterns work
- Overcomplicating by adding too many elements

---

## Level 3: Indirect Parallels

**What:** Draw inspiration from designs in different domains that solve similar problems.

### When to Use

- Direct competitors have similar solutions
- Looking for fresh perspectives
- The core problem is domain-agnostic
- Want to surprise users (positively)

### How to Execute

☐ Define the core problem (abstractly)
☐ Identify other domains with the same problem
☐ Research how those domains solve it
☐ Translate the solution to your context
☐ Validate it works for your users

### Examples

- Netflix content discovery → B2B product recommendations
- Video game skill trees → Learning platform progression
- Restaurant reservation flow → Meeting scheduling
- Music playlist curation → Content organization

### Good Cross-Domain Sources

- Gaming (engagement, progression, feedback)
- E-commerce (conversion, product display)
- Social media (engagement, sharing, discovery)
- Maps/navigation (wayfinding, spatial organization)
- Publishing (content hierarchy, reading experience)

### Risks

- Translation may not work across domains
- Users may not understand the metaphor
- Over-reaching can feel forced

---

## Level 4: Metaphors & Analogies

**What:** Use concepts from the real world to inform your design.

### When to Use

- Introducing new/unfamiliar concepts
- Making abstract concepts concrete
- Creating memorable mental models
- Building on existing user knowledge

### How to Execute

☐ Identify the concept users need to understand
☐ Find a familiar real-world analog
☐ Map the relationships (what matches, what doesn't)
☐ Use language and visuals from the metaphor
☐ Don't over-extend the metaphor

### Classic Metaphors in Software

| Metaphor | Software Concept |
|----------|-----------------|
| Desktop | OS file management |
| Folder | Directory |
| Trash can | Deleted files |
| Shopping cart | Checkout |
| Inbox | Messages |
| Library | Content collection |
| Dashboard | Metrics overview |
| Workspace | Project environment |

### Creating New Metaphors

☐ The metaphor should simplify, not complicate
☐ The mapping should be intuitive
☐ Don't force all aspects to match
☐ Test if users understand the metaphor
☐ Be consistent once you commit

### Risks

- Metaphor breaks down at edge cases
- Users don't share the cultural reference
- Constrains design to fit the metaphor
- Can feel gimmicky if overdone

---

## Level 5: True Innovation

**What:** Create entirely new design patterns from first principles.

### When to Use

- Existing patterns don't solve the problem
- Creating a new product category
- Technical breakthrough enables new interactions
- Differentiation is critical competitive advantage
- You have time and resources to iterate

### How to Execute

☐ Define the problem from first principles
☐ Question all assumptions about current solutions
☐ Explore multiple radical approaches
☐ Prototype and test extensively
☐ Be prepared to fail and iterate
☐ Document your learnings

### First Principles Questions

- What is the user actually trying to accomplish?
- Why do we do it this way? What if we didn't?
- What constraints are real vs. assumed?
- What would this look like with no constraints?
- What new technology/capability enables a different approach?

### Examples of True Innovation

- iPhone's multitouch interface (2007)
- Notion's blocks-based content model
- Figma's multiplayer design editing
- Linear's keyboard-first interface
- Superhuman's command-k pattern

### Risks

- High failure rate
- Significant time and resource investment
- Users may not adopt unfamiliar patterns
- May solve a problem users don't have
- Competitors can copy if successful

---

## Choosing Your Level

### Decision Framework

| Factor | Lower Originality | Higher Originality |
|--------|------------------|-------------------|
| Time available | Limited | Ample |
| Risk tolerance | Low | High |
| User sophistication | General | Early adopters |
| Market maturity | Established | Emerging |
| Differentiation need | Low | Critical |
| Pattern clarity | Clear best practice | No clear winner |

### By Context

| Context | Recommended Level |
|---------|------------------|
| Internal tools | 1 (Direct copies) |
| Commodity features | 1-2 (Copies, Remixes) |
| Core product features | 2-3 (Remixes, Parallels) |
| Key differentiators | 3-4 (Parallels, Metaphors) |
| New categories | 4-5 (Metaphors, Innovation) |

---

## Innovation Process

When pursuing higher originality levels:

### 1. Diverge Widely

- Generate many options (10+)
- Include "bad" ideas
- Cross-pollinate from unexpected sources
- Don't evaluate while generating

### 2. Prototype Rapidly

- Build to learn, not to ship
- Test core assumptions early
- Fail fast, learn faster
- Increase fidelity incrementally

### 3. Validate Thoroughly

- Test with real users
- Measure against JTBD
- Compare to existing solutions
- Be willing to abandon

### 4. Document Learnings

- What worked and didn't
- Unexpected discoveries
- Principles that emerged
- Recommendations for future

---

## Innovation Audit

Before pursuing originality:

| Question | Answer |
|----------|--------|
| Why is innovation needed here? | |
| What's the risk if we fail? | |
| Do we have time to iterate? | |
| What's our differentiation goal? | |
| What's the simplest option that might work? | |
| Have we validated user need? | |


path: references/20-patterns-chunking.md
content: # Patterns: Chunking

Patterns for breaking content into digestible, organized units.

---

## What is Chunking?

Breaking complex information into smaller, manageable pieces that users can process and remember more easily. Based on Miller's Law (7±2 items in working memory).

**Core principle:** Users can't process everything at once. Group related items, separate unrelated items.

---

## Card-Based Layouts

**What:** Contained units of related content with clear boundaries.

### Benefits & Use Cases

- **Scannable** — Users quickly identify relevant cards
- **Self-contained** — Each card is a complete unit
- **Flexible** — Cards work in grids, lists, or carousels
- **Actionable** — Cards can be interactive (click, expand, drag)

### Psychological Principles

- **Law of Common Region** — Boundary creates relatedness
- **Chunking** — Content grouped into digestible units
- **Recognition over recall** — Visual cards easier to scan

### Implementation Guidelines

**DO:**
- Clear visual boundary (border, shadow, or background)
- Consistent card structure across the set
- Visual hierarchy within the card (image → title → description → actions)
- Appropriate sizing for content (not too cramped or empty)
- Interactive states (hover, selected)

**DON'T:**
- Mix card sizes without purpose
- Overload cards with too much content
- Use cards for single items (overkill)
- Nest cards inside cards
- Forget empty states

### Common Variants

| Variant | Use Case |
|---------|----------|
| Media card | Image/video prominent |
| Stat card | Single metric focus |
| Action card | Primary CTA emphasis |
| Profile card | Person/account info |
| Preview card | Summary with expand |

---

## Tabs & Accordions

**What:** Show/hide content sections to reduce visible complexity.

### When to Use Tabs vs. Accordions

| Tabs | Accordions |
|------|------------|
| 2-7 peer sections | Many sections (5+) |
| Mutually exclusive content | Content can stack |
| Horizontal space available | Vertical list format |
| Users need to switch frequently | Users view one at a time |

### Benefits & Use Cases

- **Space efficient** — Show only relevant content
- **User control** — Users choose what to see
- **Progressive disclosure** — Reduce cognitive load
- **Organization** — Clear content categorization

### Psychological Principles

- **Hick's Law** — Fewer visible options = easier decisions
- **Progressive disclosure** — Reveal complexity gradually
- **Miller's Law** — Chunk content into sections

### Implementation Guidelines (Tabs)

**DO:**
- Clear active state
- Limit to 7 tabs (use dropdown for more)
- Descriptive labels (2-3 words)
- Logical order (frequency or process)
- Preserve state when switching

**DON'T:**
- Use tabs for sequential steps (use steppers)
- Mix tabs with different content types
- Use very long labels
- Nest tabs within tabs
- Auto-switch tabs without user action

### Implementation Guidelines (Accordions)

**DO:**
- Clear expand/collapse indicators (chevron, +/-)
- Allow multiple open (usually) or single open (sometimes)
- Animate expansion smoothly
- Keyboard accessible (Enter/Space to toggle)
- Consider default-expanded first item

**DON'T:**
- Nest accordions deeply
- Hide critical information in collapsed sections
- Use vague headers
- Make all sections collapsed by default if users need most of them

---

## Grouped Form Fields

**What:** Related form fields visually grouped together.

### Benefits & Use Cases

- **Scannable** — Related fields easy to locate
- **Logical** — Reflects user mental model
- **Reduced errors** — Related info filled together
- **Progress sense** — Completing groups feels like progress

### Psychological Principles

- **Law of Proximity** — Close items perceived as related
- **Chunking** — Smaller groups easier to process
- **Goal gradient** — Visible progress motivates completion

### Implementation Guidelines

**DO:**
- Group by relationship (personal info, shipping, payment)
- Use visual separation (whitespace, lines, containers)
- Label groups with clear headers
- 3-5 fields per group typically
- Consider two-column layout for short fields

**DON'T:**
- Create groups that are too large
- Separate clearly related fields (first/last name)
- Use inconsistent grouping across forms
- Over-decorate group boundaries

### Common Groupings

| Group | Fields |
|-------|--------|
| Personal | Name, email, phone |
| Address | Street, city, state, zip, country |
| Payment | Card, expiry, CVV, billing address |
| Credentials | Username/email, password, confirm |
| Preferences | Notification settings, privacy |

---

## Pagination

**What:** Breaking large lists into discrete pages.

### Pagination vs. Infinite Scroll vs. Load More

| Pattern | Use When |
|---------|----------|
| **Pagination** | User needs to locate specific items, page numbers meaningful, SEO important |
| **Infinite scroll** | Browsing/discovery, no specific target, continuous consumption (social feeds) |
| **Load more** | Compromise between above, user controls when to load |

### Benefits & Use Cases

- **Orientation** — Users know where they are (page 3 of 10)
- **Shareable** — Deep links to specific pages
- **Performance** — Predictable page loads
- **Completion sense** — Can reach "the end"

### Psychological Principles

- **Chunking** — Content in manageable batches
- **Progress** — Page numbers show advancement
- **Control** — User decides when to load more

### Implementation Guidelines

**DO:**
- Show current page and total pages
- Provide first/last page shortcuts (for many pages)
- Truncate middle pages with ellipsis (1 2 3 ... 10)
- Show items per page (and allow customization)
- Preserve page in URL (deep linking)

**DON'T:**
- Use pagination for < 20 items
- Hide page count
- Break in the middle of logical groups
- Require clicking through many pages for common tasks
- Forget keyboard navigation

### Page Size Guidelines

| Context | Items/Page |
|---------|------------|
| Data tables | 10-50, user configurable |
| Search results | 10-25 |
| Product listings | 12-48 |
| Blog/articles | 5-10 |

---

## Carousels & Sliders

**What:** Horizontal scrollable content, often auto-advancing.

### Benefits & Use Cases

- **Space efficient** — Many items in limited space
- **Visual interest** — Dynamic, engaging
- **Feature highlights** — Hero promotions, featured content
- **Related content** — "You might also like"

### Psychological Principles

- **Curiosity** — Partial visibility entices exploration
- **Chunking** — Subset of content at a time
- **Serial position** — First items get most attention

### Implementation Guidelines

**DO:**
- Show partial next item (indicates more content)
- Clear navigation controls (arrows, dots)
- Allow touch/swipe on mobile
- Consider auto-advance carefully (user control preferred)
- Pause auto-advance on hover/focus

**DON'T:**
- Auto-advance too fast (5+ seconds minimum)
- Use for critical content (users miss it)
- Hide navigation controls
- Use multiple carousels on same page
- Rely on carousel for primary navigation

### Critical Warnings

⚠️ Carousels have notoriously low engagement beyond first item
⚠️ Users often miss carousel content entirely
⚠️ Auto-advance frustrates users trying to read
⚠️ Consider if content is important enough to warrant space without hiding

### Better Alternatives

- Grid of items (all visible)
- Horizontal scroll (user-controlled)
- Featured + list (primary + secondary)
- Accordion (if order matters less)

---

## Chunking Pattern Selection Guide

| User Need | Pattern |
|-----------|---------|
| Compare items | Cards in grid |
| View details on demand | Accordions |
| Switch between categories | Tabs |
| Fill related information | Grouped forms |
| Navigate large sets | Pagination |
| Browse highlights | Carousel (with caution) |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)