NodeJSmith/i-teach-impeccable

Gather design context for this project — both prose context (audience, brand, principles) and concrete design tokens (colors, fonts, spacing, motion). Persist everything to design/context.md for all future sessions.

Step 1: Explore the Codebase

Before asking questions, scan the project to discover what you can:

• README and docs: Project purpose, target audience, any stated goals
• Package.json / config files: Tech stack, dependencies, existing design libraries
• Existing components: Current design patterns, spacing, typography in use
• Brand assets: Logos, favicons, color values already defined
• Design tokens / CSS variables: Existing color palettes, font stacks, spacing scales
• Mockup files: If HTML mockups exist (from /mine.mockup), read them for aesthetic direction to reference when gathering tokens
• Any style guides or brand documentation

Also check for a design doc: look for design/specs/*/design.md. If found, read the User Scenarios section — it contains structured actor/goal/context data that pre-answers Step 2 questions.

Note what you've learned and what remains unclear.

Check for existing context

Look for design/context.md, .impeccable.md, or design/direction.md.

If found, read and ask:

AskUserQuestion:
  question: "Existing design context found. What would you like to do?"
  header: "Context"
  options:
    - label: "Update it"
      description: "Revise the existing context with new decisions"
    - label: "Start fresh"
      description: "Replace it entirely"

If updating, carry forward decisions not being changed.

Step 2: Gather Intent

Ask focused questions, one at a time. Skip any already answered by the spec or codebase exploration.

Question 1 (skip if spec has User Scenarios):

AskUserQuestion:
  question: "Who is this person? Not 'users' — the actual person. A teacher at 7am with coffee, a developer debugging at midnight, a manager scanning reports between meetings."
  header: "Audience"

If the answer is vague ("users", "people"), push back: "Can you be more specific? What's their context when they use this?"

Question 2 (skip if spec has User Scenarios):

AskUserQuestion:
  question: "What must they accomplish? The verb — not 'use the dashboard.' Grade submissions, find the broken deployment, approve the payment."
  header: "Task"

Question 3:

AskUserQuestion:
  question: "What should this feel like? Specific language: 'warm like a notebook', 'cold like a terminal', 'dense like a trading floor.' Not 'clean and modern.'"
  header: "Feel"

If any answer is vague ("clean and modern", "simple"), push back with a concrete alternative and ask to confirm or revise.

Step 3: Collect References

Ask for visual references:

AskUserQuestion:
  question: "Name 2-3 apps or sites whose *feel* (not features) matches what you described. Not to copy — to articulate direction."
  header: "References"

If the user cannot name any, suggest 3 options based on the domain and intent. For each reference, identify:

• What to take from it (e.g., "the density and monospace feel")
• What to leave (e.g., "the cold corporate blue — wrong for our brand")
• The specific visual movement it represents (e.g., "editorial minimalism", "data-dense utility", "organic warmth")

Naming the visual movement constrains downstream decisions more precisely than vague feel descriptors.

Step 4: Domain Exploration

Run the four-part exploration. Present all four before proposing any direction.

1. Domain concepts — Concepts, metaphors, vocabulary from this product's world. Not features — territory. Minimum 5.
2. Color world — What colors exist naturally in this domain? If this product were a physical space, what would you see? List 5+.
3. Signature element — One element — visual, structural, or interaction — that could only exist for THIS product. Be specific: "a timeline scrubber that mimics a vinyl record arm" not "a unique navigation pattern."
4. Defaults to reject — 3 obvious choices for this interface type. Name them so you can reject them consciously. For each: the default, why it's wrong for this product, and a better alternative.
5. Concrete constraints — Specific aesthetic rules derived from the exploration above. These are hard constraints, not suggestions. Examples:
   • "No rounded corners above 4px — the product is technical, not friendly"
   • "Body text must be a serif — the editorial feel requires it"
   • "Maximum 2 colors beyond neutrals — density demands restraint"
   • "No drop shadows — use border-only depth strategy"

Present exploration results to the user. Remove the product name — could someone still identify what it's for? If not, explore deeper.

Step 5: Self-Review

Draft your token decisions internally. Before presenting them, run these checks:

• Swap test: Replace your typeface, layout choices, and colors with the most common alternatives. Would anyone notice? Where they wouldn't — you defaulted.
• Squint test: Blur your eyes at the token set. Can you perceive hierarchy? Is anything jarring?
• Signature test: Point to five specific places where the signature element appears in your token decisions. "The overall feel" doesn't count.
• Token test: Read your CSS variable names aloud. Do they sound like they belong to this product, or any project?

If any check fails, iterate before presenting. Ask yourself: "If they said this lacks craft, what would they point to?" Fix that first.

Step 6: Propose Direction

Present concrete token decisions. Every value must be justified against intent and domain — not "it's common" or "it works."

Present a summary covering:

• Color palette — OKLCH values with semantic names. Light and dark mode. How colors connect to the domain's color world.
• Typography — Specific fonts and why they fit this product. Scale (xs through 3xl). Weights and their purposes. Avoid generic defaults (Inter, Roboto, Arial, Open Sans, system fonts).
• Spacing — Base unit and scale. How density connects to intent.
• Depth strategy — One of: borders-only, subtle shadows, layered shadows, surface tints. Why this choice fits the feel.
• Border radius — Scale (sm, md, lg). Where on the sharp-to-round spectrum and why.
• Motion — Micro-interaction timing, transition timing, easing functions.

Ask the user to confirm or revise before saving.

Step 7: Save Context

After user confirmation, write design/context.md. Create the design/ directory if it does not exist.

File format

---
schema_version: 1
updated_at: YYYY-MM-DD
---

## Users & Purpose
[From Step 2, Questions 1-2 — who the person is, their context, the task]

## Brand Personality
[From Step 2, Question 3 — emotional feel, aesthetic tone]

## Aesthetic Direction
[From Step 3 — visual references, what to take/leave, visual movement name]
[From Step 4 — domain concepts, signature element, defaults rejected]

## Concrete Constraints
[From Step 4 — hard aesthetic rules, e.g., "no rounded corners above 4px", "body text must be serif"]

## Design Principles
[3-5 principles derived from the conversation]

## Design Tokens

### Color
| Token | Light | Dark | Role |
|-------|-------|------|------|
| `--bg` | oklch(...) | oklch(...) | Page background |
| `--surface` | oklch(...) | oklch(...) | Card/panel background |
| ... | ... | ... | ... |

**Rationale**: [how colors connect to domain and intent]

### Typography
- **Primary**: [font name] — [why]
- **Mono**: [font name] — [for code/data]
- **Scale**: [specific sizes: xs, sm, base, lg, xl, 2xl, 3xl]
- **Weights**: [which weights, for what purpose]

### Spacing
- **Base**: [value]
- **Scale**: micro (1×), sm (2×), md (4×), lg (8×), xl (12×), 2xl (16×)

### Depth
- **Strategy**: [borders-only | subtle shadows | layered | surface tints]
- **Why**: [connection to intent]
- **Levels**: [specific values]

### Border Radius
- **Scale**: sm, md, lg
- **Character**: [sharp=technical, round=friendly]

### Motion
- **Micro**: [~150ms, easing]
- **Transition**: [200-250ms, easing]
- **Entrance**: [if applicable]

### Anti-patterns
[Specific things to avoid for THIS product — not generic advice]

If design/context.md already exists and the user chose "Update it" in Step 1, update changed sections in place rather than overwriting.

Step 8: Offer Next Steps

AskUserQuestion:
  question: "Design context saved. What's next?"
  header: "Next step"
  options:
    - label: "Generate a mockup"
      description: "Run /mine.mockup to produce an HTML preview using these tokens"
    - label: "Also add to CLAUDE.md"
      description: "Append a Design Context summary to CLAUDE.md so it loads automatically in all sessions (takes effect in new sessions, not the current one)"
    - label: "Done for now"
      description: "Context is saved — it will be used by all i-* design skills automatically"

If mockup → invoke /mine.mockup. If CLAUDE.md → append or update a ## Design Context section in CLAUDE.md with a summary of the prose sections (not the full token tables — those live in design/context.md).

Communication Style

Be invisible. Don't announce modes or narrate process.

Never say: "I'm now entering the exploration phase", "Let me check for existing files..." Instead: Jump into work. Present exploration, then direction, then confirm.