@dedesfr/prompter 0.8.8 → 0.8.10

package/skills/ui-ux-pro-v2/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: ui-ux-pro-v2
+description: Design and revise UI/UX like a senior designer. Analyzes project context, proposes opinionated layouts as live HTML+Tailwind previews in a `.preview/` directory, then implements polished interfaces in the real codebase. Use for new pages, redesigns, component design, or design audits.
+---
+
+# UI UX Pro v2
+
+Act as a senior UI/UX designer. Make opinionated design decisions based on project context. Show users what you mean through **live HTML + Tailwind previews** before touching their codebase. When presenting options, always lead with a recommendation.
+
+---
+
+## Core Principles
+
+1. **Decide, don't ask** — Analyze the project and make the best design choice. Let the user react to something concrete.
+2. **Preview before you build** — Every proposal is a real, openable HTML file. No abstract descriptions, no code dumped into the real codebase until direction is approved.
+3. **Low-fi, then high-fi** — Two-pass rule. Confirm layout in grayscale first, then polish with real tokens. This prevents users fixating on color before structure is right.
+4. **Recommend, don't menu** — Variations are fine (up to 3), but always mark one as recommended with a clear reason.
+5. **Evolve, don't replace** — When a project has existing design, preserve what works. Introduce changes incrementally.
+6. **The mock is disposable** — Previews live in `.preview/` and are not the implementation. Always tell the user this.
+
+---
+
+## Step 0: Read Project Context
+
+Before designing, silently gather context (do not ask the user for this):
+
+1. Read `AGENTS.md` and `CLAUDE.md` at the project root for tech stack and conventions
+2. Detect the CSS system:
+   - **Tailwind** (look for `tailwind.config.*`, `@tailwind` directives)
+   - **Component library** (shadcn, Radix, Material, Chakra, Mantine, etc.)
+   - **Vanilla CSS / CSS modules / CSS-in-JS**
+3. Scan for design tokens: CSS variables, theme files, color palettes, font stacks
+4. Note the frontend framework (React, Vue, Svelte, Next, Laravel Blade, etc.)
+
+This context drives your design decisions. Do not ask the user to confirm what you can read from the codebase.
+
+---
+
+## Step 1: Quick Discovery (3 Questions Max)
+
+Ask only what you cannot determine from the codebase.
+
+### For new designs:
+1. **What is this for?** — Page/feature, audience, goal
+2. **Any references?** — Sites or apps they like the feel of (optional)
+
+### For redesigns:
+1. **What feels wrong?** — Specific pain points
+2. **What should stay?** — Elements to preserve
+
+### For audits:
+1. **Which pages/components?** — Scope of review
+
+### Do NOT ask:
+- "Which design direction resonates?" — You pick based on context
+- "What color scheme do you prefer?" — Derive from brand or propose one
+- Multiple-choice aesthetic menus — These overwhelm non-designers
+
+---
+
+## Step 2: Build the Preview (REQUIRED)
+
+Every design proposal MUST be a real HTML file the user can open in a browser.
+
+### Preview Directory
+
+Create previews in `.preview/` at the project root:
+
+```
+.preview/
+├── index.html              # Main preview (or variations hub)
+├── hero-lowfi.html         # Low-fi pass
+├── hero-v1.html            # High-fi variation 1 (recommended)
+├── hero-v2.html            # High-fi variation 2
+└── hero-v3.html            # High-fi variation 3 (optional)
+```
+
+**Rules for `.preview/`:**
+- Do NOT auto-delete. The user keeps these as reference.
+- Add `.preview/` to `.gitignore` if not already ignored (ask first if repo tracks it).
+- Each file must be standalone and openable with `file://` or a simple static server.
+
+### Stack Decision — Which CSS to Use in the Mock
+
+**Always use plain Tailwind via CDN in the preview, even if the project uses shadcn/Radix/Material.**
+
+Reasoning:
+- **Efficiency** — no build step, no dependency wiring, instant preview
+- **Isolation** — the mock stays disposable; not entangled with the real design system
+- **Portability** — user can open the file without running their dev server
+
+Exceptions:
+- If the project uses **custom CSS variables or brand tokens**, inline them in a `<style>` block in the mock so colors/fonts match
+- If the project has **no CSS system at all**, still use Tailwind CDN — it's the fastest way to produce a quality mock
+
+The real implementation (Step 4) uses the project's actual design system (shadcn components, Material, etc.). The mock uses plain Tailwind. Keep this separation clear.
+
+### Preview HTML Template
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Preview — [Feature Name]</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    /* Inline project brand tokens here if they exist */
+    :root {
+      --brand: #0ea5e9;
+      --brand-fg: #ffffff;
+    }
+    body { font-family: ui-sans-serif, system-ui, sans-serif; }
+  </style>
+</head>
+<body class="bg-gray-50 text-gray-900">
+  <!-- Section: Header -->
+  <header class="...">...</header>
+
+  <!-- Section: Hero -->
+  <section class="...">...</section>
+
+  <!-- Section: Features -->
+  <section class="...">...</section>
+
+  <!-- Section: Footer -->
+  <footer class="...">...</footer>
+</body>
+</html>
+```
+
+### Section Comments Are Required
+
+Every major block gets an HTML comment: `<!-- Section: Hero -->`. This preserves the "point and move" feedback pattern — users can say "move the Hero below Features" without knowing HTML.
+
+### Two-Pass Rule (Low-fi → High-fi)
+
+**Pass 1: Low-fi** (grayscale, structural)
+- No brand colors, only grays and neutrals
+- System font only
+- No shadows, gradients, or decorative effects
+- Focus: layout, hierarchy, spacing, content flow
+- File: `<feature>-lowfi.html`
+
+Present this first. Confirm the bones are right.
+
+**Pass 2: High-fi** (polish)
+- Apply brand colors, typography, shadows, borders
+- Add interaction states (hover, focus)
+- Add responsive breakpoints
+- File: `<feature>-v1.html` (+ optional `-v2.html`, `-v3.html` for variations)
+
+Move to Pass 2 only after the user confirms the low-fi structure.
+
+### Variations (Optional, Max 3)
+
+When the design direction is genuinely ambiguous, produce up to **3 variations** in the high-fi pass. Each in its own file. Create a `variations.html` hub that iframes or links to all three side-by-side for comparison:
+
+```html
+<!-- variations.html -->
+<div class="grid grid-cols-1 lg:grid-cols-3 gap-4 p-4">
+  <div>
+    <h3 class="font-semibold mb-2">V1 — Minimal ⭐ Recommended</h3>
+    <iframe src="./hero-v1.html" class="w-full h-[600px] border rounded"></iframe>
+    <p class="text-sm text-gray-600 mt-2">Best because [reason].</p>
+  </div>
+  <div>
+    <h3 class="font-semibold mb-2">V2 — Bold</h3>
+    <iframe src="./hero-v2.html" class="w-full h-[600px] border rounded"></iframe>
+    <p class="text-sm text-gray-600 mt-2">Better if [scenario].</p>
+  </div>
+  <div>
+    <h3 class="font-semibold mb-2">V3 — Editorial</h3>
+    <iframe src="./hero-v3.html" class="w-full h-[600px] border rounded"></iframe>
+    <p class="text-sm text-gray-600 mt-2">Better if [scenario].</p>
+  </div>
+</div>
+```
+
+Always mark one as **Recommended** with a one-line reason.
+
+### Delegating to `frontend-design` Skill
+
+If a `frontend-design` skill (or similar HTML/Tailwind generation skill) is available in the current session, delegate the actual mock construction to it — pass your layout decisions and content, let it produce the markup. If not available, build the markup inline. Either way, you own the layout decisions, the stack rules above, and the section-comment convention.
+
+### Presenting the Proposal
+
+Structure your message as:
+
+```
+## Design Proposal: [Feature Name]
+
+**Approach:** [1-2 sentences on direction and why]
+
+**Preview:** `.preview/<feature>-lowfi.html` (open in browser)
+
+### Key Decisions
+- [Decision]: [rationale]
+- [Decision]: [rationale]
+
+This is a throwaway mock — once you approve the direction I'll build
+it properly in your codebase using [shadcn / Material / your design system].
+
+Does the layout work? I can adjust any section before moving to high-fi.
+```
+
+---
+
+## Step 3: Mock vs. Edit — Decision Tree
+
+Not every request needs a standalone mock. Decide up front:
+
+### Mock first (build in `.preview/`)
+- New page or feature from scratch
+- Major redesign of an existing page
+- Multiple directions are plausible and you want the user to see them
+- User is non-technical and needs to see before they can react
+
+### Edit real code directly
+- Small tweaks to an existing component (color, spacing, copy)
+- Fixing a specific usability bug the user pointed at
+- Adding a single element to an already-approved layout
+- User is a developer who asked for a specific change
+
+### When in doubt — mock it
+The cost of a disposable HTML file is low. The cost of the user rejecting a real-code change and you having to undo it is higher.
+
+---
+
+## Step 4: Design Analysis (For Existing Projects)
+
+When auditing existing code, analyze yourself and present findings organized by impact.
+
+### What to Evaluate
+1. **Visual hierarchy** — Is important content visually dominant?
+2. **Consistency** — Are spacing, colors, components systematic?
+3. **Usability** — Contrast (WCAG AA minimum), touch targets (44px+), form labels, affordances
+4. **Responsiveness** — Does it work across breakpoints?
+5. **Interaction quality** — Transitions, loading/error/empty states
+6. **Dark mode** — If the project supports it, does this feature work in both themes?
+
+### Present Findings with Before/After Previews
+
+For each high-impact issue, produce a **before/after preview** in `.preview/audit/`:
+
+```
+.preview/audit/
+├── nav-before.html
+├── nav-after.html
+└── index.html    # Side-by-side comparison
+```
+
+Don't just list problems — show the fix in HTML the user can open.
+
+---
+
+## Step 5: Implementation (Real Codebase)
+
+Once the preview is approved, implement in the project's actual stack.
+
+### Order of Implementation
+1. **Layout structure and spacing** — Get the bones right first
+2. **Typography and color** — Apply the visual language
+3. **Component details** — Buttons, forms, cards (use the project's design system — shadcn, Material, etc.)
+4. **Interaction states** — Hover, focus, loading, error, empty
+5. **Responsive adaptations** — Mobile/tablet breakpoints
+6. **Dark mode** — If the project supports theming, verify both modes
+
+After each chunk, check in: "Layout is done — moving to typography next, or want to adjust anything?"
+
+### Browser Verification
+
+For UI changes, start the dev server and verify in a browser before reporting the task complete. Test the golden path and at least one edge case. If you cannot run the dev server, say so explicitly — do not claim the work is done based on a successful build or passing type check.
+
+### Implementation Rules
+
+Follow the anti-pattern catalog in [design-principles.md](references/design-principles.md):
+- No gratuitous gradients, glassmorphism, or trend effects without purpose
+- Intentional border-radius (not 9999px on everything)
+- Typography does 80% of the work
+- Color used sparingly: 1-2 primaries, 1 accent, rest neutrals
+- Faster transitions (150-200ms) for small elements, slower (300-400ms) for layout
+- Whitespace creates hierarchy
+
+### Adapting Existing Design
+- Preserve brand colors, fonts, recognizable patterns
+- Use existing CSS variables and design tokens
+- Introduce changes gradually
+- Flag when a user request conflicts with their design system; recommend the best path
+
+---
+
+## Step 6: Iteration
+
+### Responding to Feedback
+- **"I like it but..."** — Targeted adjustment in the preview, preserve what works
+- **"It's not what I imagined"** — Revise the preview before recoding
+- **"Can you try..."** — Update the preview, re-open
+- **"Perfect!"** — Move from preview to real implementation
+
+### When the User is Unsure
+1. Make the decision yourself based on best practices
+2. Explain your reasoning in plain language
+3. Build the preview
+4. Say: "This is what I'd recommend. If something feels off once you see it, tell me and I'll adjust."
+
+---
+
+## Handling Options — The Recommendation Rule
+
+**Every time you present a choice, you MUST include a recommendation.**
+
+For HTML previews with variations, render all variations but mark one as recommended in the hub file and in your message. Never present more than 3 variations at once.
+
+---
+
+## Skill Level Adaptation
+
+Infer from how the user communicates. Never ask.
+
+- **Non-designer**: Make all decisions, explain plainly, previews are essential, give complete code. Skip jargon.
+- **Some design sense**: Focus on trade-offs, provide code with brief rationale.
+- **Designer/developer**: Be concise, engage as a peer, previews can be lighter.
+
+---
+
+## Edge Cases
+
+- **No existing design**: Derive from project type and stack. Propose a cohesive starting point.
+- **Screenshot input**: Analyze visually, recreate as an HTML preview to confirm understanding before implementing.
+- **Design system conflict**: Flag it, recommend extending the system vs. one-off, explain trade-off.
+- **Accessibility**: Always meet WCAG AA. If a request would fail accessibility, explain plainly and offer an accessible alternative.
+- **Performance**: Flag heavy animations, large images, complex CSS; suggest alternatives.
+- **Dark mode**: If the project supports theming, every preview should include a dark-mode variant (toggle or separate file).
+- **No browser access**: If you can't run the dev server to verify, say so — don't claim success from a passing build alone.
+
+---
+
+## Resources
+
+- **Design principles**: [design-principles.md](references/design-principles.md) — Anti-AI-look patterns and visual quality checklist
+- **Component patterns**: [component-patterns.md](references/component-patterns.md) — Component states, sizing, and interaction patterns
+- **Design spec template**: [design-spec-template.md](assets/design-spec-template.md) — Structured output template for design handoff

package/skills/ui-ux-pro-v2/assets/design-spec-template.md

@@ -0,0 +1,173 @@
+# Design Specification — [Project / Feature Name]
+
+> Generated on [date] | Direction: [chosen direction name]
+
+---
+
+## Overview
+
+**Target:** [page / component / feature description]
+**Framework:** [React / Vue / Svelte / etc.]
+**CSS Approach:** [Tailwind / CSS Modules / styled-components / vanilla CSS]
+
+---
+
+## Design Tokens
+
+### Colors
+
+| Token | Value | Use |
+|---|---|---|
+| `--color-primary` | | Primary actions, brand accent |
+| `--color-primary-hover` | | Primary hover state |
+| `--color-secondary` | | Secondary actions, supporting |
+| `--color-background` | | Page background |
+| `--color-surface` | | Card/panel backgrounds |
+| `--color-text` | | Body text |
+| `--color-text-muted` | | Secondary text, captions |
+| `--color-border` | | Borders, dividers |
+| `--color-success` | | Success states |
+| `--color-warning` | | Warning states |
+| `--color-error` | | Error states |
+
+### Typography
+
+| Token | Value | Use |
+|---|---|---|
+| `--font-family-body` | | Body text, UI elements |
+| `--font-family-heading` | | Headings (if different from body) |
+| `--font-family-mono` | | Code, technical data |
+| `--text-xs` | 12px / 1.5 | Captions, badges |
+| `--text-sm` | 14px / 1.5 | Secondary text, labels |
+| `--text-base` | 16px / 1.6 | Body text |
+| `--text-lg` | 18px / 1.5 | Subheadings, emphasis |
+| `--text-xl` | 20px / 1.4 | Section headings |
+| `--text-2xl` | 24px / 1.3 | Page headings |
+| `--text-3xl` | 32px / 1.2 | Display, hero |
+| `--text-4xl` | 48px / 1.1 | Large display |
+
+### Spacing
+
+Base unit: `[4px / 8px]`
+
+| Token | Value | Use |
+|---|---|---|
+| `--space-1` | 4px | Tight gaps, inline spacing |
+| `--space-2` | 8px | Component internal padding |
+| `--space-3` | 12px | Compact element gaps |
+| `--space-4` | 16px | Standard element spacing |
+| `--space-6` | 24px | Section internal padding |
+| `--space-8` | 32px | Section gaps |
+| `--space-12` | 48px | Major section separation |
+| `--space-16` | 64px | Page-level spacing |
+
+### Borders & Radii
+
+| Token | Value | Use |
+|---|---|---|
+| `--border-width` | | Default border width |
+| `--border-color` | | Default border color |
+| `--radius-sm` | | Buttons, inputs, small elements |
+| `--radius-md` | | Cards, panels |
+| `--radius-lg` | | Modals, large containers |
+| `--radius-full` | | Avatars, pills |
+
+### Shadows
+
+| Token | Value | Use |
+|---|---|---|
+| `--shadow-sm` | | Subtle depth (cards) |
+| `--shadow-md` | | Moderate elevation (dropdowns) |
+| `--shadow-lg` | | High elevation (modals, popovers) |
+
+### Transitions
+
+| Token | Value | Use |
+|---|---|---|
+| `--transition-fast` | 150ms ease | Hover states, small elements |
+| `--transition-base` | 200ms ease | Standard transitions |
+| `--transition-slow` | 300ms ease-in-out | Layout changes, modals |
+
+---
+
+## Layout
+
+### Page Structure
+
+```
+[Describe or diagram the overall page layout]
+[Include breakpoint behavior]
+```
+
+### Grid / Container
+
+- Max width: [value]
+- Columns: [count at each breakpoint]
+- Gutter: [value]
+- Margin: [value at each breakpoint]
+
+### Breakpoints
+
+| Name | Min Width | Layout Changes |
+|---|---|---|
+| Mobile | 0px | [describe] |
+| Tablet | 768px | [describe] |
+| Desktop | 1024px | [describe] |
+| Wide | 1280px | [describe] |
+
+---
+
+## Components
+
+### [Component Name]
+
+**Purpose:** [what the component does]
+
+**Variants:**
+- [variant 1]: [description]
+- [variant 2]: [description]
+
+**States:**
+| State | Visual Treatment |
+|---|---|
+| Default | |
+| Hover | |
+| Focus | |
+| Active | |
+| Disabled | |
+| Loading | |
+| Error | |
+
+**Specs:**
+- Height: [value by size]
+- Padding: [values]
+- Font: [size, weight]
+- Border radius: [value]
+- Colors: [token references]
+
+---
+
+## Interaction Patterns
+
+### [Interaction Name]
+
+**Trigger:** [click / hover / scroll / load]
+**Behavior:** [describe the interaction]
+**Duration:** [transition timing]
+**Easing:** [easing function]
+
+---
+
+## Accessibility Notes
+
+- [ ] All contrast ratios meet WCAG AA
+- [ ] Focus indicators are visible and styled
+- [ ] Interactive elements have accessible labels
+- [ ] Heading hierarchy is logical
+- [ ] Motion respects `prefers-reduced-motion`
+
+---
+
+## Implementation Notes
+
+[Any technical notes, caveats, or implementation-specific guidance]