From 59c2fecf246b4ae750657dbbf55c1e7b6d341bfd Mon Sep 17 00:00:00 2001 From: nlook Date: Sat, 20 Jun 2026 13:14:17 +0900 Subject: [PATCH] Add design-from-code plugin (Design UX) Claude Code plugin & Codex skill that designs UI changes from real source code: verify what each number counts in code, iterate faithful AS-IS/TO-BE HTML mockups, lock a design doc, then delegate. MIT, by nlook (nlook.me). --- .claude-plugin/marketplace.json | 20 ++- .../.claude-plugin/plugin.json | 19 +++ .../skills/design-from-code/SKILL.md | 62 ++++++++ .../examples/issue-976-walkthrough.md | 56 ++++++++ .../references/code-fidelity-reproduction.md | 136 ++++++++++++++++++ .../references/data-model-verification.md | 86 +++++++++++ .../references/html-mockup-recipe.md | 121 ++++++++++++++++ .../references/prompt-templates.md | 106 ++++++++++++++ 8 files changed, 605 insertions(+), 1 deletion(-) create mode 100644 plugins/design-from-code/.claude-plugin/plugin.json create mode 100644 plugins/design-from-code/skills/design-from-code/SKILL.md create mode 100644 plugins/design-from-code/skills/design-from-code/examples/issue-976-walkthrough.md create mode 100644 plugins/design-from-code/skills/design-from-code/references/code-fidelity-reproduction.md create mode 100644 plugins/design-from-code/skills/design-from-code/references/data-model-verification.md create mode 100644 plugins/design-from-code/skills/design-from-code/references/html-mockup-recipe.md create mode 100644 plugins/design-from-code/skills/design-from-code/references/prompt-templates.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6f29b6b..4c1a4e3 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1670,6 +1670,24 @@ "security", "compliance" ] + }, + { + "name": "design-from-code", + "source": "./plugins/design-from-code", + "description": "Design UI changes from real source code: trace handler->query->schema to confirm what each number counts, iterate faithful AS-IS/TO-BE HTML mockups (keep/new/changed tags), lock a design doc, then delegate. Claude Code plugin & Codex skill.", + "version": "1.0.0", + "author": { + "name": "nlook" + }, + "category": "Design UX", + "homepage": "https://github.com/nlook-service/design-from-code", + "keywords": [ + "design", + "ui", + "mockup", + "workflow", + "html" + ] } ] -} \ No newline at end of file +} diff --git a/plugins/design-from-code/.claude-plugin/plugin.json b/plugins/design-from-code/.claude-plugin/plugin.json new file mode 100644 index 0000000..59ddce9 --- /dev/null +++ b/plugins/design-from-code/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "design-from-code", + "version": "1.0.0", + "description": "Workflow skill that designs UI changes from real source code and data models — verify data in code, iterate faithful HTML mockups, lock a design doc, then delegate implementation. It reproduces existing components pixel-for-pixel by reading actual JSX/queries instead of imagining them.", + "author": { + "name": "nlook", + "url": "https://nlook.me" + }, + "homepage": "https://github.com/nlook-service/design-from-code", + "license": "MIT", + "keywords": [ + "design", + "ui", + "mockup", + "workflow", + "html", + "skill" + ] +} diff --git a/plugins/design-from-code/skills/design-from-code/SKILL.md b/plugins/design-from-code/skills/design-from-code/SKILL.md new file mode 100644 index 0000000..f5faf07 --- /dev/null +++ b/plugins/design-from-code/skills/design-from-code/SKILL.md @@ -0,0 +1,62 @@ +--- +name: design-from-code +description: Workflow skill that turns one issue/requirement into a design in the order "verify real code & data → iterate faithful HTML mockups → design doc (.md) → delegate implementation." When designing a change to existing UI, it reads the actual component source and data model instead of imagining them, and reproduces the current screen pixel-for-pixel. Triggers (EN) "design this", "make a mockup", "how should this feature look", "add ~ to the existing screen"; (KO) "설계해줘", "시안 만들어줘", "이 기능 어떻게 보여줄지", "기존 화면에 ~ 추가". +--- + +# design-from-code — design mockups grounded in real source + +> One line: **lock facts with code → agree via HTML → nail it in a `.md` → ship by delegating.** +> The key difference: mockups are not *imagined*. They are reproduced down to the pixel and the number by **reading the real component JSX and data queries.** + +## When to use + +- Designing a change that **adds or modifies something** in an existing screen/component (e.g. "add a metrics card to the bottom bar") +- **UI re-layout / emphasis** requests like "it's hard to see / I want it shown like this" +- Exposing data (numbers, stats) on screen when you need to **pin down exactly what each number counts** +- When the user says "mockup first / show me in HTML" + +## When NOT to use + +- Pure backend/CLI work, changes with no UI +- A simple, already-agreed bug fix (no mockup needed) + +## Core principles (these override every other decision) + +1. **No guessing — read the code.** "How does this stat work?" is wrong ~100% of the time if you imagine it. Trace handler→query→schema all the way down, confirm it as *fact*, then design. → `references/data-model-verification.md` +2. **Reproduce the real component faithfully.** Before any new mockup, draw the **current state (AS-IS) exactly as the real JSX renders it**. Schematic drawings cause misunderstandings. → `references/code-fidelity-reproduction.md` (★ the heart of this skill) +3. **Pictures over prose.** Iterate with self-contained HTML you can see and fix. Bump the version (v2, v3…) on every round of feedback. → `references/html-mockup-recipe.md` +4. **Confirm one decision at a time.** "A vs B?" → "7-day window?" → "monotone color?" — ask narrowly. +5. **Mark keep / new / changed.** When "leave the rest as-is" is a requirement, use 🟦keep / 🟩new / 🟨changed color tags to show what you are *not* touching. +6. **Empty / initial state is first-class.** Always design the data-zero (new user) screen alongside the populated one. +7. **Delegate the build, but verification is mandatory.** Close it out with build / type-check / tests. + +## The 8-step workflow + +| # | Step | Key tools | Detail | +|---|------|-----------|--------| +| 1 | Read the issue verbatim | `Bash` + `gh issue view` | Don't open GitHub via WebFetch (auth fails) | +| 2 | Map the code | `Agent(Explore)` ×N | Get just the conclusions for related components/hooks/schema | +| 3 | **Verify the data** | `Bash` (grep/sed) + Explore | handler→use-case→repository→schema. `references/data-model-verification.md` | +| 4 | HTML mockup v1 | `Write` (.html) + `SendUserFile` | Phone frame, 2–3 options, per-state, inline SVG. `references/html-mockup-recipe.md` | +| 5 | User confirmation | reply / `AskUserQuestion` | Confirm one at a time; v2, v3 per feedback | +| 6 | **Faithful AS-IS/TO-BE** | `Bash` (read JSX with sed) + `Write` | Extract real render fns/classes/labels → HTML. `references/code-fidelity-reproduction.md` | +| 7 | Design doc `.md` | `Write` | Approved mockup + verified data model + build entry points + phases | +| 8 | Delegate + verify | `Agent` (language expert) + direct | Delegate with the contract & verify commands baked in; close with build/tests | + +## Reference files + +- `references/code-fidelity-reproduction.md` — **★ concrete technique for reading the real component with sed and reproducing it 1:1 in HTML** (worked `renderSeg` example) +- `references/data-model-verification.md` — how to trace the data model all the way down (events-table username-attribution example) +- `references/html-mockup-recipe.md` — recipe for self-contained HTML (phone frame, inline-SVG charts, design tokens, empty state) +- `references/prompt-templates.md` — copy-paste prompts for each step +- `examples/issue-976-walkthrough.md` — the full flow of a real case (v1→v5, including the point where the user corrected "top/bottom is reversed") + +## Common mistakes (checklist) + +- [ ] Wrote data behavior from a **guess** → did you confirm it in code? +- [ ] Mockup is **schematic** so it differs from reality → did you read the real JSX and reproduce classes & labels? +- [ ] Asked several decisions at once and caused confusion → did you confirm one at a time? +- [ ] "Keep existing" was the requirement but it's unclear what stays untouched → did you add keep/new/changed tags? +- [ ] Forgot the empty / initial state (data-zero) → did you include the empty-state design? +- [ ] Pulled in a chart library for the graph → did you use inline SVG instead? +- [ ] Skipped build/type-check after implementing → did you close it out with verification commands? diff --git a/plugins/design-from-code/skills/design-from-code/examples/issue-976-walkthrough.md b/plugins/design-from-code/skills/design-from-code/examples/issue-976-walkthrough.md new file mode 100644 index 0000000..15b581b --- /dev/null +++ b/plugins/design-from-code/skills/design-from-code/examples/issue-976-walkthrough.md @@ -0,0 +1,56 @@ +# Worked Example — Issue #976 (Mobile Bottom Brand Status) + +> The complete flow of applying this skill to a real issue. Recorded as-is, including why the mockup went from v1 through v5 and the exact points where the user corrected course. + +## Requirement (Issue, original text) +> "On the mobile bottom, instead of content that's hard to see, show information (numbers) that appeal psychologically, and make them big. Posts published, visitors, likes. A weekly graph showing the rate of change. Add a branding element." + +Target = the bottom sheet `MobileBottomBar`. + +--- + +## Application, Step by Step + +### [1] Read the issue +`gh issue view 976 ...` → restated intent: "Big numbers in the bottom bar (published / visitors / likes) + a weekly rate-of-change graph + branding." + +### [2] Map the code (Explore ×1) +→ peek = nav icons + the ＋ FAB; full = secondary menu, recent posts, calendar, brand metrics (the bottom 3 tiles), and footer. Found the reusable component `Sparkline.tsx`. Data comes from `fetchSummary` (currently days=1). + +### [3] Verify the data (direct sed + Explore) +Traced handler → use case → repository → schema. **Confirmed facts**: +- `events` has no author_id → **attribution is by the `username` string**. +- `WHERE username=$1 AND device_type<>'bot' AND is_self=false`. +- If there's no `doc`, it's **the home page plus all posts, summed**. A `daily[]` time series exists. +- Likes live only in `likes` and there's no aggregation API → **a new endpoint is needed**. +- There's no per-day time series for likes → decided to disable the graph tab. +→ This verification let us answer the user's question "Do visitors include both home and posts?" **with evidence from the code**. + +### [4]–[6] HTML mockup iterations (v1→v5) — ★user feedback drove the direction +| Version | Change | Trigger | +|---------|--------|---------| +| v1 | Compared two options: option A (hero) and option B (3 numbers) | First presentation | +| v2 | Locked in option B + data-model panel + added an **empty state** | "Like option B / visitors not available yet" | +| v3 | Introduced AS-IS vs TO-BE (keep / new / changed tags) | "Re-propose by combining existing + new on top of the current bar" | +| v4 | **Read the actual JSX** to reproduce faithfully (renderSeg, the ＋ FAB circle, the 5-cell grid, the date calendar) | "More accurate, please" | +| v5 | Corrected to **pin the menu at the top / status below the menu** | "The menu is the bottom bar, so it goes at the very top, with the proposal below it" | + +→ **Lesson**: faithful code reproduction in v4 (§code-fidelity) sharply raised accuracy, and in v5 the user corrected the top/bottom placement. Because we locked things down narrowly, one at a time, it converged fast. + +### [7] Design document +`docs/02-design/issue-976-mobile-bottom-brand-status-design.md` — the locked-in v5 + the verified data model + implementation starting points + P1/P2/P3. + +### [8] Implementation + verification +- Backend (delegated to a backend specialist): `GET //likes-summary?days=N` → `{total,current,previous}`. go build + 33 tests PASS. +- Frontend (done directly): days=1→14, the likes query, the status card (first child of the body, empty state), absorbing the existing metrics module. build 0 errors, net-new tsc 0 errors. +- Menu and existing modules left untouched. + +--- + +## Meta Lessons Taken From This Case + +1. **Data verification builds user trust.** Answering "Do visitors include both home and posts?" from the code let the design proceed without snags. +2. **Faithful reproduction is the key to mockup accuracy.** The "this is accurate" reaction came at v3 (schematic) → v4 (code reproduction). +3. **Spatial constraints like placement get lost in words.** A diagram + locking things down one at a time fixed it by v5. +4. **Empty states from the start.** With real visitors at 0, the empty state was actually the top-priority screen. +5. **Playwright is a supporting tool.** It all failed due to environment issues, but reading the source carefully was enough. diff --git a/plugins/design-from-code/skills/design-from-code/references/code-fidelity-reproduction.md b/plugins/design-from-code/skills/design-from-code/references/code-fidelity-reproduction.md new file mode 100644 index 0000000..aab3680 --- /dev/null +++ b/plugins/design-from-code/skills/design-from-code/references/code-fidelity-reproduction.md @@ -0,0 +1,136 @@ +# Faithfully Reproducing Real Components (Code-Fidelity Reproduction) + +> The heart of this skill. Accuracy "matching the current design" comes from **reading the actual source code, not from Playwright captures**. +> Goal: make the mockup HTML **look identical to the real component — down to the icons, labels, spacing, and colors**. + +--- + +## 0. Why read the code (not Playwright) + +- A screenshot only gives you "the visible result." **Class names, conditional rendering, per-state branches, and exact labels** live only in the code. +- Live-app captures (Playwright) depend on the environment (server boot, login, viewport), so they break often. In fact, on this task Playwright failed entirely with timeouts, and the **pixel-matching mockup was built from source reading alone**. +- Conclusion: **Priority #1 = reading the source.** A real Playwright capture is a supplementary aid for *verification/comparison* (nice to have, but optional). + +--- + +## 1. Procedure (5 steps) + +### STEP 1 — Find the component file +```bash +find app/src -iname "*BrandStudio*" # candidate files +grep -rln "하단바\|BottomBar\|StudioBar" app/src +``` + +### STEP 2 — Grasp the render function / structural skeleton +A component usually draws repeated UI through small `renderXxx` helpers. Find these first. +```bash +grep -n "renderSeg\|renderProfile\|leftSegs\|rightSegs\|ModuleCard\|return (" \ + app/src/components/mobile/MobileBottomBar.tsx | head +``` +→ You get a skeleton like "peek is `leftSegs.map(renderSeg)` + ＋FAB + `rightSegs.map(renderSeg)`." + +### STEP 3 — Read the render function body closely (★core) +Use `sed` to read the function body verbatim and extract its **Tailwind classes, icons, labels, and conditional styles**. +```bash +sed -n '/const renderSeg/,/^ );$/p' \ + app/src/components/mobile/MobileBottomBar.tsx +``` +What this actually yields: +```tsx +const renderSeg = (s) => ( + +); +``` +→ **Facts read off**: vertical layout (icon on top, label below), icon `h-5 w-5`, text `text-[10px]`, **no background/color — only active gets `font-bold text-foreground`** (monotone), rounded `rounded-xl`. + +### STEP 4 — Confirm exact labels, icons, and defaults +If labels are i18n, get the actual strings from the locale; if they're slot defaults, confirm them in the constants. +```bash +grep -n "DEFAULT_PEEK_SLOTS\|EDITABLE_KEYS" .../MobileBottomBar.tsx +sed -n '52,60p' app/src/locales/ko/bottomBar.json # actual labels +``` +→ peek defaults = `글·캘린더·＋·통계·프로필` (Posts · Calendar · ＋ · Stats · Profile), module titles = "최근 글" (Recent posts) · "이번 주" (This week), footer = `ABOUT|PRIVACY|TERMS`. +**Never invent labels here.** Use only the actual strings. + +### STEP 5 — Translate 1:1 into HTML/CSS +Map Tailwind classes to CSS of the same meaning. Use the **class → CSS mapping cheat sheet** (§2 below). +```html + +
글
+ +``` + +--- + +## 2. Tailwind → CSS mapping cheat sheet + +| Tailwind | CSS | +|---|---| +| `flex flex-col items-center` | `display:flex;flex-direction:column;align-items:center` | +| `gap-0.5` / `gap-2` | `gap:2px` / `gap:8px` (×4px) | +| `h-5 w-5` / `h-12 w-12` | `height/width:20px` / `48px` (×4px) | +| `text-[10px]` / `text-sm` / `text-xl` | `font-size:10px` / `14px` / `20px` | +| `font-medium/bold/extrabold` | `font-weight:500/700/800` | +| `rounded-xl` / `rounded-2xl` / `rounded-full` | `border-radius:12px / 16px / 50%` | +| `p-3` / `px-4 py-1.5` | `padding:12px` / `padding:6px 16px` | +| `bg-primary text-primary-foreground` | `background:var(--primary);color:#fff` | +| `text-foreground` / `text-muted-foreground` | `color:var(--foreground)` / `var(--muted-foreground)` | +| `border border-border` | `border:1px solid var(--border)` | +| `bg-muted/60` | `background:rgba(244,244,245,.6)` (theme muted + alpha) | +| `tabular-nums` | `font-variant-numeric:tabular-nums` | +| `shadow-md` | `box-shadow:0 4px 10px rgba(0,0,0,.15)` | + +> For design tokens (`--foreground`, `--primary`, etc.), check the real values in the project's theme CSS and put approximations into `:root`. If the project is monotone, keep it monotone. + +--- + +## 3. Handling icons + +- The real component typically uses an icon library (lucide, etc.). In the mockup, **a simple inline SVG** that mimics the same silhouette is enough. +- The key is to match the **size, weight, and monotone-or-not** exactly as read from the code (`h-5 w-5` → `width:20px`, `strokeWidth=2`). +```html + + + +``` + +--- + +## 4. AS-IS / TO-BE two-column layout + +- **AS-IS** = the *current state as-is*, reproduced via STEP 1–5. +- **TO-BE** = clone AS-IS, then swap **only the parts that change**. Prove with code that everything else is left untouched. +- Tag each block with a color: 🟦 unchanged (no `outline`) / 🟩 new (`outline:2px solid #86efac`) / 🟨 changed (`outline:2px solid #fcd34d`). +- **Placement constraints** are also drawn as a separate diagram box (top→bottom stack) to reach agreement. (e.g., "the menu is pinned to the top of the sheet, new items go below it" — on this task the user corrected this top/bottom ordering.) + +--- + +## 5. Common mistakes + +- ❌ Inventing labels ("대시보드" (Dashboard), "내 정보" (My info)) → ✅ Only the actual i18n strings. +- ❌ Painting the active state in color (blue) → ✅ If the code says `font-bold text-foreground`, use **weight/brightness** (preserve monotone). +- ❌ Making the ＋ button a rounded square → ✅ If the code says `rounded-full`, make it **circular**. +- ❌ Reordering modules arbitrarily → ✅ Keep the order as it appears in the JSX (Recent posts → This week → metrics → footer). +- ❌ Dropping conditional UI (e.g., the music-player row) → ✅ Reflect branches like `musicActive &&` in the mockup, at least as a comment. + +--- + +## 6. (Optional) Verify against a real Playwright capture + +Overlaying your source-built mockup **against an actual app screenshot** is the surest validation. But it's heavily environment-dependent. +```bash +# After booting the dev server, capture the real component in a mobile viewport → pixel-compare against the mockup +``` +- On this task, Playwright failed entirely — `file://` blocking, frame detached, timeouts — so **source reading alone was sufficient**. +- In other words, Playwright is **a supplement when available, skippable when not**. Priority #1 is always reading the source. diff --git a/plugins/design-from-code/skills/design-from-code/references/data-model-verification.md b/plugins/design-from-code/skills/design-from-code/references/data-model-verification.md new file mode 100644 index 0000000..8427e02 --- /dev/null +++ b/plugins/design-from-code/skills/design-from-code/references/data-model-verification.md @@ -0,0 +1,86 @@ +# Data-Model Verification + +> Confirm "exactly what does this number count?" **in code**. Designing on guesswork is 100% wrong. +> If the design surfaces stats/numbers on screen, finish this step *before* drawing any mockup. + +--- + +## 1. Trace Path (backend-first) + +``` +router registration → handler (auth · scope derivation) → use case (filters) → repository (WHERE clause) → schema (columns · attribution) +``` + +What to read at each step: +- **Router**: endpoint path · method · auth middleware. +- **Handler**: Who is it scoped to? (userID? token?) Which parameters (days, doc)? +- **Use case**: What does it filter by? userID→username conversion, etc. +- **Repository**: the actual SQL `WHERE` clause. **What it includes/excludes**. +- **Schema**: Whose *content* is this stat attributed to? (author_id? username? doc_uuid?) + +--- + +## 2. Practical Commands + +```bash +# Where the endpoint is registered +grep -rn "/summary\|/" server/internal --include="*.go" | grep -iE "Get|Post|route" + +# Read the handler closely (auth · scope) +sed -n '1,60p' server/internal//handler/summary_handler.go + +# Use case (filter derivation) +sed -n '1,60p' server/internal//usecase/summary.go + +# Repository WHERE clause (the crux) +grep -nE "WHERE|Username|device_type|is_self|COUNT|GROUP BY" \ + server/internal//repository/query_repository.go + +# Schema (attribution columns) +sed -n '1,80p' server//schema/event.go +``` + +If parallel investigation is needed, delegate to `Agent(subagent_type: Explore)` with a "trace it end to end" prompt (→ `prompt-templates.md`). + +--- + +## 3. Questions You Must Settle in One Line + +| Question | Example answer (this case) | +|------|------------------| +| Scoped by whom? | `WHERE username=$1` — the owner's handle (no author_id; attributed by username string) | +| What's included/excluded? | `device_type<>'bot'` (excludes bots) + `is_self=false` (excludes the owner) | +| What range is summed? | If no `doc`, **sum the home (/@handle) + all posts (/@handle/)** | +| Is there time-series / rate-of-change data? | `daily[]` (visitors per day) exists → fetch with days=14, split into last 7 / previous 7 | +| Unique vs. cumulative? | `unique_visitors = COUNT(DISTINCT visitor_id)` | + +→ **Settled output (one line)**: "Visitors = unique visitors across my entire public surface, excluding bots and the owner, summing home + all posts." + +--- + +## 4. Diagnosing "Looks Like There's No Data" + +When a number shows 0, distinguish **a tracing gap from genuinely absent data**: +- Check the beacon's firing condition (consent gate `isTrackingAllowed()`, etc.) — no consent means no collection. +- Whether the endpoint was committed/deployed (`git log -- `). +- Whether there's genuinely no traffic (new user) — in this case, solve it with an **empty-state design** (not a tracking problem). + +--- + +## 5. Don't "Invent" Time-Series or Rate-of-Change From Nonexistent Data + +- Some metrics have a daily time series (visitors `daily[]`); some don't (likes). +- For metrics without a time series, **disable the graph tab** or expose only "total + change." **No fake flat graphs** (honesty). +- Rate of change = sum for this period vs. sum for the immediately preceding equal period. If data exists for only one side, omit the rate of change. + +--- + +## 6. If New Data Is Needed → Define the Contract First + +If a metric is missing from the existing API (e.g., likes total), **settle the endpoint contract (JSON) first**, then delegate the implementation. +``` +GET /api//likes-summary?days=N (owner-authenticated) +→ { "total": 342, "current": 57, "previous": 41 } + total=all time, current=last N days, previous=the N days before that (for rate of change) +``` +With a contract in place, frontend and backend can proceed in parallel. diff --git a/plugins/design-from-code/skills/design-from-code/references/html-mockup-recipe.md b/plugins/design-from-code/skills/design-from-code/references/html-mockup-recipe.md new file mode 100644 index 0000000..7f26c30 --- /dev/null +++ b/plugins/design-from-code/skills/design-from-code/references/html-mockup-recipe.md @@ -0,0 +1,121 @@ +# Self-Contained HTML Mockup Recipe + +> Zero external dependencies, inline CSS/SVG only. Just open it in a browser and it renders. Build with `Write`, deliver with `SendUserFile`. + +--- + +## 1. Skeleton (copy-paste starting point) + +```html + + + +Issue #NNN · Mockup + + +``` + +--- + +## 2. Phone Frame (mobile mockup) + +```css +.phone{width:300px;aspect-ratio:300/640;background:var(--background); + border-radius:40px;border:1px solid var(--border);overflow:hidden;position:relative; + display:flex;flex-direction:column;box-shadow:0 10px 30px rgba(0,0,0,.07)} +.statusbar{height:30px;display:flex;justify-content:space-between;align-items:center; + padding:0 18px;font-size:11px;font-weight:700} +.sheet{position:absolute;left:0;right:0;bottom:0;background:var(--card); + border-radius:24px 24px 0 0;border-top:1px solid var(--border); + box-shadow:0 -8px 30px -12px rgba(0,0,0,.18);padding:0 16px} /* floating layer */ +.grip{height:6px;width:48px;border-radius:999px;background:rgba(113,113,122,.4);margin:8px auto} +``` +- Place **multiple phones side by side, one per state** (collapsed/expanded, etc.). +- Lay the background content as a blurred placeholder (`opacity:.4` gray blocks) to sell the "sheet floating above" effect. + +--- + +## 3. Inline SVG Charts (no chart libraries) + +**Sparkline (line)**: +```html + + + + +``` +**Area (gradient fill)**: +```html + + + + + + + +``` +**Bars**: use `flex` + height %. Emphasize today only with `background:var(--foreground)`. + +> Real implementations also often use inline SVG components (e.g. `Sparkline.tsx`) instead of a chart library, so the mockup's SVG doubles as an implementation hint. + +--- + +## 4. Big Number + Change Rate (monotone emphasis) + +```html +
+
1,284
+
Visitors
+
▲24%
+
+``` +- Emphasis = **size and weight** (not color). Reserve blue for the primary action button. +- Change rate = `▲`/`▼` glyphs. Increases bold (`text-foreground`), decreases dimmed (`muted`). (Or, if the user prefers, a soft green/red.) + +--- + +## 5. Comparing Variants (A/B) + Empty State + +- Put **2–3 layout variants** side by side on one page, with 2 lines of rationale under each. +- Include the **empty/initial state** as a separate phone (a new user with zero data). Use an action-driving CTA like "Waiting for your first ~ · Share". + +--- + +## 6. Keep/New/Changed Color Tags (AS-IS/TO-BE) + +```css +.hl-new{outline:2px solid #86efac;outline-offset:3px;border-radius:14px} /* new */ +.hl-chg{outline:2px solid #fcd34d;outline-offset:3px;border-radius:14px} /* changed */ +/* keep: no outline */ +``` +Show the legend as chips at the top of the page. + +--- + +## 7. Preview (optional) & Delivery + +- If possible, screenshot via a local server: + ```bash + cd {folder} && (python3 -m http.server 8777 &) # http://localhost:8777/file.html + ``` + Note that browser automation frequently blocks or times out on `file://` → **if it doesn't work, just deliver the file**. +- **Delivery**: send the `.html` file with `SendUserFile` (the user opens it directly in a browser). + +--- + +## 8. Versioning + +- Version in the filename: `mobile-bottom-...-v2.html`, `-v3.html`, … +- New version per round of feedback. The bigger the directional shift (layout correction, etc.), the more reason to keep the previous version for comparison. diff --git a/plugins/design-from-code/skills/design-from-code/references/prompt-templates.md b/plugins/design-from-code/skills/design-from-code/references/prompt-templates.md new file mode 100644 index 0000000..e73a237 --- /dev/null +++ b/plugins/design-from-code/skills/design-from-code/references/prompt-templates.md @@ -0,0 +1,106 @@ +# Copy-Paste Prompt Templates + +> Copy each step as-is and just swap out the `{curly_braces}`. You can hand these prompts directly to an AI when assigning it work. + +--- + +## [1] Read the issue (direct Bash) + +```bash +gh issue view {number} --repo {owner}/{repo} --json title,body,state,labels,comments,url +``` +→ If the body is ambiguous, **restate the user's intent in one sentence** before starting. + +--- + +## [2] Map the code — Explore agent + +``` +Map how {feature} is currently implemented in {path}. +Report with file path + line number + a short code excerpt: +1. What does {screen/component} render right now (state/slots/structure)? +2. Where does {data} come from — which hook/query/endpoint, and what shape are the response fields? +3. Reusable {chart/card/shared} components — names and props +4. Side data hooks such as {branding/profile} +Return a structured map, not a full dump. +``` + +--- + +## [3] Verify the data — Explore agent (backend) + +``` +Trace end to end how {endpoint} is computed and scoped. +router → handler (auth/scope) → use case (filters) → repository (WHERE clause) → schema (columns/ownership). +Answer the key questions explicitly: +- Who is it scoped by? (userId? username? global?) +- What is included/excluded? (bots excluded? self excluded? public only?) +- What is the aggregation range? (profile only? including posts? everything?) +- Is there already data to build a time series / rate of change? (fields like daily[]) +Return it structured with file + line number + WHERE-clause excerpts. +``` + +--- + +## [4] HTML mockup — working principles (instruction to yourself) + +``` +Build a single self-contained HTML file: +- States side by side inside a phone frame (e.g., collapsed/expanded) +- Compare 2–3 layout options, with 2 lines of rationale under each +- Inline CSS/SVG only, zero chart libraries +- Numbers in tabular-nums; emphasize with size/weight, not color (preserve the monotone theme) +- Include empty/initial states (zero data) as first-class too +Generate the .html with Write → deliver it with SendUserFile. +``` + +--- + +## [6] Faithful AS-IS/TO-BE reproduction — working principles + +``` +1. Read the actual component JSX with sed and extract the render functions (renderXxx), Tailwind classes, labels, and icon sizes. +2. Translate exactly what you extracted into HTML/CSS 1:1 (do not invent labels; stay faithful to the code, e.g., active = weight, not color). +3. Two columns: AS-IS (exactly as it is now) | TO-BE (swap in only the parts that change). +4. Mark what you are not touching with color tags: 🟦keep / 🟩new / 🟨changed. +5. Also agree on placement constraints via a top→bottom stack diagram. +``` + +--- + +## [7] Design doc .md — table of contents + +``` +Write to docs/02-design/{issue}-design.md: +1. Background/intent (one-line issue + user intent) +2. Layout decision (finalized mockup filename + ASCII structure diagram) +3. Data model (verified — table of definitions, sources, scope) +4. Implementation entry points (backend/frontend files, functions, routes + new API contract JSON) +5. Phases P1/P2/P3 +6. Principles/risks (performance, no-modification guarantee, honesty) +``` + +--- + +## [8] Delegate implementation — language-specialist agent + +``` +Add {endpoint/feature} as new. +Contract: {method, path, response JSON}. +Data model: {confirmed tables, columns, ownership}. +Follow the handler/use case/repository/dto pattern of the existing {similar feature} exactly. +Register the route next to the existing {similar route}. Wrap errors (fmt.Errorf) and pass context. +Verification required (report results): {build command} + {test command}, and add one unit test. +Return a summary of changed/added files + endpoint path + response fields. +``` + +--- + +## Decision questions (to the user, one at a time) + +``` +- Layout: Option A ({summary}) vs Option B ({summary}) — which direction appeals to you? +- Time range: fixed "this week (7 days)" vs a today/week/month toggle? +- Rate-of-change color: monotone (▲ weight) vs up=green / down=red? +- Placement: above or below the existing {existing} should {new} go? +```