@laith-wallace/crisp 1.0.0

package/.claude/skills/crisp-audit.md

@@ -0,0 +1,158 @@
+---
+name: crisp-audit
+description: Full CRISP framework evaluation of a UI design. Scores all five dimensions — Contextual, Responsive, Intelligent, Seamless, Powerful — with P0–P3 severity ratings, benchmarks against Stripe, Linear, Notion, Asana, and Slack, and delivers a prioritised action plan. Use when doing a thorough design review. If .crisp.md exists, load it first for project context.
+user-invocable: true
+---
+
+# /crisp-audit — Full CRISP Evaluation
+
+Analyse the provided design (screenshot, Figma link, or description) with the critical eye of a senior product designer. If `.crisp.md` exists in the project root, load it before beginning — your analysis should be grounded in the specific product context, users, and benchmarks documented there.
+
+## Step 1: 30-Second Scan
+
+Before structured analysis, capture first impressions:
+- **Strengths**: What works immediately
+- **Red Flags**: The most critical issues visible at a glance
+- **Overall Grade**: A–F with one-line justification
+
+## Step 2: CRISP Dimension Scoring
+
+Rate each dimension 1–10 and identify specific violations. Use the failure indicators below as your diagnostic criteria.
+
+### C — Contextual
+**Test:** Can the user tell where they are and what this page does within 5 seconds?
+
+Fail indicators:
+- Generic empty states ("No data available" vs. "You haven't added any deals yet. Add your first one to start tracking.")
+- Missing breadcrumbs or location signals on deep pages
+- Page title or heading doesn't reflect what the user is doing
+- No orientation after a user action ("What just happened?")
+
+Violation examples:
+- Generic "Success" message → Fails C. Tell the user exactly what changed.
+- Empty dashboard with no call-to-action → Fails C. Show what they're missing and how to get it.
+
+### R — Responsive
+**Test:** Does the UI update immediately on every interaction?
+
+Fail indicators:
+- Spinner appears on filter changes, tab switches, or any action the user can predict the result of
+- Click-wait-update patterns where the user has to wait to see their action reflected
+- No hover feedback on interactive elements
+- No loading skeleton — blank space appears while content loads
+
+Violation examples:
+- Spinner on search → Fails R. Use debounced optimistic filtering.
+- Page refresh on form submit → Fails R. Update inline, background sync.
+
+### I — Intelligent
+**Test:** Are we showing insight, not raw data?
+
+Fail indicators:
+- Numbers displayed without context, comparison, or suggested action
+- Blank/empty forms when we already know the user's data
+- No next-best-action when the user reaches a dead end
+- We know the user's history but present them a generic experience
+
+Violation examples:
+- "1,247" with no label, no comparison, no action → Fails I.
+- Empty form when user has done this before → Fails I. Pre-populate from their last session.
+
+### S — Seamless
+**Test:** Are we fitting into their day — not forcing them into ours?
+
+Fail indicators:
+- Redirect to a portal or separate app for a task the user considers routine
+- Forced login to complete an action that could be handled inline or via email
+- Custom UI components that break familiar mental models (e.g. a custom dropdown that doesn't behave like a dropdown)
+- Unnecessary page reloads for contextual tasks
+
+Violation examples:
+- "Open in portal to approve" → Fails S. Inline approval card, one click.
+- Custom date picker with non-standard interactions → Fails S. Use the native or library standard.
+
+### P — Powerful
+**Test:** Is complexity hidden appropriately for each user type?
+
+Fail indicators:
+- All settings visible to all users regardless of role or experience level
+- No keyboard shortcuts for power users
+- No undo — destructive actions are permanent without confirmation
+- Advanced options surfaced to novices who don't need them
+
+Violation examples:
+- 23 settings on the main view → Fails P. Surface 3–5, collapse the rest.
+- Delete with no undo or confirm → Fails P. Soft delete with 5-second undo.
+
+## Step 3: Severity Rating
+
+Rate each violation using this scale:
+
+| Priority | Definition | Example |
+|----------|-----------|---------|
+| P0 | Blocks the user entirely | Empty state with no recovery path |
+| P1 | Major friction — user can work around it but shouldn't have to | Spinner on every filter change |
+| P2 | Noticeable degradation in experience | Generic empty state copy |
+| P3 | Minor polish issue | Missing hover state on secondary action |
+
+## Step 4: Benchmark Comparison
+
+Compare against one or more of these exemplars (or the benchmarks from `.crisp.md`):
+- **Stripe**: Clean, trustworthy, progressive disclosure, excellent error handling
+- **Linear**: Minimal, fast, keyboard-native, excellent micro-interactions
+- **Notion**: Flexible, intuitive, powerful yet approachable, great onboarding
+- **Asana**: Task-focused, clear status indicators, seamless collaboration
+- **Slack**: Clear hierarchy, efficient workflows, contextual design
+
+## Output Format
+
+Structure the audit as:
+
+```
+## CRISP Audit: [Screen/Feature Name]
+
+**Grade: [A–F]** — [One-line verdict]
+
+### 30-Second Impression
+Strengths: [2–3 bullet points]
+Red Flags: [2–3 bullet points]
+
+### CRISP Scorecard
+| Dimension   | Score | Key Violation                        |
+|-------------|-------|--------------------------------------|
+| Contextual  | /10   | [Most critical C failure]            |
+| Responsive  | /10   | [Most critical R failure]            |
+| Intelligent | /10   | [Most critical I failure]            |
+| Seamless    | /10   | [Most critical S failure]            |
+| Powerful    | /10   | [Most critical P failure]            |
+| **Total**   | **/50** |                                    |
+
+### Violations by Priority
+**P0 — Fix immediately**
+- [Dimension tag] [Specific violation] → [Specific fix]
+
+**P1 — Fix this sprint**
+- [Dimension tag] [Specific violation] → [Specific fix]
+
+**P2–P3 — Backlog**
+- [List]
+
+### Quick Wins (high-impact, low-effort)
+- [List]
+
+### Benchmark Comparison
+Compared against [Stripe / Linear / Notion / project benchmark]:
+[2–3 sentences on where this design falls vs. the benchmark]
+
+### Strategic Recommendations
+- [How to elevate to world-class — 2–3 points]
+- [User research questions to validate]
+- [Success metrics to track]
+```
+
+## Analysis Style
+
+- Be direct and specific. "This fails I" is useful. "The UX could be improved" is not.
+- Every violation should have a specific fix, not a direction.
+- Prioritise by user impact, not by what's easiest to say.
+- Reference the user context from `.crisp.md` if available — a violation matters more or less depending on who the user is.

package/.claude/skills/crisp-review.md

@@ -0,0 +1,84 @@
+---
+name: crisp-review
+description: 30-second CRISP design scan. Returns a grade A–F and the top 3 issues by user impact with specific fix suggestions. Use during rapid design iteration when a full audit would slow you down. If .crisp.md exists, load it for project context.
+user-invocable: true
+---
+
+# /crisp-review — Quick CRISP Scan
+
+A fast, high-signal design pass. Not a full audit — a diagnostic. Use this during iteration when you need clear direction, not a comprehensive report.
+
+If `.crisp.md` exists in the project root, load it. Your review should be grounded in the specific product, users, and priorities documented there.
+
+## What to Evaluate
+
+Scan the design against all five CRISP dimensions, but don't score each one individually. Instead:
+
+1. Identify the **single most critical issue per dimension** (if one exists)
+2. From those, surface the **top 3 issues by user impact**
+3. Assign a **grade** that reflects the overall quality
+
+## Grading Scale
+
+| Grade | Meaning |
+|-------|---------|
+| A | World-class. Ship it. Minor polish only. |
+| B | Good. One or two fixable issues. |
+| C | Functional but frustrating. Multiple P1s. |
+| D | Users will struggle. Core experience broken. |
+| F | Blocks users entirely. Don't ship. |
+
+## CRISP Quick-Check
+
+Use these as your diagnostic lens during the scan:
+
+- **C** — Does the user know where they are within 5 seconds?
+- **R** — Does every interaction feel instant?
+- **I** — Is data presented as insight, not just numbers?
+- **S** — Does the user stay in their flow, or get pushed out of it?
+- **P** — Is complexity hidden from those who don't need it?
+
+## Output Format
+
+Keep it tight. No lengthy explanations.
+
+```
+## CRISP Review: [Screen/Feature Name]
+
+**Grade: [A–F]** — [One punchy verdict sentence]
+
+**Strengths**
+- [What's working — 1–2 points max]
+
+**Top 3 Issues**
+
+1. [C/R/I/S/P] **[Issue title]**
+   What's wrong: [One sentence, specific]
+   Fix: [One sentence, specific — not a direction, an action]
+
+2. [C/R/I/S/P] **[Issue title]**
+   What's wrong: [One sentence]
+   Fix: [One sentence]
+
+3. [C/R/I/S/P] **[Issue title]**
+   What's wrong: [One sentence]
+   Fix: [One sentence]
+
+**Quick Wins**
+- [High-impact, low-effort items that didn't make the top 3]
+```
+
+## Examples of Good vs. Weak Feedback
+
+**Weak:** "The empty state could be improved."
+**Good:** "[C] Empty state says 'No data' with no CTA. Replace with: 'You haven't added any suppliers yet. [Add your first supplier]'"
+
+**Weak:** "Loading feels slow."
+**Good:** "[R] Filter results wait for API response before updating. Switch to optimistic filtering — show results immediately, reconcile in background."
+
+**Weak:** "The dashboard shows too much."
+**Good:** "[P] 11 metrics visible at once, all with equal visual weight. Promote 3 most-used to hero cards. Collapse the rest into a secondary grid."
+
+## Tone
+
+Direct. Specific. Actionable. No softening. If the design fails, say it fails and say exactly why. The goal is to make the next iteration better, not to protect feelings.

package/.claude/skills/crisp-teach.md

@@ -0,0 +1,90 @@
+---
+name: crisp-teach
+description: CRISP onboarding command. Run once per project to teach the AI your product context — users, jobs-to-be-done, design system, benchmark references, and anti-references. Writes .crisp.md which all subsequent CRISP commands read automatically.
+user-invocable: true
+---
+
+# /crisp-teach — Project Onboarding
+
+Run this command once per project. It learns your design context through a structured interview, then writes `.crisp.md` to your project root. All other CRISP commands (`/crisp-audit`, `/crisp-review`, `/feature-design`, `/handoff`) inherit this context automatically.
+
+## Interview Protocol
+
+Work through the following questions with the user. Ask them one section at a time. Don't rush — good context makes every subsequent command significantly more accurate.
+
+---
+
+### Section 1: Product Overview
+Ask:
+- "What is this product? Describe it in one sentence as if explaining to a potential customer."
+- "What stage is it at? (Pre-launch / early customers / growth / mature)"
+- "What's the primary action a user takes in this product?"
+
+---
+
+### Section 2: Users
+Ask:
+- "Who is your primary user? Describe them — their role, their day, their level of technical sophistication."
+- "What is the job they're hiring your product to do? What were they doing before?"
+- "What does failure look like for them? What happens if the product lets them down?"
+
+---
+
+### Section 3: Design System
+Ask:
+- "Do you have a design system or component library? If so, name it or describe it briefly."
+- "What design tokens or visual constraints should I know about? (colours, type scale, spacing)"
+- "Are there any components that are off-limits to change?"
+
+---
+
+### Section 4: Benchmarks
+Ask:
+- "Which products do you most admire from a design perspective? These become your positive references."
+- "Which products do you NOT want to look or feel like? These become your anti-references."
+- "Of the CRISP dimensions — Contextual, Responsive, Intelligent, Seamless, Powerful — which matters most for your users right now?"
+
+---
+
+### Section 5: Known Weaknesses
+Ask:
+- "What's the biggest UX problem you already know exists?"
+- "Which user flows feel most broken or incomplete?"
+- "Is there anything that's off-limits for this audit? (legacy constraints, upcoming changes)"
+
+---
+
+## Output Format
+
+Once the interview is complete, write a `.crisp.md` file to the project root with this structure:
+
+```markdown
+# .crisp.md — CRISP Design Context
+*Generated by /crisp-teach. Update by running /crisp-teach again.*
+
+## Product
+[One-sentence product description]
+Stage: [Pre-launch / Early / Growth / Mature]
+Primary action: [What users mainly do]
+
+## Users
+Primary user: [Role + sophistication level]
+Job-to-be-done: [What they're hiring the product for]
+Failure mode: [What happens if the product lets them down]
+
+## Design System
+[System name or description]
+Key tokens: [Colours, type, spacing constraints]
+Constraints: [What can't be changed]
+
+## Benchmarks
+Positive references: [Products to aspire to]
+Anti-references: [Products to avoid resembling]
+Priority CRISP dimension: [C / R / I / S / P]
+
+## Known Issues
+[List of acknowledged UX problems]
+[Off-limits areas]
+```
+
+Confirm to the user that `.crisp.md` has been written and that all CRISP commands will now use this context automatically.

package/.claude/skills/feature-design.md

@@ -0,0 +1,131 @@
+---
+name: feature-design
+description: Design a new product feature using CRISP principles. Takes a problem statement and produces user flows, component decisions, CRISP compliance checks, and decision rationale benchmarked against world-class products. If .crisp.md exists, load it first.
+user-invocable: true
+---
+
+# /feature-design — CRISP Feature Design
+
+Design a new feature from scratch, grounded in CRISP principles. This is not wireframe generation — it's structured design thinking that produces flows, decisions, rationale, and open questions.
+
+If `.crisp.md` exists, load it before beginning. The design should be grounded in the specific users, design system, and benchmarks documented there.
+
+## Step 1: Problem Framing
+
+Before designing anything, clarify the problem. If the user hasn't provided these, ask:
+
+1. **Who is experiencing this problem?** (Role, sophistication level, context)
+2. **What are they trying to do?** (The job, not the feature)
+3. **What do they do today?** (Workaround, existing tool, manual process)
+4. **What does success look like?** (Observable outcome, not feature completion)
+5. **What constraints exist?** (Technical, timeline, design system)
+
+If `.crisp.md` exists, cross-reference with the documented user persona and known issues before proceeding.
+
+## Step 2: CRISP Design Principles to Apply
+
+Design the feature so that each dimension is explicitly addressed:
+
+**Contextual** — The user should always know:
+- Where they are in the flow
+- What they've just done
+- What happens next
+
+**Responsive** — Every action should feel immediate:
+- Optimistic UI for predictable state changes
+- Skeleton loading, not blank spaces
+- No spinners for actions the user initiated
+
+**Intelligent** — The feature should leverage what we know:
+- Pre-populate from history or context
+- Surface the next-best-action at every step
+- Show data as insight, not raw numbers
+
+**Seamless** — The feature should fit into their existing workflow:
+- Don't redirect users out of their context unnecessarily
+- Use familiar patterns before inventing new ones
+- Keep the feature's footprint as small as possible
+
+**Powerful** — Complexity should be progressive:
+- Surface the most-used 20% by default
+- Hide the other 80% behind deliberate disclosure
+- Add keyboard shortcuts for power users
+
+## Step 3: Flow Design
+
+Map the user flow as a numbered sequence of steps. For each step, document:
+
+```
+Step [N]: [What the user does / sees]
+- State: [What the UI shows]
+- CRISP check: [Which dimension(s) this step addresses or risks]
+- Decision: [Why this approach over alternatives]
+- Edge cases: [Empty state / error state / loading state]
+```
+
+## Step 4: Component Decisions
+
+For each key UI element in the flow, document:
+- **What it is** (component name/type)
+- **Why this pattern** (over alternatives)
+- **Benchmark reference** (where this pattern works well — Stripe, Linear, etc.)
+- **CRISP alignment** (which dimension it serves)
+
+## Step 5: Open Questions
+
+List the research questions this design surfaces — things that should be validated before building or in a usability test:
+
+- User behaviour questions (do users actually do X?)
+- Technical feasibility questions
+- Edge cases that need product decisions
+
+## Output Format
+
+```
+## Feature Design: [Feature Name]
+
+### Problem
+Who: [User]
+Job: [What they're trying to do]
+Today: [Current workaround]
+Success: [Observable outcome]
+
+### User Flow
+
+**Step 1: [Name]**
+State: [UI description]
+CRISP: [Dimension + how it's addressed]
+Decision: [Why this approach]
+Edge cases: [Empty / error / loading]
+
+[Repeat for each step]
+
+### Key Component Decisions
+
+| Component | Pattern | Benchmark | CRISP Dimension |
+|-----------|---------|-----------|-----------------|
+| [Name]    | [Type]  | [Reference] | [C/R/I/S/P]   |
+
+### CRISP Compliance Summary
+
+| Dimension   | How addressed | Risk |
+|-------------|--------------|------|
+| Contextual  | [How]        | [Any gaps] |
+| Responsive  | [How]        | [Any gaps] |
+| Intelligent | [How]        | [Any gaps] |
+| Seamless    | [How]        | [Any gaps] |
+| Powerful    | [How]        | [Any gaps] |
+
+### Open Questions
+- [Research / product / technical questions to resolve]
+
+### Next Steps
+- [Recommended actions before building]
+```
+
+## Design Style
+
+- Design for the primary user first. Edge cases come second.
+- Favour familiar patterns over novel ones unless novelty is the point.
+- Every design decision should be justifiable against CRISP.
+- If a step in the flow fails a CRISP dimension, flag it and propose a fix before moving on.

package/.claude/skills/handoff.md

@@ -0,0 +1,219 @@
+---
+name: handoff
+description: Convert a CRISP-reviewed design into a developer-ready specification. Produces component states, implementation notes, token references, edge cases, and an accessibility checklist. Use after a design has passed /crisp-audit or /crisp-review. If .crisp.md exists, load it first.
+user-invocable: true
+---
+
+# /handoff — Developer Handoff Spec
+
+Convert a design into a complete, implementation-ready specification. The goal is to eliminate ambiguity before a single line of code is written.
+
+If `.crisp.md` exists, load it. Your spec should reference the documented design system tokens and constraints.
+
+## What to Produce
+
+A handoff spec that covers everything a developer needs to build the design correctly, without having to interpret, invent, or ask follow-up questions.
+
+---
+
+## Section 1: Overview
+
+```
+## [Component / Screen Name] — Handoff Spec
+Date: [Today]
+Status: Ready for development
+
+### Summary
+[One paragraph: what this is, what it does, who uses it]
+
+### Scope
+[What's included in this spec]
+[What's explicitly out of scope]
+```
+
+---
+
+## Section 2: Component Inventory
+
+List every distinct component in the design:
+
+```
+### Components
+
+| Component | Type | Existing / New | Notes |
+|-----------|------|---------------|-------|
+| [Name]    | [Button / Card / Modal / etc.] | [Existing — link to design system] / [New] | [Any notes] |
+```
+
+For new components only, add:
+- **Props**: What data does it accept?
+- **Variants**: What visual/functional variants exist?
+- **Behaviour**: How does it respond to interactions?
+
+---
+
+## Section 3: States
+
+For every interactive element and every screen, document all states:
+
+```
+### States: [Component/Screen Name]
+
+**Default**
+[Description of the resting state]
+
+**Hover / Focus**
+[Description — include cursor, outline, colour change]
+
+**Active / Pressed**
+[Description]
+
+**Loading**
+[Description — skeleton, spinner, optimistic UI? Which and why]
+
+**Empty**
+[What the user sees when there's no data — never "No data available"]
+
+**Error**
+[What the user sees when something goes wrong — specific error message, recovery action]
+
+**Disabled**
+[When is it disabled? What does it look like? Can the user tell why?]
+
+**Success**
+[What confirms the action completed — and what did it do specifically?]
+```
+
+---
+
+## Section 4: Tokens & Spacing
+
+Reference the design system from `.crisp.md` or document the values directly:
+
+```
+### Design Tokens
+
+**Colours**
+| Token | Value | Usage |
+|-------|-------|-------|
+| [name] | [value] | [where used in this component] |
+
+**Typography**
+| Token | Size | Weight | Line-height | Usage |
+|-------|------|--------|-------------|-------|
+
+**Spacing**
+| Context | Value | Token |
+|---------|-------|-------|
+| Internal padding | [value] | [token name] |
+| Gap between elements | [value] | [token name] |
+
+**Border / Radius**
+[Document radius values and border styles used]
+```
+
+---
+
+## Section 5: Interactions & Animation
+
+```
+### Interactions
+
+| Trigger | Action | Duration | Easing | Notes |
+|---------|--------|----------|--------|-------|
+| Button click | Optimistic state update | immediate | — | Don't wait for API |
+| Hover on card | Background colour shift | 150ms | ease-out | |
+| Modal open | Fade + scale from 95% | 200ms | ease-out | |
+```
+
+---
+
+## Section 6: Edge Cases
+
+Document the cases that aren't shown in the main design but must be handled:
+
+```
+### Edge Cases
+
+| Scenario | Expected behaviour |
+|----------|-------------------|
+| User has no data yet | [Empty state with CTA — exact copy] |
+| API returns error | [Error message — exact copy + recovery action] |
+| User has 1 item | [Singular vs. plural label handling] |
+| User has 1,000+ items | [Truncation / pagination behaviour] |
+| Long text / content | [How labels, headings, descriptions handle overflow] |
+| Slow connection | [Loading state — duration before skeleton appears] |
+| User lacks permission | [What they see — not a blank page] |
+```
+
+---
+
+## Section 7: Accessibility
+
+```
+### Accessibility Checklist
+
+**Keyboard**
+- [ ] All interactive elements reachable via Tab
+- [ ] Focus order matches visual order
+- [ ] Custom components have keyboard equivalents (Escape to close, Enter to confirm)
+- [ ] Focus is managed correctly after modal open/close
+
+**Screen reader**
+- [ ] All interactive elements have accessible labels (aria-label or visible text)
+- [ ] Icons without text have aria-hidden="true" or aria-label
+- [ ] Dynamic content updates announced via aria-live
+- [ ] Error messages associated with form fields via aria-describedby
+
+**Visual**
+- [ ] Text contrast meets WCAG AA (4.5:1 for body, 3:1 for large text)
+- [ ] UI doesn't rely on colour alone to convey meaning
+- [ ] Touch targets are minimum 44×44px
+- [ ] Focus indicator is visible and has 3:1 contrast against background
+
+**Specific to this component**
+[Any component-specific accessibility considerations]
+```
+
+---
+
+## Section 8: Copy
+
+Document every string that appears in this design:
+
+```
+### Copy
+
+| Location | String | Notes |
+|----------|--------|-------|
+| Page heading | "[exact copy]" | [Tone note if relevant] |
+| CTA button | "[exact copy]" | |
+| Empty state heading | "[exact copy]" | |
+| Empty state body | "[exact copy]" | |
+| Success message | "[exact copy]" | |
+| Error message | "[exact copy]" | [What error condition triggers this] |
+```
+
+---
+
+## Section 9: Open Questions
+
+```
+### Open Questions for Engineering
+- [Technical questions the developer needs answered before building]
+
+### Open Questions for Product
+- [Product decisions still outstanding]
+
+### Decisions Made
+- [Key decisions already resolved — document so there's no revisiting]
+```
+
+---
+
+## Handoff Style
+
+- Be precise. "Fade in" is not enough. "Opacity 0→1, 200ms, ease-out" is.
+- Every string should be exact. No "TBD" in copy.
+- Every error state needs a recovery action, not just an error message.
+- If a state isn't documented, a developer will invent it. That's a design decision you've abdicated.