whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-14-agentic-development/lesson-02-documenting-decisions.md

@@ -0,0 +1,188 @@
+# Module 14: Agentic Development
+
+## Lesson 2: Evaluation and Feedback
+
+**Staying in control as the agent builds**
+
+---
+
+## The Step Is Done. Now What?
+
+The agent completed a step. You have output — code, a component, a visual.
+
+Now is the most important moment: **evaluation**.
+
+This is where you, the designer, earn your keep. The AI builds fast. You decide if what it built is right.
+
+---
+
+## The Evaluation Cycle
+
+After every step:
+
+### 1. Compare to Intent
+
+Does the output match what you asked for?
+
+- Check against the specification
+- Check against the test protocol
+- Look at it with fresh eyes — not just technically correct, but does it *feel* right?
+
+### 2. Give Feedback
+
+Tell the agent specifically what's wrong or right. The more precise your feedback, the better the next iteration.
+
+### 3. Update the Plan
+
+Based on what you learned, adjust:
+
+- **Reprioritize** — this task turned out to be more important
+- **Add tasks** — something new emerged
+- **Remove tasks** — this is no longer needed
+- **Split tasks** — this was too big, break it down
+- **Shuffle order** — the sequence should change
+
+---
+
+## Giving Effective Feedback
+
+### Bad Feedback
+
+> "This doesn't look right."
+
+The agent doesn't know what "right" means. It will guess, probably wrong.
+
+### Good Feedback
+
+> "The spacing between the form fields is too tight. The spec says 16px between fields, this looks like 8px. Also, the submit button should be full-width, not centered at 200px."
+
+Specific. Referenced to spec. Actionable.
+
+### Better Feedback
+
+> "Two issues:
+> 1. Field spacing: spec says 16px gap, implementation has 8px. Fix to 16px.
+> 2. Submit button: spec says full-width (100%), implementation is 200px centered. Fix to 100%.
+>
+> Everything else looks correct. Proceed to next step after fixing."
+
+Numbered. Clear priority. Confirms what's correct too.
+
+---
+
+## What to Evaluate
+
+### Against Specification
+
+| Check | Question |
+|-------|----------|
+| Content | Does text match spec exactly? |
+| Layout | Are elements positioned correctly? |
+| States | Are all states present and correct? |
+| Behavior | Do interactions work as specified? |
+| Styling | Do colors, fonts, spacing match tokens? |
+
+### Against Intent
+
+Not everything is in the spec. Use your design judgment:
+
+- Does the visual hierarchy feel right?
+- Is the flow natural?
+- Would a user understand this immediately?
+- Does it match the persona's needs?
+
+### Against Quality
+
+- Accessibility: contrast, focus states, touch targets
+- Responsiveness: does it work on all sizes?
+- Performance: is it smooth?
+
+---
+
+## Re-evaluating the Plan
+
+After evaluation, open the Design Log and update the task list.
+
+**Before step 3:**
+```markdown
+## Tasks
+1. [x] Create form layout
+2. [x] Add validation
+3. [ ] Implement error states
+4. [ ] Loading and success states
+5. [ ] Responsive adjustments
+6. [ ] Accessibility pass
+```
+
+**After step 3 revealed mobile layout issues:**
+```markdown
+## Tasks
+1. [x] Create form layout
+2. [x] Add validation
+3. [x] Implement error states
+4. [ ] Fix mobile layout for error messages    ← NEW
+5. [ ] Loading and success states
+6. [ ] Responsive adjustments
+7. [ ] Accessibility pass
+8. [ ] Revisit password strength on mobile     ← NEW (from step 2 learning)
+```
+
+The plan grows and shrinks. That's normal.
+
+---
+
+## When Output Is Wrong
+
+Three common situations:
+
+### 1. Spec Divergence
+
+The output doesn't match the spec.
+
+**Action:** Point to the specific spec section. Ask the agent to fix it.
+
+> "The spec says the error message appears below the field, but it's rendering as a toast notification. Fix to inline below-field as per spec section 4.2."
+
+### 2. Spec Was Wrong
+
+Building revealed the spec needs updating.
+
+**Action:** Update the spec first, then continue building.
+
+> "The spec says inline validation on keypress, but that's too aggressive. Updating spec to blur-based validation. Continue with updated approach."
+
+### 3. Better Idea
+
+The agent or you discovered a better approach during building.
+
+**Action:** Document the improvement, update spec, continue.
+
+> "The agent suggested a shake animation on error instead of just red text. That's better UX. Updating spec to include shake. Document as intentional improvement."
+
+---
+
+## The Evaluation Mindset
+
+Think of yourself as a creative director reviewing work:
+
+- **Be specific** — point to exact elements
+- **Be decisive** — approve or reject, don't waffle
+- **Be efficient** — one round of feedback per step, not five
+- **Confirm what's right** — not just what's wrong
+- **Think strategically** — does this serve the user, the persona, the business goal?
+
+---
+
+## What's Next
+
+In the next lesson, you'll learn what to do when things go wrong — when the agent can't solve the problem and you need to troubleshoot or escalate.
+
+---
+
+**[Continue to Lesson 3: When You Get Stuck →](lesson-03-when-you-get-stuck.md)**
+
+---
+
+[← Back to Lesson 1](lesson-01-iterative-building.md) | [Back to Module Overview](module-14-agentic-development-overview.md)
+
+*Part of Module 14: Agentic Development*

package/docs/learn/module-14-agentic-development/lesson-03-when-you-get-stuck.md

@@ -0,0 +1,213 @@
+# Module 14: Agentic Development
+
+## Lesson 3: When You Get Stuck
+
+**Because AI doesn't always get it right**
+
+---
+
+## It Will Happen
+
+You give clear feedback. The agent makes a change. It's still wrong. You clarify. Another change. Still wrong. Or worse — it fixes one thing and breaks another.
+
+This is normal. It happens to everyone. The question is: what do you do?
+
+---
+
+## Recognize the Loop
+
+The most common trap:
+
+```
+You: "Fix the spacing"
+Agent: Changes spacing, breaks alignment
+You: "Now fix the alignment"
+Agent: Fixes alignment, reverts spacing
+You: "The spacing is wrong again"
+Agent: ...
+```
+
+If you've gone back and forth more than **3 times** on the same issue, you're in a loop. Stop.
+
+---
+
+## Troubleshooting Strategies
+
+### 1. Start Fresh on the Step
+
+Sometimes the agent has accumulated too many conflicting changes. The context is muddled.
+
+**Action:** Roll back to the last working state. Ask the agent to redo the step from scratch with clear, complete instructions.
+
+> "Let's start this step over. Here's the last working version: [paste code]. Now implement the error states with these exact requirements: [list all requirements in one message]."
+
+One comprehensive prompt beats five incremental fixes.
+
+### 2. Break the Problem Down
+
+The step might be too big. The agent is trying to do too much at once.
+
+**Action:** Split the step into smaller pieces.
+
+Instead of:
+> "Add all error states"
+
+Try:
+> "Add just the email validation error. Red border, error message below the field, text: 'Please enter a valid email'."
+
+One thing. Verify. Next thing.
+
+### 3. Show, Don't Tell
+
+Sometimes words aren't enough. Show the agent what you mean.
+
+**Action:** Provide visual reference, code snippets, or examples.
+
+> "The error message should look like this:
+> ```html
+> <span class="error" style="color: #DC2626; font-size: 14px; margin-top: 4px;">
+>   Please enter a valid email
+> </span>
+> ```
+> Apply this pattern to all validation errors."
+
+Concrete examples eliminate ambiguity.
+
+### 4. Check Your Own Spec
+
+Sometimes the problem is the spec, not the agent.
+
+**Action:** Re-read your specification with fresh eyes. Is it actually clear? Could it be interpreted differently?
+
+Common spec issues that confuse agents:
+- Contradictory requirements
+- Vague descriptions ("appropriate size", "good spacing")
+- Missing state definitions
+- Unclear interaction triggers
+
+Fix the spec, then resume.
+
+---
+
+## When to Change Approach
+
+Some problems resist iteration. Signs you need a different approach:
+
+| Signal | What it means |
+|--------|---------------|
+| Same error 3+ times | The agent doesn't understand the problem |
+| Fixes create new bugs | The approach is structurally wrong |
+| The output keeps getting worse | Too many patches on a bad foundation |
+| You can't explain what's wrong | You might need to rethink the design |
+
+**Action:** Step back. Look at the bigger picture. Maybe the component needs a different structure. Maybe the layout approach is wrong. Sometimes the answer is to redesign the step, not debug it.
+
+---
+
+## When to Ask a Developer
+
+This is the hardest moment for a designer working with AI: admitting the agent can't solve it.
+
+### Signs You Need Human Help
+
+- **Technical limitation** — the agent hits a framework or API issue it can't resolve
+- **Performance problem** — it works but it's too slow, and optimizing is beyond the spec
+- **Integration issue** — the component works in isolation but breaks in the real app
+- **Build/deploy error** — something in the toolchain, not the design
+- **State management** — complex data flow that needs architectural thinking
+
+### How to Ask
+
+Don't come empty-handed. Bring your Design Log:
+
+> "I've been building the signup form. Here's my Design Log with everything we tried.
+>
+> The issue: error messages work on desktop but disappear on mobile. The agent tried 4 different approaches (logged in the dialog). None worked.
+>
+> I think it's a CSS overflow issue but I'm not sure. Can you take a look?"
+
+The dialog shows what you've tried. The developer doesn't start from zero.
+
+### What to Document
+
+When a developer fixes the issue, add it to your Design Log:
+
+```markdown
+### Step 4: Error states on mobile (resolved with developer help)
+- Issue: Error messages clipped by overflow:hidden on parent container
+- Root cause: Parent component sets overflow:hidden for scroll behavior
+- Fix: Moved error messages outside the scrollable container
+- Developer: Marcus helped identify the CSS issue
+- Learning: Check parent overflow properties when elements disappear
+```
+
+This learning carries forward. Next time the agent (or you) will know.
+
+---
+
+## Common Stuck Points for Designers
+
+Issues that frequently trip up designers working with AI:
+
+### CSS That Won't Behave
+
+The layout looks right in one viewport, breaks in another. AI agents are surprisingly bad at responsive edge cases.
+
+**Tips:**
+- Give explicit breakpoints, not vague "make it responsive"
+- Test each breakpoint separately
+- Use browser dev tools to inspect
+
+### State Management
+
+The button should be disabled when the form is invalid. But it's always enabled. Or always disabled.
+
+**Tips:**
+- Describe state transitions explicitly: "Button starts disabled. Becomes enabled when email is valid AND password is 8+ characters."
+- Test each transition individually
+
+### Animations and Transitions
+
+The agent adds an animation. It's janky. You ask for smooth. Still janky.
+
+**Tips:**
+- Provide exact CSS transition values: "transition: opacity 200ms ease-in-out"
+- Some animations need requestAnimationFrame — this is where a developer helps
+
+### Accessibility
+
+The contrast passes but the focus ring is invisible. Or screen readers announce things in the wrong order.
+
+**Tips:**
+- Use browser accessibility tools (DevTools → Accessibility panel)
+- Tab through everything manually
+- Test with actual screen reader if possible
+
+---
+
+## The Right Mindset
+
+Getting stuck doesn't mean failure. It means you're pushing into real product development.
+
+The value of a designer in agentic development isn't that you can build everything yourself. It's that you:
+
+1. **Know what right looks like** — your eye catches what the agent misses
+2. **Can articulate the problem** — your feedback makes the agent better
+3. **Know when to escalate** — you don't waste time on what needs human expertise
+4. **Document everything** — the next person (or the next session) benefits from your experience
+
+---
+
+## What's Next
+
+Before the tutorial, two more practical lessons: choosing your code format and keeping it safe with Git.
+
+---
+
+**[Continue to Lesson 4: Working with Code →](lesson-04-working-with-code.md)**
+
+---
+
+[← Back to Lesson 2](lesson-02-documenting-decisions.md) | [Back to Module Overview](module-14-agentic-development-overview.md)
+
+*Part of Module 14: Agentic Development*

package/docs/learn/module-14-agentic-development/lesson-04-working-with-code.md

@@ -0,0 +1,304 @@
+# Module 14: Agentic Development
+
+## Lesson 4: Choosing Your Code Format
+
+**Understanding what the agent produces and which technology fits your needs**
+
+---
+
+## The Agent Writes Code. Which Kind?
+
+When you ask an agent to build something, one of the first decisions is: what technology should it use? This choice affects how fast you can iterate, how easy it is to share, and how close the output is to production.
+
+You don't need to become an expert. But you need to understand the options well enough to make good decisions — or at least ask the right questions.
+
+---
+
+## The Most Common Stack: React + Tailwind
+
+Most modern web projects use some version of this combination. If you're building production code, this is likely what you'll work with.
+
+**React** handles structure and behavior — you build reusable components that manage their own state.
+
+**Tailwind CSS** handles styling — instead of writing CSS in separate files, you apply utility classes directly to elements.
+
+**Next.js** ties it all together — routing between pages, server features, and deployment.
+
+```jsx
+function SignupForm() {
+  const [email, setEmail] = useState('')
+  const [error, setError] = useState('')
+
+  function handleSubmit() {
+    if (!email.includes('@')) {
+      setError('Please enter a valid email')
+    }
+  }
+
+  return (
+    <div className="max-w-md p-8">
+      <h1 className="text-2xl font-bold mb-4">Create Account</h1>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        className="w-full border rounded p-3 mb-4"
+        placeholder="Email"
+      />
+      {error && <span className="text-red-600 text-sm">{error}</span>}
+      <button
+        onClick={handleSubmit}
+        disabled={!email}
+        className="bg-blue-600 text-white px-6 py-3 rounded w-full disabled:opacity-50"
+      >
+        Sign Up
+      </button>
+    </div>
+  )
+}
+```
+
+Notice how everything — structure, styling, and behavior — lives in one component file. This is what modern web development looks like.
+
+| | |
+|---|---|
+| **Pros** | Industry standard. Components are reusable. Real interactivity. Deploys easily to Vercel. The agent is very good at generating this stack. |
+| **Cons** | Requires a development environment (Node.js, package manager). Can't just open a file in the browser. Errors can be cryptic. Steeper learning curve. |
+| **Best for** | Production projects. Interactive prototypes. Building within an existing codebase. |
+
+---
+
+## Component Libraries and Your Design System
+
+In Module 13, you built a design system — tokens for colors, typography, spacing, and component definitions. In code, these come to life through **component libraries**.
+
+A component library is a collection of pre-built, styled components (buttons, inputs, cards, modals) that you use as building blocks. Instead of writing a button from scratch every time, you import one:
+
+```jsx
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+
+function SignupForm() {
+  return (
+    <div className="max-w-md p-8">
+      <Input type="email" placeholder="Email" />
+      <Button variant="primary">Sign Up</Button>
+    </div>
+  )
+}
+```
+
+### Popular component libraries
+
+| Library | What it is |
+|---|---|
+| **shadcn/ui** | Copy-paste components built on Tailwind. You own the code. Highly customizable. Currently the most popular choice. |
+| **Radix UI** | Accessible, unstyled primitives. You add your own styling. The foundation under shadcn/ui. |
+| **Material UI (MUI)** | Google's design system as React components. Opinionated look and feel. |
+| **Chakra UI** | Utility-based components with built-in accessibility. |
+
+### How this connects to your design system
+
+Your design tokens (Module 13) define the rules. The component library implements them:
+
+| Design token | Code implementation |
+|---|---|
+| Primary color: `#0066FF` | `--primary: #0066FF` in your Tailwind config |
+| Font: Inter, 16px base | `fontFamily: { sans: ['Inter'] }` in config |
+| Spacing: 8px scale | `spacing: { 1: '8px', 2: '16px', ... }` |
+| Button: primary variant | `<Button variant="primary">` uses all the above |
+
+When the agent builds, it should use your component library and respect your design tokens. Include your design system in the Design Log requirements:
+
+> "Use our design system tokens. Primary #0066FF, Inter font, 8px spacing scale. Use shadcn/ui components where applicable."
+
+---
+
+## For Prototyping: HTML + Tailwind
+
+When you don't need a full framework — just a quick visual prototype — use static HTML with Tailwind via CDN.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://cdn.tailwindcss.com"></script>
+</head>
+<body>
+  <div class="max-w-md mx-auto p-8 mt-16">
+    <h1 class="text-2xl font-bold mb-4">Create Account</h1>
+    <input type="email" placeholder="Email"
+      class="w-full border rounded p-3 mb-4">
+    <button class="bg-blue-600 text-white px-6 py-3 rounded w-full">
+      Sign Up
+    </button>
+  </div>
+</body>
+</html>
+```
+
+One file. Double-click to open. Instant prototype.
+
+| | |
+|---|---|
+| **Pros** | Zero setup. One file. Consistent styling with utility classes. Easy to share. Fast iteration. |
+| **Cons** | No real interactivity without adding JavaScript. Not production code. Tailwind CDN is for prototyping only. |
+| **Best for** | Rapid exploration. Client reviews. Testing layouts and visual direction before committing to a framework. |
+
+---
+
+## The Simplest Option: HTML + CSS + JavaScript
+
+The foundation of the web. Every browser understands these three languages natively. No framework, no library, no build step.
+
+- **HTML** — the structure (what elements exist and how they're organized)
+- **CSS** — the visual styling (colors, fonts, spacing, layout)
+- **JavaScript** — the behavior (what happens when you click, type, or scroll)
+
+These can be combined in a single `.html` file for quick explorations, or split into separate files for organized work:
+
+```html
+<!-- structure -->
+<div class="signup-form">
+  <h1>Create Account</h1>
+  <input type="email" id="email" placeholder="Email">
+  <button id="submit-btn">Sign Up</button>
+  <span class="error" id="email-error"></span>
+</div>
+```
+
+```css
+/* appearance */
+.signup-form { max-width: 400px; padding: 32px; font-family: Inter, sans-serif; }
+.signup-form button { background: #0066FF; color: white; padding: 12px 24px; }
+.error { color: #DC2626; font-size: 14px; display: none; }
+```
+
+```javascript
+// behavior
+document.getElementById('submit-btn').addEventListener('click', function() {
+  const email = document.getElementById('email').value
+  const error = document.getElementById('email-error')
+  if (!email.includes('@')) {
+    error.textContent = 'Please enter a valid email'
+    error.style.display = 'block'
+  }
+})
+```
+
+| | |
+|---|---|
+| **Pros** | No setup. No dependencies. Universal. You can read the structure, styles, and behavior separately. Opens in any browser. |
+| **Cons** | Everything is manual. No components or reusability. Gets messy in larger projects. More code to wire things together. |
+| **Best for** | Learning the basics. Quick one-off prototypes. When you want full control with no abstractions. |
+
+---
+
+## Other Frameworks
+
+| Technology | When you'll see it |
+|---|---|
+| **Svelte / SvelteKit** | Simpler alternative to React. Less boilerplate. Growing in popularity. |
+| **Vue / Nuxt** | Another React alternative. Popular in some teams and regions. |
+| **TypeScript** | JavaScript with type safety. Production projects often require it. The agent handles it well. |
+
+You don't choose these — your project does. If you're joining an existing codebase, you use what's already there. If you're starting fresh, the agent can help you pick.
+
+---
+
+## Static vs. Executable: Where They Live
+
+### Static prototypes
+
+Placed in the scenario folder alongside their specifications. This keeps the visual output next to the spec it was built from:
+
+```
+docs/C-Scenarios/S01-User-Registration/
+├── scenario-overview.md
+├── P01-landing-page/
+│   ├── specification.md
+│   └── prototype.html          ← Static prototype
+├── P02-signup-form/
+│   ├── specification.md
+│   └── prototype.html          ← Static prototype
+└── shared/
+    ├── styles.css              ← Shared styles across pages
+    └── interactions.js         ← Shared behavior
+```
+
+### Executable code
+
+Organized in the root of the repository, following the project's framework structure:
+
+```
+my-project/
+├── src/
+│   ├── components/
+│   │   ├── SignupForm.tsx
+│   │   └── ui/                 ← Component library
+│   ├── pages/
+│   │   ├── index.tsx
+│   │   └── signup.tsx
+│   └── styles/
+│       └── globals.css
+├── docs/                       ← Specs still live here
+├── package.json
+└── ...
+```
+
+---
+
+## Choosing the Right Format
+
+| Situation | Format | Why |
+|-----------|--------|-----|
+| Exploring a layout idea | HTML + Tailwind | Fast, disposable, zero setup |
+| Reviewing with a client | Static HTML | Easy to share, no setup for viewer |
+| Rapid component iteration | HTML + Tailwind | Consistent styling, quick changes |
+| Building a production feature | React + Tailwind | Ships directly into the codebase |
+| Testing real form validation | React | Needs real state management |
+| Designing a new page | Static first | Iterate fast, then migrate |
+| Adding to an existing app | Match the existing stack | Must fit the codebase |
+
+Many projects use both categories: static HTML for exploration, framework code for implementation. Start light, go heavy when you need to.
+
+---
+
+## Practical Tips
+
+### For static prototypes
+
+- Ask the agent: "Build this as a single HTML file I can open in my browser"
+- Use Tailwind CDN for fast styling without setup
+- Share by sending the file — email, Slack, cloud drive
+- Place prototypes in the scenario folder next to the specification
+
+### For executable code
+
+- Ask the agent: "Build this as a component in our [framework] project using our design system"
+- Make sure your development environment is running before you start
+- Deploy to a preview URL (Vercel, Netlify) when you need to share
+- Keep the Design Log updated with the branch and commit information
+
+### When to ask a developer
+
+- You're not sure which technology the project uses
+- The development server won't start
+- You get build errors you don't understand
+- You need to set up a new project from scratch
+
+---
+
+## What's Next
+
+Whether you're producing static HTML or executable code, you need a way to keep your work safe, organized, and shareable. That's where Git comes in.
+
+---
+
+**[Continue to Lesson 5: Git Discipline →](lesson-05-git-discipline.md)**
+
+---
+
+[← Back to Lesson 3](lesson-03-when-you-get-stuck.md) | [Back to Module Overview](module-14-agentic-development-overview.md)
+
+*Part of Module 14: Agentic Development*