diff --git a/.claude/skills/demo-ux/SKILL.md b/.claude/skills/demo-ux/SKILL.md new file mode 100644 index 00000000..42ac2d07 --- /dev/null +++ b/.claude/skills/demo-ux/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-ux +description: Best practices for designing, reviewing, or refining "try-it-now" interactive product demos, in-app product tours, onboarding walkthroughs, and sandbox experiences. Use when building or critiquing a demo page, tour component, tooltip copy, sandbox, aha-moment flow, reset/skip behavior, or any try-before-signup experience. Triggers on "demo UX", "ツアー設計", "ウォークスルー", "オンボーディング設計", "チュートリアル", "product tour", "walkthrough", "try it now", "サンドボックス設計", "デモのレビュー", or when reviewing files named `*Tour*`, `*Demo*`, `*Onboarding*`, `*Walkthrough*`. +--- + +# Demo UX Best Practices + +Knowledge base for designing try-it-now demos, product tours, and onboarding flows that convert. Grounded in 2024–2026 benchmarks (Navattic, Arcade, Chameleon, Userpilot, Appcues) rather than first principles — because most "design intuitions" in this space are wrong in ways only data reveals. + +## When to use + +- Designing a `/demo` or `/try` page from scratch +- Reviewing or refining an existing tour / tooltip / sandbox +- Deciding whether a tour should auto-start +- Writing tooltip microcopy +- Debating step count, skip behavior, or reset behavior +- Choosing between guided tour, free sandbox, or hybrid + +## Core decisions (checklist) + +Work through these in order. Each has a default answer backed by data; deviate only with a specific reason. + +### 1. Step count — **default: 3 steps** + +- **3 steps hits 72% completion. 4 steps → 45%. 7 steps → 16%.** The cliff between 3 and 4 is real. +- If the guided flow needs more than 3 steps, split it: 3-step tour + progressive disclosure (contextual tooltips fired later when the feature is actually used). +- A tour that explains features *before* the user tries them is almost always wrong. Fold explanation into the moment the user is about to use the feature (event-driven tooltips). + +### 2. Start trigger — **default: user-initiated, not auto-start** + +- **User-initiated tours complete 2–3× more often** than auto-start. +- Modal-on-arrival increases bounce. Don't cover the product on first paint. +- Instead: land in the sandbox, show a visible-but-dismissible CTA inline ("最初の1日を整えてみる →" / "Start the tour"). +- If you must nudge: delay 30–60s or trigger on idle / scroll. + +### 3. Initial state — **default: pre-broken, not empty** + +- Empty states push time-to-value past the user's attention budget. +- **Pre-broken > pre-populated > empty.** Grammarly (text with mistakes), Linear (seeded issues), Notion (getting-started workspace), Figma (community files) — none start empty. +- The pre-broken state *is* the aha setup: the user fixes it, the aha lands. +- Design the broken state so the problem is **visually obvious** — long bars, missing entries, visible conflicts. Don't require explanation. + +### 4. Progression — **default: event-driven, not click-Next** + +- "Click Next" tours let users advance without performing the value-creating action — the single biggest conversion killer in tour design. +- Fire the next tooltip **when the user completes the action** (drag finished, item deleted, form submitted). +- For non-action steps (welcome / summary), click-Next is fine. + +### 5. Tooltip copy — **default: 1 sentence, ≤150 chars, verb-first** + +- **≤150 chars, ~20–30 words, one idea per tooltip.** +- **Verb-first, second person, imperative**: "Add your first shift" beats "You can add shifts here." +- **Instructional > narrative.** Narrative fits marketing videos, not tooltips. +- Point at the next action, not at the feature. +- See `references/copy-patterns.md` for patterns and Japanese-specific nuances. + +### 6. Skip — **default: always visible, persistent, preserves state** + +- Skip control must be visible on every step. Forcing a tour == churn. +- Show step counter next to skip so the user can choose "3 more → done" vs. "skip". +- **Skipping should NOT reset the sandbox.** Let the user keep poking the state they've built. +- B2B tour completion averages ~5%. Skip is the default behavior, not the exception. + +### 7. Reset — **default: reload-resets, plus a visible "Start over" button** + +- Reload should restore initial state (simplest, no surprises). +- Additionally expose a visible "Reset demo" / "最初からやり直す" button in the page chrome. +- Single-step confirmation ("Your demo progress will be cleared"). No typed confirmation — this is a sandbox. +- Label as "Reset" / "Start over", not "Delete". + +### 8. End state — **default: inline CTA in the last step, not a full-screen modal** + +- Inline CTA in the last tooltip outperforms full-screen celebration for SMB flows. +- Show 1–2 differentiated CTAs: low-commitment + high-commitment ("Keep exploring" + "Start free"). +- **"Learn more" CTRs ~63%; "Book a demo" ~41%.** High CTR ≠ high qualified conversion — match wording to intent. +- Consider a persistent top-bar CTA for users who hit aha mid-flow. + +### 9. Mobile — **default: desktop-first with explicit fallback** + +- Interactive tours are desktop-first. That's the state of the industry. +- **52% of top-1% demos ship an optimized mobile experience** — the rest redirect or email-capture. +- Fallbacks: (a) simplified mobile-only demo, (b) looping video, (c) "best on desktop — email me the link". +- If the demo uses drag/drop/precision hover, a mobile fallback is mandatory. + +### 10. Analytics — **instrument these 5 events minimum** + +1. `demo_loaded` — page opened +2. `tour_started` — start CTA clicked (distinguishes auto vs. user-triggered) +3. `step_completed` — per-step with step id. Finds the one step killing the funnel. +4. `aha_reached` — custom event when the user completes the value-creating action +5. `cta_clicked` — final signup / upgrade CTA + +Top-1% demos: final CTR 67%, demo-to-signup 8× median. If your numbers are far from these, the fix is usually step-count or progression style — not copy. + +## The persona lens + +Two meta-personas matter: + +| Persona | Prefers | Why | +|---|---|---| +| **Hands-on SMB / operator** (shop owners, ops managers, ICs) | Sandbox > guided. Short tours. Try-it-now > sales demo | SMB buyers "tolerate lighter, shorter tours" (SmartCue). Self-serve converts. | +| **Exec / enterprise evaluator** | 90-second narrative video > interactive. Prefers demo-with-a-human | "Watch-to-evaluate" — Arcade-style video demos convert this persona better. | + +Building for both? Ship a 60–90s video demo alongside the interactive demo. Let the user choose. + +## Common anti-patterns (do not do) + +- 7+ step tours that front-load feature explanation +- Auto-triggered modal on first page load +- "Click Next" progression for action steps +- Empty initial state ("Add your first X to get started") +- Skip button hidden in an overflow menu +- Multi-step reset confirmation +- Full-screen celebration modal at end (over-ceremonious) +- Narrative / marketing copy in tooltips ("Welcome to the future of X…") +- Mobile "coming soon" dead-ends +- No aha-reached event instrumented + +See `references/anti-patterns.md` for extended list with symptom → cause → fix. + +## When to reference deeper files + +- **`references/benchmarks.md`** — specific numbers to justify a design decision (completion rates, conversion benchmarks, TTV, CTR by wording). Full citations. +- **`references/copy-patterns.md`** — when writing or reviewing tooltip / CTA / banner text, especially in Japanese. Includes verb-first patterns, 3 I's (Inform/Influence/Interact), Japanese copy nuances. +- **`references/anti-patterns.md`** — when reviewing an existing demo for problems. Organized as symptom → cause → fix. + +## Output discipline (when reviewing or proposing) + +1. **Lead with data, not opinion.** "3-step tours hit 72%, 7-step tours hit 16% — your 7 steps is in the wrong zone" beats "this feels long." +2. **State the default, then justify the exception** if the design deviates. +3. **Don't invent tooltip copy** without showing the underlying pattern (verb-first, ≤150 chars, event-driven). Otherwise the user treats it as decoration, not a design artifact. +4. **Always mention analytics.** "What 5 events are we instrumenting?" If the answer is "we'll figure that out later", the demo isn't done. + +## Scope boundaries + +- This skill covers **try-it-now demos, tours, and onboarding** — not marketing landing pages, not sales demos, not documentation sites. +- For full-screen mock design, use `/create-design`. +- For pinpoint UI polish unrelated to demos, use `/design-ideas`. diff --git a/.claude/skills/demo-ux/references/anti-patterns.md b/.claude/skills/demo-ux/references/anti-patterns.md new file mode 100644 index 00000000..32ab9198 --- /dev/null +++ b/.claude/skills/demo-ux/references/anti-patterns.md @@ -0,0 +1,117 @@ +# Demo UX Anti-patterns + +Organized as **symptom → cause → fix**. Use this file when reviewing an existing demo for problems. + +## Step count bloat + +**Symptom**: Tour has 7+ steps, each explaining a feature before the user tries it. +**Cause**: Designer assumed "more explanation = better understanding." In practice, front-loaded explanation doesn't stick and users bail. +**Fix**: Cut to 3 action steps. Move remaining explanations to contextual tooltips that fire when the user is about to use the feature. Treat the 3-step 72% completion benchmark as a hard ceiling. + +## Auto-start modal on page load + +**Symptom**: Landing on `/demo` immediately pops a modal that covers the product. +**Cause**: "Immediate engagement" interpretation that ignores user autonomy. +**Fix**: Render the sandbox first. Add a non-blocking inline CTA ("Start the 30-second tour →") in a dismissible banner or card. User-initiated completion is 2–3× higher. + +## Click-Next progression on action steps + +**Symptom**: Tooltip says "Try dragging this bar" but has a "Next" button the user can click to advance without ever dragging. +**Cause**: Default implementation in most tour libraries. Easier to build than event-driven. +**Fix**: Listen for the actual event (drag-end, click, submit). Advance the tour only when the user performs the action. Disable or hide "Next" on action steps. + +## Empty initial state + +**Symptom**: Demo opens to "Click + to add your first item" with nothing else on screen. +**Cause**: Developer-brain: fresh-account experience == demo experience. +**Fix**: Seed the demo with realistic, pre-broken content. The user should walk in and see a *problem they can fix*, not a blank canvas they need to populate. + +## Hidden skip / force-march tours + +**Symptom**: No visible skip control; user can only X out of the modal or close the browser tab. +**Cause**: "Don't let them leave the tour" reasoning. +**Fix**: Every step has a visible "Skip" / "自由に触る" control, adjacent to the step counter. Skipping preserves the sandbox state. B2B tour completion averages ~5% — designing for skip is designing for reality. + +## Skip resets the sandbox + +**Symptom**: User skips mid-tour, everything they did is wiped to initial state. +**Cause**: Conflation of "skip tour" with "reset demo". +**Fix**: These are two different operations. Skip leaves state alone. Reset (a separate button in page chrome) wipes state. Never collapse them into one. + +## Hard reset confirmation + +**Symptom**: "Reset demo" button opens a modal asking the user to type "RESET" to confirm. +**Cause**: Over-application of production-data safety patterns. +**Fix**: Single-sentence confirmation ("デモの操作内容がクリアされます。よろしいですか？") with a plain Yes button. This is a sandbox — reload already resets. + +## Narrative tooltip copy + +**Symptom**: Tooltips read like marketing copy: "Welcome to the future of scheduling! Our revolutionary approach lets you…" +**Cause**: Copy written by a marketer or written before the rest of the tour was designed. +**Fix**: Verb-first, instructional, ≤30 words, points at the next action. "Drag the bar to change 高橋さん's end time to 16:00." + +## Feature-label tooltip copy + +**Symptom**: Tooltip title says "Shift Editor" and body says "This is the shift editor." +**Cause**: Writer explained *what it is*, not *what to do with it*. +**Fix**: Rewrite as an action prompt. Title: "Edit a shift." Body: "Drag the bar to change the time." + +## 擬音語・抽象語の多用 (JP) + +**Symptom**: 「ぱっと伝わります」「さらっと見られます」のような曖昧な表現。 +**Cause**: 雰囲気の良い日本語を書こうとして具体性を失う。 +**Fix**: 具体的な動作・数字に置き換える。「スタッフ全員にメール送信されます」「30秒で要点が見られます」。 + +## 体言止めを本文で多用 (JP) + +**Symptom**: 本文が「シフトの編集。バーをドラッグで時間変更。」のように体言止めの連続。 +**Cause**: タイトル向けの指針を本文にも適用した。 +**Fix**: 本文は「バーをドラッグして時間を変えられます。」のように述語で終わる文に。体言止めはタイトル・見出しだけ。 + +## Full-screen celebration modal at end + +**Symptom**: Last tour step fills the screen with "🎉 Tour complete! You've mastered the basics!" +**Cause**: Over-ceremony; trying to manufacture a "moment". +**Fix**: Replace with an inline tooltip + 1–2 CTAs on the same spot where the last action happened. Less ceremony, more momentum. Inline CTA outperforms celebration modal for SMB flows. + +## Single end-of-tour CTA + +**Symptom**: Last step shows only "Sign up now." +**Cause**: Funnel focus without thinking about lower-intent users. +**Fix**: Two CTAs — low-commitment + high-commitment. "Keep exploring" next to "Start free." Capture users at whatever intent level they arrive at. + +## No mid-tour exit to CTA + +**Symptom**: User hits aha at step 2, wants to sign up, has to finish the tour or skip first. +**Cause**: Tour flow is a sealed box. +**Fix**: Persistent top-bar CTA throughout the demo. Catches the aha-and-go user (more common than you think). + +## Mobile dead-end + +**Symptom**: User on phone loads `/demo`, sees "Best viewed on desktop" and a back button. +**Cause**: Defer-to-desktop assumption. +**Fix**: At minimum, a looping video walkthrough. Better: a simplified mobile sandbox. Best: email-capture "send me the desktop link." 52% of top-1% demos ship an optimized mobile experience — the industry is moving on. + +## No analytics instrumented + +**Symptom**: Demo is live but nobody can answer "what % complete the tour? where do they drop off?" +**Cause**: "We'll add analytics later" that never comes. +**Fix**: Instrument 5 events on day 1: `demo_loaded`, `tour_started`, `step_completed` (per step), `aha_reached`, `cta_clicked`. Without them, you cannot improve the demo. + +## Demo treated as one-shot marketing artifact + +**Symptom**: Demo shipped, never iterated on. +**Cause**: Demo viewed as launch content, not as a product surface. +**Fix**: Review the demo funnel monthly. The step-with-highest-drop-off is the one to fix — fixing it typically yields +10–15% completion. + +## Demo data indistinguishable from real data + +**Symptom**: Users confused whether their demo actions are affecting a real account. +**Cause**: No visual cue that this is a sandbox. +**Fix**: Subtle but persistent "Demo mode" indicator in the chrome (top bar stripe, corner badge). Don't be so loud that it kills immersion; just enough for the user to know nothing is at stake. + +## Using real customer data as demo seed + +**Symptom**: Demo shows "田中太郎" from an actual user's account. +**Cause**: Lazy seeding that reuses production queries. +**Fix**: Use obviously-fictional names (「居酒屋シフトリ」「田中次郎」) and data shaped for the problem/resolution scenario. Privacy risk and weird authenticity both disappear. diff --git a/.claude/skills/demo-ux/references/benchmarks.md b/.claude/skills/demo-ux/references/benchmarks.md new file mode 100644 index 00000000..344cfe0f --- /dev/null +++ b/.claude/skills/demo-ux/references/benchmarks.md @@ -0,0 +1,109 @@ +# Demo UX Benchmarks (2024–2026) + +Cite these numbers when justifying a design decision. All sources are linked inline. + +## Step count & tour completion + +| Steps | Completion rate | +|---|---| +| 3 | **72%** | +| 4 | ~45% | +| 5 | 34% (median) | +| 7+ | 16% | + +- 2–4-step guides hover near 50% median completion ([Chameleon metrics](https://www.chameleon.io/blog/effective-product-tour-metrics)) +- Average well-designed tour: ~61% ([Chameleon 15M interactions](https://www.chameleon.io/blog/product-tour-benchmarks-highlights)) +- B2B SaaS onboarding tour *average* completion sits near **5%** across the industry — treat skip as the default behavior ([Chameleon comparison](https://www.chameleon.io/alternative/appcues-vs-pendo-vs-chameleon)) +- Fixing the single highest-abandonment step alone yields **+10–15%** completion (Appcues internal data via [Marketing Scoop](https://www.marketingscoop.com/service/35-customer-onboarding-statistics-you-need-to-know-in-2023/)) + +## Start trigger + +- **User-initiated tours complete 2–3× more often** than auto-start ([Chameleon](https://www.chameleon.io/blog/effective-product-tour-metrics)) +- Modal-on-arrival increases bounce. Best practice: wait 30–60s or tie to idle/scroll +- SaaS landing bounce rates sit at 35–55% baseline — forced modals push this worse ([Claspo](https://claspo.io/blog/what-is-a-good-bounce-rate-for-a-landing-page-7-ways-to-improve/)) + +## Time to value (TTV) + +- Across 547 SaaS products: median TTV ~**1 day, 12h, 23min** ([Userpilot TTV 2024](https://userpilot.com/blog/time-to-value-benchmark-report-2024/)) +- For interactive demo contexts: first value should hit in **<60 seconds**, full flow **<3 minutes** ([Arcade benchmarks](https://www.arcade.software/post/interactive-demo-benchmarks)) +- Aha ≠ activation. Aha is the emotional realization; activation is first hands-on use. Design both ([Chameleon](https://www.chameleon.io/blog/successful-user-onboarding), [Appcues](https://www.appcues.com/blog/aha-moment-guide)) + +## Progression style (event-driven vs click-Next) + +- "Click Next" tours let users advance without performing the value-creating action — **single biggest conversion killer** in tour design +- Event-driven tours enforce the activation event at the moment the tour was designed to produce it ([Usertourly](https://usertourly.com/blog/conversion-optimization/interactive-product-tours-do-they-really-improve-conversions-2)) + +## Sandbox vs guided tour (SMB hands-on persona) + +- Sandbox demos generate **6× more interactions** than traditional free trials and drive **35% higher meeting conversion** when scoped to a specific use case ([Guideflow](https://www.guideflow.com/blog/sandbox-demos-guide)) +- Interactive demos overall convert **7.2× better than demo videos** ([Navattic](https://www.navattic.com/blog/interactive-demos)) +- Motive lifted trial conversion **+5%** using resettable demos as leave-behinds ([Guideflow](https://www.guideflow.com/blog/sandbox-demos-guide)) + +## Initial state + +- Top-1% demos overwhelmingly ship pre-populated with realistic sample data ([Navattic 2025 report](https://www.navattic.com/report/state-of-the-interactive-product-demo-2025)) +- Pre-broken exemplars: Grammarly (pre-filled error text), Linear (seeded issues), Notion (getting-started workspace), Figma (community files) ([Userpilot examples](https://userpilot.com/blog/aha-moment-examples/)) + +## CTA wording on final step + +| CTA | CTR | +|---|---| +| "Learn more" | **63.3%** | +| "Book a demo" | **41.4%** | + +- High CTR ≠ high qualified conversion. "Try for free" / "Book a demo" drive more downstream conversion despite lower CTR ([Navattic ending](https://www.navattic.com/blog/ending-an-interactive-demo)) +- Top-1% demos hit **67%** CTR on final CTA (2× Navattic median) ([Arcade stats](https://www.arcade.software/post/interactive-demo-statistics)) +- Ship **1–2 differentiated CTAs** on the last step — low-commitment + high-commitment +- Users who engage a demo are **80%** more likely to complete multi-step activation ([Navattic 2025](https://www.navattic.com/report/state-of-the-interactive-product-demo-2025)) + +## Downstream outcomes + +- Top-1% demos convert to signup at **8.38× median** (8,040 vs 720 signups over 12 months) ([Arcade benchmarks](https://www.arcade.software/post/interactive-demo-benchmarks)) + +## Mobile support + +- **52% of top-1% demos** ship an optimized mobile experience; the rest redirect or email-capture ([Navattic mobile](https://www.navattic.com/blog/mobile-interactive-demos)) +- Common mobile fallbacks: + 1. Device-detect → swap to simplified mobile demo + 2. Serve a looping video walkthrough + 3. Email-capture "best viewed on desktop" form + +## Tooltip copy + +- **≤150 characters / ~20–30 words / one idea per tooltip** (industry consensus) +- **Verb-first, second person, imperative**. Format: **verb + object** ([Userpilot microcopy](https://userpilot.com/blog/microcopy-ux/), [Shopify microcopy](https://www.shopify.com/enterprise/blog/how-to-write-microcopy-that-influences-customers-even-if-they-don-t-read-it)) +- NN/g's **3 I's** — Inform, Influence, Interact. Each tooltip should do ≥2 ([NN/g](https://www.nngroup.com/articles/3-is-of-microcopy/)) +- Tour length sweet spot: 3–6 steps; beyond that, split into tour + checklist + contextual tooltips ([Jimo](https://jimo.ai/blog/interactive-product-tour)) + +## Persona + +- SMB / IC personas prefer self-serve free trials / hands-on demos +- Demos-with-a-human skew manager+ enterprise ([Userpilot free-trial-vs-demo](https://userpilot.com/blog/free-trial-vs-demo-saas/)) +- SMB buyers "tolerate lighter, shorter tours" → aim for 3-step tours + deep sandbox exploration after ([SmartCue guide](https://www.getsmartcue.com/blog/guide-to-self-serve-demos)) + +## Analytics — events to instrument + +| Event | Why | +|---|---| +| `demo_loaded` | Baseline pageview | +| `tour_started` | Distinguishes auto vs user-triggered starts | +| `step_completed` | Per-step drop-off identifies the one step to fix | +| `aha_reached` | Custom event when user completes the value-creating action | +| `cta_clicked` | Final signup/upgrade — the output metric | + +Funnel: demo_loaded → tour_started → step_completed (per step) → aha_reached → cta_clicked. + +## Key sources (full list) + +- Navattic: [State of Interactive Demo 2025](https://www.navattic.com/report/state-of-the-interactive-product-demo-2025), [Best practices 2026](https://www.navattic.com/blog/interactive-demos), [Ending a demo](https://www.navattic.com/blog/ending-an-interactive-demo), [Mobile demos](https://www.navattic.com/blog/mobile-interactive-demos), [Increase conversions](https://www.navattic.com/blog/increase-conversions-for-interactive-demos) +- Arcade: [Top 1% benchmarks](https://www.arcade.software/post/interactive-demo-benchmarks), [Demo stats 2025](https://www.arcade.software/post/interactive-demo-statistics), [SaaS demo practices](https://www.arcade.software/post/saas-demo-best-practices) +- Chameleon: [15M interactions benchmark](https://www.chameleon.io/blog/product-tour-benchmarks-highlights), [Effective metrics 2025](https://www.chameleon.io/blog/effective-product-tour-metrics), [Mastering tours](https://www.chameleon.io/blog/mastering-product-tours), [Successful onboarding](https://www.chameleon.io/blog/successful-user-onboarding) +- Userpilot: [TTV 2024](https://userpilot.com/blog/time-to-value-benchmark-report-2024/), [Aha examples](https://userpilot.com/blog/aha-moment-examples/), [Tooltip best practices](https://userpilot.com/blog/tooltip-best-practices/), [Microcopy](https://userpilot.com/blog/microcopy-ux/), [Free trial vs demo](https://userpilot.com/blog/free-trial-vs-demo-saas/), [Checklist benchmarks](https://userpilot.com/blog/onboarding-checklist-completion-rate-benchmarks/) +- Appcues: [Aha moment guide](https://www.appcues.com/blog/aha-moment-guide), [TTV](https://www.appcues.com/blog/time-to-value), [Tooltips](https://www.appcues.com/blog/tooltips) +- UserGuiding: [Tooltips](https://userguiding.com/blog/tooltips) +- Guideflow: [Sandbox demos guide](https://www.guideflow.com/blog/sandbox-demos-guide) +- Layerpath: [Interactive demos vs sandboxes](https://www.layerpath.com/resources/blog/interactive-demos-vs-demo-sandbox-environments-for-saas) +- Usertourly: [Conversion playbook](https://usertourly.com/blog/conversion-optimization/interactive-product-tours-do-they-really-improve-conversions-2) +- ProductLed: [Aha-moment onboarding](https://productled.com/blog/how-to-use-aha-moments-to-drive-onboarding-success) +- NN/g: [3 I's of microcopy](https://www.nngroup.com/articles/3-is-of-microcopy/) +- Pendo: [Measuring onboarding](https://www.pendo.io/resources/measuring-onboarding-effectiveness/) diff --git a/.claude/skills/demo-ux/references/copy-patterns.md b/.claude/skills/demo-ux/references/copy-patterns.md new file mode 100644 index 00000000..a9d37b88 --- /dev/null +++ b/.claude/skills/demo-ux/references/copy-patterns.md @@ -0,0 +1,127 @@ +# Demo Copy Patterns + +Writing patterns for tooltips, banners, and CTAs in product tours. Includes Japanese-specific nuances. + +## Universal rules + +1. **≤150 characters / ≤30 words / 1 sentence per tooltip** +2. **Verb-first, second person, imperative** — "Add your first shift" not "You can add shifts here" +3. **Instructional, not narrative** — narrative fits marketing videos, not tooltips +4. **Point at the next action** — tell the user what to do, not what the feature is +5. **NN/g's 3 I's** — Inform, Influence, Interact. Each tooltip should do ≥2 + +## Format: verb + object (+ brief reason) + +``` +[Action verb] [the thing], [micro-reason if non-obvious] +``` + +Good: +- "Drag this bar to change the time." +- "Click the staff member to assign a shift." +- "Delete this entry — 伊藤さん is out Monday." + +Bad: +- "You can drag bars to change times." (indirect, not action-oriented) +- "This is the shift editor." (labels, doesn't tell user what to do) +- "Welcome to the future of scheduling!" (marketing, not instructional) + +## One idea per tooltip + +A tooltip that explains three things is a tooltip that gets dismissed. If you have three things to say, you have three tooltips — or two tooltips and one checklist. + +Bad (three ideas): +> バーをドラッグで時間変更できます。バーをクリックすると削除メニューが出ます。編集が終わったら確定ボタンを押してください。 + +Good (one idea, fires at the right moment): +> バーをドラッグして、高橋さんの終業時間を16時に変えましょう。 + +## Japanese-specific patterns + +### 句読点と半角スペース + +- **本文** (tooltip content, banner body): 句読点（、。）を普通に使う。半角スペースで区切らない +- **タイトル・見出し** (tooltip title, banner heading): 句読点なしでOK。体言止め可。半角スペースで区切ってリズムを作るのも可 +- 混ぜない。タイトルで「日別 と 一覧」と書いたなら、本文では「日別で細かく、一覧で俯瞰できます。」のように明確に切り替える + +### 述語終わり vs 体言止め + +- タイトル: 体言止めOK（「シフトの編集」「確定ボタン」） +- 本文: 「〜できます」「〜です」のような述語終わりで書く。本文で体言止めを多用すると硬く、リズムが悪い + +### 擬音語・抽象語に注意 + +- 「ぱっと」「さらっと」「ちゃちゃっと」「すぐに」「きれいに」は、響きはよくても**具体的な情報を運ばない** +- 「ぱっと伝わります」より「スタッフ全員に送信されます」 +- 「さらっと見られます」より「30秒で要点が見られます」 +- 使う前に「何をどうするのか」で言い換えられないか考える + +### トーン + +- ですます調は固すぎない程度で使う。タメ口は避ける +- 「ご案内します」「お願いします」は一段フォーマル。中間トーンなら「案内します」「〜してください」 +- 謙譲語・尊敬語の過剰使用は避ける + +## Specific tooltip archetypes + +### 導入ステップ (welcome) + +- 1文、何ができるかを予告、次の行動へ誘導 +- 「自由に触れるデモです。最初の1日を整えてみましょう。」 + +### アクションステップ (action-prompt) + +- **どの要素を・何をするか・なぜか（あれば）** +- 「高橋さんのバーを16時までドラッグしてください。朝9時から11時間は長すぎます。」 +- ハイライトされているからユーザーは対象を見つけられる前提で、指示を明確に + +### 遷移ステップ (transition / summary) + +- 完了したことを短く認め、次へ誘導 +- 「3クリックで整いました。最後に確定ボタンを押しましょう。」 + +### 終了ステップ (end / CTA) + +- 1文で体験を言語化、CTA はボタン側に任せる +- 「実際のお店でも、同じように整えられます。」＋ [自分のお店で始める] [もう少し触る] + +## CTA wording + +| Tone | Examples | When | +|---|---|---| +| Low-commitment | "もう少し触る" / "Keep exploring" | Pair with high-commitment on final step | +| High-commitment | "自分のお店で始める" / "Start free" | Primary end-of-tour CTA | +| Informational | "詳しく見る" / "Learn more" | High CTR, lower conversion — use when intent is unclear | + +- **"Learn more" CTR ~63% / "Book a demo" ~41%**. Higher CTR ≠ higher qualified conversion. Match wording to the commitment level you actually want. + +## Banner / Invite card copy (non-tour entry) + +For a dismissible card that invites the user to start the tour from the sandbox: + +- **Headline** (short, may be体言止め): 「月曜のシフト、違和感ありますか？」「Try the 30-second walkthrough」 +- **Body** (1 sentence, instructional): 「3クリックで整えてみましょう。」「Watch the 3 things to fix, then do them yourself.」 +- **Primary button**: action verb + object: 「整える →」「Start walkthrough」 +- **Secondary / dismiss**: low-friction: 「自分で触る」「Maybe later」 + +## Reset / confirmation copy + +- **Button label**: "Reset demo" / "最初からやり直す" (avoid "Delete" — implies destroying real data) +- **Confirmation**: 1 sentence that names what's lost and reassures about real data + - "デモの操作内容がクリアされます。よろしいですか？" + - "Your demo progress will be cleared. No real data is affected." +- Single-step. No typed confirmation — this is a sandbox. + +## Skip tour copy + +- Label: "スキップ" / "Skip tour" / "自由に触る" / "ガイドなしで試す" +- Should never imply data loss ("Exit" or "Close" are fine; "Cancel" is ambiguous) +- Keep adjacent to step counter: `3 / 5 [スキップ]` so the user can trade "3 more → done" vs. "skip" + +## A/B hypothesis to test (when you have traffic) + +- Verb-first vs noun-first tooltip opens +- "Start tour" vs product-specific wording ("最初の1日を整える") +- Inline CTA in last tooltip vs full-screen celebration modal +- Persistent top-bar CTA on/off +- Video fallback vs dead-end on mobile diff --git a/.claude/skills/design-ideas/SKILL.md b/.claude/skills/design-ideas/SKILL.md new file mode 100644 index 00000000..40bb04f1 --- /dev/null +++ b/.claude/skills/design-ideas/SKILL.md @@ -0,0 +1,193 @@ +--- +name: design-ideas +description: Design principles for pinpoint UI refinement — polishing a specific component, adjusting colors/spacing/copy, or fixing something that "feels off." Not for whole-screen mocks (use `/create-design` for that). Triggers on `/design-ideas`, "デザイン見直して", "ここのUIよくして", "このコンポーネント整えて", "UI磨いて", "これダサいから直して", "refine this UI", "polish this component". Covers matching visual vocabulary, color discipline, declaring a system, scale, CSS surprise, filler/data slop, AI-slop anti-patterns, variation strategy, and content guidelines. +--- + +# design-ideas — Principles for Pinpoint UI Refinement + +Use this when the user points at a piece of UI and asks you to make it better — not when they ask for a full mock. These are craft principles for a designer, not procedural instructions. Read before you write. Observe before you change. + +Embody the relevant expert: visual designer, UX designer, prototyper. Avoid generic "web design" tropes unless the thing actually is a web page. + +--- + +## Match the existing visual vocabulary + +Before writing a single line, look around. Read adjacent components and the rest of the surface the element lives on. Observe and **think out loud** about: + +- Color palette and where accents appear +- Corner radii, shadow depth, border weight +- Density, rhythm, whitespace +- Copywriting style and tone +- Hover / click / focus / animation states +- Shadow + card + layout patterns +- Iconography style + +Then match it, unless the user has explicitly asked to break from it. Consistency inside a surface is almost always worth more than any single "better" choice in isolation. + +**Prefer code over screenshots.** Source tells you exact tokens, spacing, and structural choices. Screenshots only tell you appearance. When the codebase is available, read it. + +--- + +## Color discipline + +- Use colors from the existing brand / design system / palette. +- If the palette is genuinely too restrictive, compute new colors with `oklch()` so they harmonize with what's already there. +- Don't invent hex from scratch — the odds of it clashing subtly with the rest are high. +- Accent sparingly. One focal accent per view usually beats three. + +## Emoji + +Only use emoji if the brand / design system already uses them. Otherwise they read as AI output. Placeholder glyphs or simple iconography beat an arbitrary emoji. + +--- + +## Declare a system up front + +For anything beyond a one-line tweak, briefly state the system you'll commit to before writing: + +- One approach for section headers, not three. +- One type scale. One primary accent. +- 1–2 background colors max across the surface. +- Consistent rhythm: gutters, paddings, vertical spacing from the same scale. + +Variety should come from **deliberate rhythm and layout variation** (full-bleed vs card, dense vs airy section), not from mixing unrelated patterns. + +--- + +## Scale, deliberately + +Rule-of-thumb minimums — adjust for context, but don't go lighter without a reason: + +- **Mobile/touch**: tap targets ≥ 44×44 px. +- **Body copy**: ≥ 14 px on screen. +- **Presentation slides (~1920×1080)**: text ≥ 24 px, usually much larger. +- **Print**: body ≥ 12 pt. +- **Headings**: big enough to actually do the hierarchical work you're asking of them. + +Scale is a tool — using it timidly flattens the design. + +--- + +## CSS is bigger than most people use + +Users often don't know what CSS can do. Reach for it: + +- `text-wrap: pretty` / `text-wrap: balance` for headings and short text. +- CSS Grid (including named areas) over nested flex towers. +- `aspect-ratio`, `min()` / `max()` / `clamp()`, container queries. +- Layering with `z-index` + `position: sticky`. +- Modern color: `oklch()`, `color-mix()`. +- SVG masks, CSS masks, `backdrop-filter`. + +**Surprise the user when it serves the content** — novel layouts, scale play, layering, type-as-image. Not surprise for its own sake. + +--- + +## Placeholders beat bad attempts + +In hi-fi design, a clearly-labeled placeholder block is better than a half-faked rendering: + +- Don't draw illustrations from scratch in SVG — use a placeholder and ask for real assets. +- Don't render a fake chart with made-up data — use a labeled box. +- Don't fake a busy grid with invented content — show the structure and say "placeholder." + +Placeholders communicate design intent cleanly. Half-faked content communicates confusion. + +--- + +## Content discipline + +### No filler + +Never pad a design with dummy sections, placeholder paragraphs, invented stats, or decorative copy just because the layout feels empty. Every element should earn its place. **A thousand no's for every yes.** + +Emptiness is a layout problem. Solve it with composition, scale, or rhythm — not with made-up material. + +### No data slop + +Unnecessary numbers, unearned icons, KPI-shaped nothings, decorative percentages. If a number isn't carrying real meaning, cut it. If an icon isn't clarifying, cut it. + +### Ask before adding + +If you think another section, page, or block of copy would improve the design, **ask before adding it.** The user knows the audience and goals better than you do. Unilateral additions are a common failure mode. + +### Kill repetition + +The same point in two sections is a design bug. Reorganize or cut. + +### Copy honesty + +- Don't promise things the system doesn't do ("automatic", "instant", "always"). +- Communicate the experience, not the mechanism. Users care about the outcome, not the plumbing. +- Lead with benefit, not pain. No humble-brag. No condescension. +- Short. One line should often do two jobs (who it's for + what they get). + +--- + +## AI slop — avoid + +Common tells of AI-generated design: + +- Aggressive gradient backgrounds, especially purple / pink / orange washes. +- Emoji used as decoration without brand justification. +- Rounded containers with a left-border accent color (the "callout" trope). +- Illustrations drawn from scratch in SVG — use placeholders and ask for real assets. +- Overused default typefaces: Inter, Roboto, Arial, Fraunces, generic system stacks. Use what the project ships, or pick something with intention. +- Generic "web page" or "admin dashboard" framing applied to things that aren't either. +- Symmetric three-card feature rows with matching circular icons. Unearned parallel structure. + +--- + +## Variation strategy (when asked for options) + +If the user wants variations, make the spread meaningful: + +- **Safe, pattern-faithful** — uses the existing vocabulary as-is. The "ship tomorrow" option. +- **Exploratory, increasingly bold** — push on one dimension at a time: layout metaphor, information hierarchy, type treatment, density, interaction model. +- Start close to safe, get bolder as you go. + +Don't waste variants on trivial deltas — different accent colors or padding values isn't two options, it's one. Mix conservative with novel. Mix text-heavy with imagery-led. Mix dense with airy. The goal is to expose the user to many atomic choices so they can mix-and-match. + +--- + +## Start from context — don't mock from scratch + +Mocking a whole product from a blank page is a last-resort move that produces generic output. Before you build: + +- Read the design system, UI kit, or codebase the project has. +- Read adjacent feature code, not just screenshots. +- If context is missing, **ask** — for a screenshot, a reference product, a Figma link, a file — don't invent from thin air. + +"I couldn't find it so I made something up" is the failure mode. Ask instead. + +--- + +## Asking questions + +For anything beyond a trivial tweak, confirm context via a question rather than an assumption: + +- What's the starting point — a design system, a specific screen, a reference? +- Do they want divergent visuals, divergent UX, or just polish on the existing pattern? +- Which axis matters most — flow, copy, or visuals? +- Variations across which dimensions, and how many? + +Err on the side of more questions for ambiguous briefs. Skip questions only for small tweaks where intent is already clear. + +--- + +## Working process + +1. **Read the target and its neighbors.** Observe visual vocabulary before writing. +2. **State the approach** in 2–3 bullets for non-trivial changes: system, what to reuse, any intentional break and why. +3. **Keep the diff minimal.** Don't slip in refactors or adjacent cleanups. Fix the thing that was asked. +4. **Confirm direction-level choices, don't decide them unilaterally.** +5. **Report in 1–2 sentences** — what changed + the next useful action. + +--- + +## Not in scope + +- Whole-screen mocks → use `/create-design` +- Design-tool briefs (pencil / Figma) → use `/design-prompt` +- Decoration that wasn't asked for diff --git a/.claude/skills/ui-architect/SKILL.md b/.claude/skills/ui-architect/SKILL.md new file mode 100644 index 00000000..bfa4b923 --- /dev/null +++ b/.claude/skills/ui-architect/SKILL.md @@ -0,0 +1,273 @@ +--- +name: ui-architect +description: UI/UX実装・提案時に必ず使う汎用UI設計スキル。ユーザーのやりたいことを「タスク → 画面構造 → コンポーネント → レイアウト → 状態 → コピー」に分解し、CSSフレームワーク（主にChakra UI v3 + プロジェクトの`src/components/ui/`ラッパー）のどの部品をどう組み合わせれば最短で伝わるUIになるかを判断する。見せ方のプロとして情報設計・視覚階層・インタラクションの最適解を選ぶ。**UIに触る全ての作業で呼ばれる**：新規画面・フォーム・ダイアログ・一覧・カード・ダッシュボード・ナビ・空状態・ローディング・モバイル対応・コンポーネント選定・レイアウトのバランス・「これどう見せればいい？」系の相談。トリガー例「画面作って」「UI実装」「UI提案」「どのコンポーネント使う？」「モーダルにする？」「レイアウトどうする？」「このUIどう？」「もっと良い見せ方ない？」「どう配置する？」「build a UI」「what component」「how to lay out」「modal or drawer」。他スキルと補完関係：`/create-design`（pencilでモック）、`/design-ideas`（既存UI微調整）、`/ux-writing`（文言）、`/demo-ux`（デモ体験）と連携する。 +--- + +# UI Architect + +UIに触る前に**必ずこのワークフローを通す**。コードを書き始める前に、最低でも「ゴール分解」と「コンポーネント選定」は明示的に言語化すること。頭の中で済ませない — 決めたことを短くユーザーに共有してから実装する。 + +> **この職能の本質**: ユーザーのタスクを翻訳して、人間が迷わず達成できる形に落とす。カッコよさより、使いやすさ・伝わりやすさ・速さが最上位。見た目を考えるのは最後。 + +--- + +## ワークフロー（順守） + +### ① ゴール分解 → ② 情報アーキテクチャ → ③ コンポーネント選定 → ④ レイアウト・視覚階層 → ⑤ 状態設計 → ⑥ マイクロコピー → ⑦ 実装 → ⑧ 触って検証 + +### ① ゴール分解 + +ユーザーの要求を以下に分ける： + +- **プライマリータスク**（1画面1つ）: ここに来て一番やりたい行動 +- **セカンダリータスク**: 補助・副次的な行動 +- **捨てるタスク**: この画面ではやらせないこと +- **ユーザーコンテキスト**: 誰が / 何回 / どのデバイス / どんな心理状態 +- **データ形状**: 1件 or 多件 / 読み中心 or 編集中心 / 静的 or 頻繁更新 + +プライマリーが2つ以上ある画面は分解失敗。分割 or 1つを主、残りを従に格下げ。詳細 → `references/decomposition.md` + +### ② 情報アーキテクチャ（IA） + +データ形状と利用頻度からページ骨格を決める： + +| シナリオ | 骨格 | +|---|---| +| 単一タスク集中（フォーム・読み物） | 中央1カラム（フォーム≤640px / 読み物≤720px） | +| ダッシュボード | KPIカード帯 + グラフ + 詳細テーブルの12カラムグリッド | +| 詳細表示（マスタ1件） | ヘッダー + 本文2カラム or タブ切替 | +| エディタ系 | 左ナビ + 中央キャンバス + 右プロパティ | +| 一覧 → 詳細 | リスト + ドリルダウン（or 選択行 + 右プレビュー） | +| モバイル全般 | 縦スタック + 下部固定CTA or BottomSheet | + +詳細 → `references/layout.md` + +### ③ コンポーネント選定 + +タスクごとに下の判定ツリーで決める。迷ったら `references/components.md` と `references/chakra-v3.md`。 + +### ④ レイアウト・視覚階層 + +- **1画面1つの主役**：最優先アクションをサイズ・色・位置で明示する。残りはsecondary/ghostに落とす。 +- **F字・Z字スキャン**：左上〜右下の目線に、重要情報 → アクションの順に置く。 +- **近接・整列**：関係するものは近く、関係ないものは離す。縦軸 or 横軸いずれかで揃える（バラバラにしない）。 +- **8ptグリッド**：4/8/12/16/24/32/48/64 以外の間隔は使わない。 +- **タイポ階層**：3段階が上限（H1 / H2 / Body）。サイズ・太さ・色のどれかで差をつける。全部変えない。 +- **色は意味**：装飾に色を使わない。ブランド・状態・アクション・中立の4カテゴリのみ。詳細→ `references/layout.md` + +### ⑤ 状態設計（**必ず全部書く**） + +- Loading（Skeletonが第一候補、Spinnerは最後の手段） +- Empty（初回・検索ゼロ件・クリア済みで出し分け） +- Error（フィールド/セクション/ページの3レベル） +- Success（Toastか永続バナーか、インラインチェックか） + +詳細 → `references/states.md` + +### ⑥ マイクロコピー + +ボタン・ラベル・エラー・空状態・Toast・確認ダイアログは `/ux-writing` に委譲。ただし最低限： + +- ボタン：動詞+目的語（「保存」より「変更を保存」）。「OK」禁止。 +- 破壊的操作：結果を具体的に書く（「本当に？」ではなく「このシフトを削除します」） +- エラー：何が / なぜ / 次どうする の3点。 +- 空状態：事実＋次の一歩。 + +### ⑦ 実装 + +- プロジェクト規約（下記「プロジェクト固有ルール」）を守る。 +- Chakra UI v3 プリミティブ + `src/components/ui/*` ラッパーを優先。既存ラッパーがあるのに自作しない。 +- フォームは react-hook-form + zodResolver、Submitは常にenabled、バリデーションは押下後。 + +### ⑧ 検証 + +- Storybookで状態ごと（loading/empty/error/success）を見る。 +- 複雑な動きがあればInteractive Storyで操作テストを書く。 +- モバイルビュー / デスクトップビュー両方で確認。 +- 必要ならPlaywright MCPやStorybook MCPでスクショ。 + +--- + +## クイック判定ツリー（頻出） + +### 選択肢を選ばせたい + +| 状況 | 部品 | +|---|---| +| ON/OFF の設定（即時反映） | `Switch` | +| 同意・チェック付与（明示確定） | `Checkbox` | +| 2〜5択・排他・全選択肢見せたい | `SegmentedControl` / `RadioGroup` | +| 6〜10択・排他 | `Select` | +| 11+択・排他・検索したい | `Combobox`（検索付き） | +| 複数選（少・全部見せたい） | `CheckboxGroup` | +| 複数選（多・タグ追加的） | `MultiCombobox` / `TagInput` | +| 数値（小範囲・段階的） | `NumberInput` / `Slider` | +| 数値（大範囲・自由入力） | `Input type=number` | +| 日付（単日） | `DatePicker` | +| 日付（期間） | `DateRangePicker` + プリセットchips（今日/今週/今月） | +| 時刻 | `TimePicker` or 分割Input（hh / mm） | + +Hickの法則：選択肢が増えるほど決定は遅くなる。11+はデフォルト値 or カテゴリで分ける。 + +### 入力・編集をどこに置く？ + +| 状況 | 置き場所 | +|---|---| +| 1〜3項目のインライン修正 | `Popover` / インライン編集 | +| 4〜10項目の作成・編集 | `Dialog`（Desktop） / `BottomSheet`（Mobile） | +| 11項目+ or 段階的入力 | 専用ページ or `Drawer`（右） | +| 破壊的操作の確認 | `AlertDialog`（赤ボタン、結果明示） | +| コンテキストアクション | `Menu` / `Popover` | +| 永続フィードバック | `Banner` / `Alert` | +| 非ブロッキング完了通知 | `Toast` | + +詳細 → `references/navigation-containers.md` + +### データを見せたい + +| データ形状 | 部品 | +|---|---| +| 同種で多属性・比較・ソート | `Table` | +| 単純で主属性1つ+アクション | `List`（行） | +| 不均質・視覚・ブラウズ | `Card` list | +| 視覚的に同等・一覧性 | `Grid of cards` | +| 時系列 | `Timeline` / `Feed` | +| 階層構造 | `Tree` | +| ワークフロー状態 | `Kanban` | +| スケジュール | `Calendar` | +| メトリクス・サマリー | `KPI Card` + `Chart` | + +詳細 → `references/data-display.md` + +### フィードバック・モードレス + +| 状況 | 部品 | +|---|---| +| ヘルプ・説明（hover） | `Tooltip`（非インタラクティブ） | +| リッチなヘルプ・補足UI | `Popover` / `HoverCard` | +| 小さな状態ラベル | `Badge` / `Tag` / `Chip` | +| 進行度（既知） | `Progress`（線） / `Stepper` | +| 進行度（不明） | `Spinner` / `Skeleton` | +| 一時的成功・失敗通知 | `Toast` | +| 画面全体に関わる注意 | `Banner` | + +--- + +## アンチパターン（実装前に自己チェック） + +- ❌ **モーダル乱用**：ページ遷移で済むことをモーダルに詰める。深い編集・長尺フォームはページ or Drawer +- ❌ **ボタンが全部同じウェイト**：プライマリが1つ、残りsecondary/ghost +- ❌ **ラベルなしアイコン**：初見で意味わからないアイコンはラベルorTooltip必須 +- ❌ **空状態なし**：初回ユーザー詰む。必ず"事実+次の一歩"を用意 +- ❌ **スピナーだけ**：何が起きてるか不明。`Skeleton`でレイアウト保持 +- ❌ **プレースホルダー=ラベル**：入力中に消える。ラベルは常に見せる +- ❌ **モバイルで多カラムフォーム**：親指が届かない。1カラム基本 +- ❌ **影の氾濫**：elevationは`base`と`raised`の2段階が限度 +- ❌ **色の乱用**：決めた意味の色以外を足さない（プロジェクト規約下記） +- ❌ **3フォントファミリー以上**：基本1、最大2 +- ❌ **変数の不一致**：font-size 13pxや17pxなどトークン外の値を使う +- ❌ **中央寄せ羅列**：左寄せで揃える方が読みやすい（カード中心寄せは装飾時のみ） +- ❌ **枠線の二重化**：ヘッダー下線 + カード枠線が重なる → 片方消す +- ❌ **カードが全部同じ**：均質グリッドは情報階層を殺す。大小混在を許す +- ❌ **フォームのインライン2カラム**：例外（CC有効期限、郵便番号+住所）を除き縦1カラム +- ❌ **確認ダイアログの「本当に？」**：結果を書く（"3件のシフトを削除します"） +- ❌ **破壊的ボタンがプライマリ配色**：`colorPalette="red"` + 右端がほぼ必須 +- ❌ **情報詰め込み**：画面に10以上の焦点 → Miller's Law違反、分割 + +詳細 → `references/anti-patterns.md` + +--- + +## プロジェクト固有ルール（このリポジトリで絶対） + +### フレームワーク・コンポーネント + +- **Chakra UI v3 + `src/components/ui/*`**（BottomSheet / Dialog / Empty / FormCard / FullPageSpinner / InfoGuide / LazyShow / LoadingState / Select / Title / toaster / tooltip / Tour） +- 既存ラッパーがあるのに自作しない。迷ったら `references/chakra-v3.md` を確認 +- Select × モーダル/BottomSheet内：`usePortal={false}` +- BottomSheetがドロップダウンをクリップ：`overflowY="visible"` +- Icons: 既存の `react-icons` を踏襲（独自SVGを足す前に確認） + +### 色・状態 + +- `teal` = ブランド・主アクション +- `orange` = 要対応・警告 +- `green` = 達成・完了 +- `gray` = 中立・完了済み・非アクティブ +- `red` = 削除・エラー +- `yellow` はほぼ使わない + +### 状態管理・データ + +- Jotai atoms（`selectedShopAtom`, `userAtom`） +- Convex `useQuery`はpages層、`useMutation`はfeatures層 +- pagesでエラー/ローディング/正常振り分け、正常系のみfeaturesを呼ぶ + +### フォーム + +- react-hook-form + zodResolver +- Submitは常にenabled、エラーは押下後 +- mutation Zodスキーマは `convex/{useCase}/schemas.ts` 起点 + +### 日付 + +- `dayjs`必須。`new Date().toISOString()`によるYYYY-MM-DD生成は禁止（TZずれ） +- Convex層はdayjs不可なので文字列比較（"YYYY-MM-DD"） + +### MVP段階 + +- SideMenuは含めない（BottomMenuのみ） +- 大きく不確実なUIは pencilで作り込まず**プレースホルダーパターン**で + +### 文言 + +- タイトル・サブタイトル：句読点なし・半角スペース区切りOK +- 本文：句読点あり・体言止め多用しない・「〜できます。」で具体的に +- 詳細は `/ux-writing` + +### Storybook + +- `@storybook/react-vite` を使う（`@storybook/react`ではない） +- `@storybook/test` はない。コールバックは `() => {}` +- 小さなコンポーネントはVariants Story 1つに集約（VRT節約） +- 大きなコンポーネントはそのまま、必要ならInteractive Storyを別途 + +--- + +## 他スキルとの分担 + +| やりたいこと | 使うスキル | +|---|---| +| 新しい画面・機能のUI戦略・コンポーネント選定・骨格 | **ui-architect（これ）** | +| pencilでモック・デザインカンプを作る | `/create-design` | +| 既存UIを1コンポーネント単位で磨く | `/design-ideas` | +| LP・マーケ・ビジュアル重視のフロントを作る | `frontend-design` | +| ボタン・エラー・FAQなどの文言 | `/ux-writing` | +| 未ログインの体験版・オンボーディングツアー | `/demo-ux` | +| 設計判断で複数案を議論 | `/discuss` | + +ui-architectは**すべてのUI作業の土台**。他スキル呼び出し時も判定ツリーとアンチパターンは適用する。 + +--- + +## リファレンス（必要時に読む） + +- `references/decomposition.md` — ゴール分解の詳細・ヒアリング手順・代表例 +- `references/layout.md` — IA・グリッド・タイポ・スペーシング・カラー階層 +- `references/components.md` — コンポーネント選定の全判定ツリー（フレームワーク非依存） +- `references/forms.md` — フォーム設計パターン（ラベル・バリデーション・多段・モバイル） +- `references/data-display.md` — 一覧・テーブル・ダッシュボード・フィルタ・ページング +- `references/navigation-containers.md` — ナビ・モーダル/ドロワー/BottomSheet・トースト +- `references/states.md` — Loading/Empty/Error/Success/Skeleton/楽観更新 +- `references/anti-patterns.md` — 詳細アンチパターン集 +- `references/chakra-v3.md` — Chakra UI v3 ↔ カテゴリのマッピング・プロジェクトラッパー +- `references/laws-of-ux.md` — UX原則（Fitts / Hick / Miller / Gestalt / Peak-end等）の実践運用 + +使い分け： +- 迷ったコンポーネント選定 → `components.md` + `chakra-v3.md` +- レイアウトのバランスが悪い → `layout.md` +- フォームを作る → `forms.md` +- 一覧・テーブル・ダッシュボード → `data-display.md` +- モーダル vs Drawer vs ページで迷う → `navigation-containers.md` +- 空状態・ローディングをどうするか → `states.md` +- 「なんかしっくりこない」 → `anti-patterns.md` + `laws-of-ux.md` diff --git a/.claude/skills/ui-architect/references/anti-patterns.md b/.claude/skills/ui-architect/references/anti-patterns.md new file mode 100644 index 00000000..bce4d828 --- /dev/null +++ b/.claude/skills/ui-architect/references/anti-patterns.md @@ -0,0 +1,279 @@ +# UI アンチパターン集 + +実装前後で自己チェックすべきよくある失敗。SKILL.md の短縮版を詳述する。 + +## モーダル乱用 + +**症状**：何でもモーダルに乗せる、モーダル内モーダル、長尺フォームをモーダルで。 + +**問題**： +- ナビゲーション（戻る/共有）が死ぬ +- モバイルで全画面塞ぐ +- 中身が読みづらい（スクロール、focus trap） + +**正解**： +- 軽い確認 → AlertDialog +- 中規模編集 → Dialog (PC) / BottomSheet (Mobile) +- 大規模編集 → 専用ページ or Drawer + +## ボタンが全部 Primary（ヒエラルキーなし） + +**症状**：保存・キャンセル・削除が全部塗りボタンで並ぶ。 + +**問題**：どれをタップすべきか視線が迷う。誤タップ増。 + +**正解**：1画面1Primary、残りはSecondary/Ghost、破壊はred。 + +## ラベルなしアイコン + +**症状**：ヘッダーに虫眼鏡・歯車・…・三本線が並ぶ。説明なし。 + +**問題**：意味がわからない、Tooltipにhoverできないモバイルではゲーム化。 + +**正解**： +- 普及アイコン（×, 検索, 戻る, +）以外はラベル併記 +- IconButton のみにする時はTooltip必須 +- モバイルはラベル併記の方が安全 + +## 空状態がない + +**症状**：データがゼロ件のとき、何も表示されない or "Empty"だけ。 + +**問題**：初回ユーザーが詰む。次に何をすればいいかわからない。 + +**正解**：「ここにXが表示されます。最初のXを作りましょう [作成]」 + +## スピナーだけのローディング + +**症状**：ページ全体を白くして真ん中で spinner グルグル。 + +**問題**：何が出てくるか想像できず、待ち時間が体感長くなる。 + +**正解**：Skeleton。レイアウト形状を保持、shimmer。Suspense Streamingで段階的に。 + +## プレースホルダー＝ラベル + +**症状**：ラベルなし、プレースホルダーに「メールアドレス」と書く。 + +**問題**： +- 入力中に消えて何の入力か忘れる +- スクリーンリーダー読み上げ不安定 +- 既入力フォームを見たとき何のフィールドかわからない + +**正解**：トップラベルを常に表示。プレースホルダーは "例: yamada@example.com" の例示のみ。 + +## モバイルで多カラムフォーム + +**症状**：氏名を「姓 / 名」横並びにしてモバイルで2カラム。 + +**問題**：1カラム幅が狭くて入力しづらい、タップ精度落ちる。 + +**正解**：モバイルでは1カラム強制。例外（電話・郵便等）のみ横並び。 + +## 影の氾濫（多段elevation） + +**症状**：カードに影、その中のサブカードにも影、ホバーでさらに影。 + +**問題**：立体感が崩壊し、平面でも立体でもない不気味な見た目。 + +**正解**：影は2段（base, raised）まで。Modal/Drawerだけ`xl`、それ以外は`sm`か`md`まで。 + +## カラー乱用 + +**症状**：ブランド色とは関係ない色を装飾で散らす（紫の見出し、青のボタン、緑の枠線）。 + +**問題**：何が意味のある色で、何が装飾かが伝わらない。 + +**正解**：色は意味を持たせる。装飾色は使わない。プロジェクトでは `teal`, `orange`, `green`, `gray`, `red` のみ。 + +## 3+ フォントファミリー + +**症状**：見出しに変わったフォント、本文標準、コードに別フォント、署名にスクリプト体。 + +**問題**：散漫、デザイン崩壊感。 + +**正解**：基本1ファミリー、最大2（コード用に等幅を追加など）。 + +## トークン外の値 + +**症状**：font-size 13px、margin 17px、padding 22px。 + +**問題**：8ptグリッドが崩れて視覚リズムが壊れる。 + +**正解**：4/8/12/16/20/24/32/40/48/64 のみ。Chakraトークン使えば自然と従う。 + +## 中央寄せのテキスト羅列 + +**症状**：カード内のラベル+値が全部中央寄せ。 + +**問題**：行頭が不揃いで読みづらい。 + +**正解**：基本左寄せ。中央寄せはヒーロー・エラー画面・空状態の単発メッセージのみ。 + +## 二重ボーダー + +**症状**：ヘッダー下線 + その下のカード上枠線が重なる。 + +**問題**：太く見える。境界が二重で重い。 + +**正解**：どちらか1本にする。ヘッダー下線を消すか、カードの上枠を消す。 + +## 均質グリッド + +**症状**：ダッシュボードでKPIカード×6、すべて同じサイズ・同じ形。 + +**問題**：何が重要かわからない。情報階層が殺される。 + +**正解**：重要度で大小を変える（メインKPI大、サブKPI小、4+1+1のような配分）。 + +## "本当に？" 確認ダイアログ + +**症状**：「本当に削除しますか？」「OK / Cancel」。 + +**問題**：何が削除されて、何が起きるか曖昧。慣れたユーザーは反射でOK→事故。 + +**正解**：「シフト『2024-01-15 田中 昼番』を削除します。スタッフへの通知も取り消されます。 [キャンセル] [削除する]」 + +## 破壊的ボタンが Primary 配色 + +**症状**：削除確認の "削除" ボタンが青や teal。 + +**問題**：危険な操作と認識されない。 + +**正解**：`colorPalette="red"`、AlertDialog の右下に配置。 + +## 情報詰め込み（Miller's Law違反） + +**症状**：1画面に焦点が10+ある（カード、ボタン、グラフ、KPIすべて競合）。 + +**問題**：認知負荷が爆発、何も伝わらない。 + +**正解**：Miller's Law（7±2）。それ以上はカテゴリ化、タブ分割、サブページ化。 + +## "Loading..." と書くだけ + +**症状**：ページ中央に "Loading..." とだけ表示。 + +**問題**：レイアウトが揺れる、待ち時間が予測できない、SkeletonのほうがUX良い。 + +**正解**：Skeleton。書くなら「シフトを取得中…」など対象を書く。 + +## 100% width Modal on Desktop + +**症状**：デスクトップでも画面いっぱい広がるダイアログ。 + +**問題**：背景が見えなくて文脈喪失。"これは何？"状態。 + +**正解**：max-width 480〜640px、中央表示、背景が薄く見える。 + +## ホバー前提インタラクション + +**症状**：行アクションがhoverでしか出ない、メニューがhoverでしか開かない。 + +**問題**：モバイルでは hover がない。タップでも触れない。 + +**正解**：常時可視 or タップでも開く。モバイルファーストで考える。 + +## ラベルが ALL CAPS の長文 + +**症状**：「お客様情報の登録」を `text-transform: uppercase` で表示。 + +**問題**：日本語にuppercase無効、英数だけ大文字化されて読みづらい、scream tone。 + +**正解**：日本語はそのまま。英語の見出しでも通常ケース。 + +## ローディングと空の混同 + +**症状**：ロードが完了したかどうかわからない、空状態が常に出てる、Skeletonがいつまでも残る。 + +**問題**：「データがないのか、まだ読み込み中なのか」判断不能。 + +**正解**：状態ごとにレンダリング分岐（pages層で）：`isLoading` → Skeleton、`isError` → エラー、`empty` → Empty、`data` → コンテンツ。 + +## カードクリック内に複数ターゲット + +**症状**：カード全体クリッカブル、内側にネストした「お気に入り」「シェア」ボタン。 + +**問題**：イベント衝突、誤タップ、SR読み上げが混乱。 + +**正解**： +- カード全体クリッカブル → 内側にネストボタンを置かない（IconButton限定し`stopPropagation`） +- カード内ボタン中心 → カード自体はクリッカブルにしない + +## 日付形式が和暦・絶対・相対バラバラ + +**症状**：同じ画面で「2024年1月15日」「01/15」「3日前」「Mon」が並ぶ。 + +**問題**：何の日付か瞬時にわからない、揃わない。 + +**正解**： +- 同じ列・同じ意味は同じ形式 +- 一覧では絶対日付（YYYY-MM-DD or M月D日）+ 必要なら相対（"3日前"）併記 +- ツールチップで他形式を補完 + +## 装飾的なエモーティブイラスト + +**症状**：空状態に毎回イラスト、絵文字を多用。 + +**問題**：AI生成感、ブランドが定まっていない印象、本質を覆い隠す。 + +**正解**： +- 絵文字はブランドが既に使っているなら可、そうでないなら避ける +- 空状態のイラストは使うなら統一トーン + +## 過剰なアニメーション + +**症状**：すべての要素がフェードイン、ホバーで拡大、ページ遷移ごとにスライド。 + +**問題**：操作が遅く感じる、酔う、酔わなくても疲れる。 + +**正解**： +- 200ms 以内の機能的なアニメーションに留める +- 装飾アニメは1画面1つ +- `prefers-reduced-motion` に対応 + +## 下層ナビと上層ナビが同時固定 + +**症状**：上にヘッダー固定、下にBottomNav固定、コンテンツ領域がスマホで激狭。 + +**問題**：見える領域が小さく操作も窮屈。 + +**正解**： +- 上 or 下のどちらかに集約 +- 下ナビ重要なら上はスクロールで隠す（hide on scroll） +- ヘッダーは細く（48〜56px） + +## 必須・オプションの判別不能 + +**症状**：必須マーク無し、エラーで初めて気づく、または全部に「*」。 + +**問題**：入力前に把握できない。 + +**正解**： +- 必須が少数 → 必須に「*」 +- 任意が少数 → 任意に「（任意）」 +- どちらも凡例を上部に + +## 見出しが全部同じウェイト + +**症状**：H1〜H4 が全部 bold で size 違いだけ、または size も同じ。 + +**問題**：階層が伝わらない。 + +**正解**：sizeとweightで差を作る。H1=2xl/700、H2=lg/600、H3=md/600、Body=md/400。 + +## "戻る"がない・効かない + +**症状**：モーダル開いたら戻る方法が×だけ、ESC効かない、外側クリックで閉じない。 + +**問題**：閉じ方を学習する負担。 + +**正解**：×、ESC、外側クリック、すべてで閉じられるのが基本（破壊的編集中以外）。 + +## キャンセルが暗い灰色で disabled に見える + +**症状**：Secondaryボタンの背景がgray.200、文字がgray.500。 + +**問題**：押せると思われない。 + +**正解**：枠線あり/なしで区別、文字色は通常文字色、ホバーで意図明示。 diff --git a/.claude/skills/ui-architect/references/chakra-v3.md b/.claude/skills/ui-architect/references/chakra-v3.md new file mode 100644 index 00000000..77e5bbae --- /dev/null +++ b/.claude/skills/ui-architect/references/chakra-v3.md @@ -0,0 +1,310 @@ +# Chakra UI v3 + プロジェクト固有ラッパー マッピング + +`components.md` のカテゴリ → Chakra v3 / `src/components/ui/*` の具体実装。新規実装でゼロから作る前にここを必ず確認する。 + +## プロジェクト独自ラッパー（`src/components/ui/`） + +| ラッパー | 役割 | 主要API（簡易） | +|---|---|---| +| `Select` | カスタムSelect | `` | +| 長文 | `