@anthropologies/claudestory 0.1.56 → 0.1.57

package/README.md

@@ -2,6 +2,8 @@
 
 An agentic development framework. Track tickets, issues, and progress for your project in a `.story/` directory that AI tools read and write natively.
 
+**[claudestory.com](https://claudestory.com)** | **[Documentation](https://claudestory.com/cli)** | **[Privacy Policy](https://claudestory.com/privacy)**
+
 ## Installation
 
 ```bash
@@ -201,4 +203,4 @@ Everything else in `.story/` should be tracked.
 
 ## License
 
-MIT
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) -- free for personal and noncommercial use. For commercial licensing, contact shayegh@me.com.

package/dist/cli.js

@@ -2634,6 +2634,20 @@ function formatReference(commands, mcpTools, format) {
     lines.push(`- **${tool.name}**${params} \u2014 ${tool.description}`);
   }
   lines.push("");
+  lines.push("## /story design");
+  lines.push("");
+  lines.push("Evaluate frontend code against platform-specific design best practices.");
+  lines.push("");
+  lines.push("```");
+  lines.push("/story design                    # Auto-detect platform, evaluate frontend");
+  lines.push("/story design web                # Evaluate against web best practices");
+  lines.push("/story design ios                # Evaluate against iOS HIG");
+  lines.push("/story design macos              # Evaluate against macOS HIG");
+  lines.push("/story design android            # Evaluate against Material Design");
+  lines.push("```");
+  lines.push("");
+  lines.push("Creates issues automatically when claudestory MCP tools or CLI are available. Checks for existing design issues to avoid duplicates on repeated runs. Outputs markdown checklist as fallback when neither MCP nor CLI is available.");
+  lines.push("");
   lines.push("## Common Workflows");
   lines.push("");
   lines.push("### Session Start");
@@ -8358,7 +8372,7 @@ function getInstalledVersion() {
   }
 }
 function getRunningVersion() {
-  return "0.1.56";
+  return "0.1.57";
 }
 var init_version_check = __esm({
   "src/autonomous/version-check.ts"() {
@@ -10955,7 +10969,7 @@ var init_mcp = __esm({
     init_init();
     ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
     CONFIG_PATH2 = ".story/config.json";
-    version = "0.1.56";
+    version = "0.1.57";
     main().catch((err) => {
       process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
 `);
@@ -11559,6 +11573,7 @@ var init_reference = __esm({
 // src/cli/commands/setup-skill.ts
 var setup_skill_exports = {};
 __export(setup_skill_exports, {
+  copyDirRecursive: () => copyDirRecursive,
   handleSetupSkill: () => handleSetupSkill,
   registerPreCompactHook: () => registerPreCompactHook,
   registerSessionStartHook: () => registerSessionStartHook,
@@ -11566,7 +11581,7 @@ __export(setup_skill_exports, {
   removeHook: () => removeHook,
   resolveSkillSourceDir: () => resolveSkillSourceDir
 });
-import { mkdir as mkdir5, writeFile as writeFile3, readFile as readFile5, rm, rename as rename2, unlink as unlink3 } from "fs/promises";
+import { mkdir as mkdir5, writeFile as writeFile3, readFile as readFile5, readdir as readdir4, copyFile, rm, rename as rename2, unlink as unlink3 } from "fs/promises";
 import { existsSync as existsSync12 } from "fs";
 import { join as join21, dirname as dirname5 } from "path";
 import { homedir } from "os";
@@ -11587,6 +11602,43 @@ function resolveSkillSourceDir() {
   ${sourcePath}`
   );
 }
+async function copyDirRecursive(srcDir, destDir) {
+  const tmpDir = destDir + ".tmp";
+  const bakDir = destDir + ".bak";
+  if (!existsSync12(destDir) && existsSync12(bakDir)) {
+    await rename2(bakDir, destDir);
+  }
+  if (existsSync12(tmpDir)) await rm(tmpDir, { recursive: true, force: true });
+  if (existsSync12(bakDir)) await rm(bakDir, { recursive: true, force: true });
+  await mkdir5(tmpDir, { recursive: true });
+  const entries = await readdir4(srcDir, { withFileTypes: true, recursive: true });
+  const written = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const parent = entry.parentPath ?? entry.path ?? srcDir;
+    const relativePath = join21(parent, entry.name).slice(srcDir.length + 1);
+    const srcPath = join21(srcDir, relativePath);
+    const destPath = join21(tmpDir, relativePath);
+    await mkdir5(dirname5(destPath), { recursive: true });
+    await copyFile(srcPath, destPath);
+    written.push(relativePath);
+  }
+  if (existsSync12(destDir)) {
+    await rename2(destDir, bakDir);
+  }
+  try {
+    await rename2(tmpDir, destDir);
+  } catch (err) {
+    if (existsSync12(bakDir)) await rename2(bakDir, destDir).catch(() => {
+    });
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    });
+    throw err;
+  }
+  await rm(bakDir, { recursive: true, force: true }).catch(() => {
+  });
+  return written;
+}
 function isHookWithCommand(entry, command) {
   if (typeof entry !== "object" || entry === null) return false;
   const e = entry;
@@ -11772,6 +11824,19 @@ async function handleSetupSkill(options = {}) {
       missingFiles.push(filename);
     }
   }
+  const designSrcDir = join21(srcSkillDir, "design");
+  if (existsSync12(designSrcDir)) {
+    const designDestDir = join21(skillDir, "design");
+    try {
+      const designFiles = await copyDirRecursive(designSrcDir, designDestDir);
+      for (const f of designFiles) writtenFiles.push(`design/${f}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Warning: design skill copy failed: ${msg}
+`);
+      missingFiles.push("design/");
+    }
+  }
   log(`${existed ? "Updated" : "Installed"} /story skill at ${skillDir}/`);
   log(`  ${writtenFiles.join(" + ")} written`);
   if (missingFiles.length > 0) {
@@ -14386,7 +14451,7 @@ async function runCli() {
     registerSessionCommand: registerSessionCommand2,
     registerRepairCommand: registerRepairCommand2
   } = await Promise.resolve().then(() => (init_register(), register_exports));
-  const version2 = "0.1.56";
+  const version2 = "0.1.57";
   class HandledError extends Error {
     constructor() {
       super("HANDLED_ERROR");

package/dist/mcp.js

@@ -7816,7 +7816,7 @@ function getInstalledVersion() {
   }
 }
 function getRunningVersion() {
-  return "0.1.56";
+  return "0.1.57";
 }
 
 // src/autonomous/guide.ts
@@ -10087,7 +10087,7 @@ async function ensureGitignoreEntries(gitignorePath, entries) {
 // src/mcp/index.ts
 var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "0.1.56";
+var version = "0.1.57";
 function tryDiscoverRoot() {
   const envRoot = process.env[ENV_VAR2];
   if (envRoot) {

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@anthropologies/claudestory",
-  "version": "0.1.56",
+  "version": "0.1.57",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "An agentic development framework. Track tickets, issues, and progress for your project so every session builds on the last.",
+  "homepage": "https://claudestory.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AmirShayegh/ClaudeStory"
+  },
   "keywords": [
     "claudestory",
     "claude-code",

package/src/skill/SKILL.md

@@ -21,6 +21,8 @@ claudestory tracks tickets, issues, roadmap, and handovers in a `.story/` direct
 - `/story export` -> export project for sharing. Ask the user whether to export the current phase or the full project, then call `claudestory_export` with either `phase` or `all` set
 - `/story status` -> quick status check (call `claudestory_status` MCP tool)
 - `/story settings` -> manage project settings (see Settings section below)
+- `/story design` -> evaluate frontend design (read `design/design.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
+- `/story design <platform>` -> evaluate for specific platform: web, ios, macos, android (read `design/design.md` in the same directory as this skill file)
 - `/story help` -> show all capabilities (read `reference.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
 
 If the user's intent doesn't match any of these, use the full context load.
@@ -132,6 +134,7 @@ Example: "Rules: integer cents for money, billing engine is pure logic, TDD for
 Tip: You can also use these modes anytime:
   /story guided T-XXX   One ticket end-to-end with planning and code review
   /story review T-XXX   Review code you already wrote
+  /story design          Evaluate frontend against platform best practices
 ```
 
 Show this once or twice, then never again.
@@ -182,6 +185,8 @@ When working on a task and you encounter a bug, inconsistency, or improvement op
 
 When starting work on a ticket, update its status to `inprogress`. When done, update to `complete` in the same commit as the code change.
 
+**Frontend design guidance:** When working on UI or frontend tickets, read `design/design.md` in the same directory as this skill file for design principles and platform-specific best practices. Follow its priority order (clarity > hierarchy > platform correctness > accessibility > state completeness) and load the relevant platform reference. This applies to any ticket involving components, layouts, styling, or visual design.
+
 ## Managing Tickets and Issues
 
 Ticket and issue create/update operations are available via both CLI and MCP tools. Delete remains CLI-only.
@@ -361,3 +366,4 @@ Additional skill documentation, loaded on demand:
 - **`setup-flow.md`** -- Project detection and AI-Assisted Setup Flow (new project initialization)
 - **`autonomous-mode.md`** -- Autonomous mode, review, plan, and guided execution tiers
 - **`reference.md`** -- Full CLI command and MCP tool reference
+- **`design/design.md`** -- Frontend design evaluation and implementation guidance, with platform references in `design/references/`

package/src/skill/autonomous-mode.md

@@ -14,6 +14,8 @@ This file is referenced from SKILL.md for `/story auto`, `/story review`, `/stor
 4. The guide advances through: PICK_TICKET -> PLAN -> PLAN_REVIEW -> IMPLEMENT -> CODE_REVIEW -> FINALIZE -> COMPLETE -> loop
 5. Continue until the guide returns SESSION_END
 
+**Frontend design:** If the current ticket involves UI, frontend, components, layouts, or styling, read `design/design.md` in the same directory as the skill file for design principles. Load the relevant platform reference from `design/references/`. Apply the priority order (clarity > hierarchy > platform correctness > accessibility > state completeness) during both planning and implementation.
+
 **Critical rules for autonomous mode:**
 - Do NOT use Claude Code's plan mode -- write plans as markdown files
 - Do NOT ask the user for confirmation or approval

package/src/skill/design/design.md

@@ -0,0 +1,311 @@
+# Frontend Design -- Evaluation & Implementation Guide
+
+This file is referenced from SKILL.md for `/story design` commands and when working on UI tickets.
+
+**Skill command name:** When this file references `/story` in user-facing output, use the actual command that invoked you (e.g., `/story design` for standalone install, `/story:go design` for plugin install).
+
+## Evaluation Mode (/story design)
+
+When invoked via `/story design`:
+
+1. **Detect platform** from project code:
+   - package.json with react/next/vue/angular/svelte deps -> web
+   - .xcodeproj or SwiftUI imports -> macOS (check for iOS targets -> ios)
+   - build.gradle.kts + AndroidManifest.xml -> android
+   - pubspec.yaml -> flutter (ask which platform target)
+   - **Multi-platform**: If multiple platform indicators found, ask via AskUserQuestion which platform(s) to evaluate. Allow multiple passes. Scope scanning to the relevant app/package paths, not the whole repo.
+   - If no frontend code detected, tell the user and exit gracefully.
+
+2. **Accept platform override**: `/story design web`, `/story design ios`, `/story design macos`, `/story design android`.
+
+3. **Load platform reference**: Read `references/<platform>.md` in the same directory as this file. If not found, tell the user to run `claudestory setup-skill` to update skill files.
+
+4. **Check existing design issues**: Before creating new issues, list existing open issues with component "design" (via `claudestory_issue_list` MCP tool or `claudestory issue list --component design` CLI). Match findings against existing issues by title and location. Update existing issues instead of creating duplicates. Mark resolved issues when the underlying code no longer violates the rule.
+
+5. **Scan UI code**: Read component files, layout files, style files, routing. Evaluate against the principles in this file AND the loaded platform reference. Check: hierarchy, state completeness, accessibility, design system consistency, typography, color system, layout, motion, anti-patterns.
+
+6. **Output findings** (three-tier fallback):
+   - If claudestory MCP tools available: create/update issues via `claudestory_issue_create` and `claudestory_issue_update` (severity based on priority order, components: `["design", "<platform>"]`, location: file paths with line numbers)
+   - If MCP unavailable but claudestory CLI installed: use `claudestory issue create` and `claudestory issue update` via Bash
+   - If neither available: output markdown checklist grouped by severity
+
+7. **Present summary**: Show a table of findings grouped by severity (critical, high, medium, low), then use AskUserQuestion:
+   - question: "What would you like to do?"
+   - header: "Design"
+   - options:
+     - "Fix the most critical issue (Recommended)" -- start working on the highest-severity finding
+     - "See detailed rationale for a finding" -- explain why a specific finding matters
+     - "Done for now" -- return to normal session
+
+## Implementation Guidance Mode
+
+When working on UI tickets (not explicit `/story design` invocation), use the principles below and the relevant platform reference to guide implementation. Do not output the design reasoning unless the user explicitly asks for a design review or rationale. Go straight to high-quality implementation.
+
+---
+
+## Platform Routing
+
+After reading this file, also read the platform-specific reference for the target:
+
+- **Web** -> `references/web.md`
+- **macOS / Desktop** -> `references/macos.md`
+- **iOS** -> `references/ios.md`
+- **Android** -> `references/android.md`
+- **Flutter** -> ask which target platform(s), then read the corresponding reference(s): `references/ios.md` for iOS, `references/android.md` for Android, `references/web.md` for web
+- **React Native** -> read both `references/ios.md` and `references/android.md`
+
+If the platform is ambiguous, infer from context. Default to web only when the request is clearly browser or UI artifact oriented. If multi-platform, read all relevant references.
+
+## Stack Handling
+
+Implementation stacks are handled in this file. Platform-specific behavior is handled in references/*.md. Do not let cross-platform code-sharing override target platform fit.
+
+---
+
+## Prime Directive
+
+Clarity before flair.
+
+A user must quickly understand: where they are, what matters most, what they can do next, what changed, and what to do when something goes wrong.
+
+If the interface looks impressive but creates hesitation, confusion, or false affordances, it failed.
+
+---
+
+## Operating Mode
+
+Before designing, determine silently:
+
+- **Product goal** -- What problem is this interface solving?
+- **Primary user** -- Who is using it, and in what context?
+- **Main task** -- What is the single most important thing the user needs to accomplish here?
+- **Target platform** -- Web, macOS/desktop, iOS, Android, or multi-platform?
+- **Implementation stack** -- Native, React Native, Flutter, Web React/Next, or other?
+- **Content shape** -- Workflow-heavy, content-heavy, form-heavy, data-dense, utility-focused, or brand-heavy?
+- **Tone** -- What visual and emotional direction best fits the product? (restrained minimal, technical/instrumented, warm tactile, editorial, premium, playful, industrial, brutalist, retro-futurist, calm healthcare, sharp geometric, etc.)
+- **Signature idea** -- One memorable design move that gives the interface identity without reducing clarity, ergonomics, or performance.
+
+Do not output this reasoning unless the user explicitly asks for a design review or rationale. Go straight to high-quality implementation.
+
+---
+
+## Priority Order
+
+When principles conflict, obey this order:
+
+1. Clarity
+2. Hierarchy
+3. Platform correctness
+4. Accessibility
+5. State completeness
+6. System consistency
+7. Content-fit
+8. Visual distinction
+9. Motion and atmosphere
+10. Novelty
+
+A distinctive visual idea must be discarded if it harms comprehension, native behavior, accessibility, or maintainability.
+
+---
+
+## Core Design Principles
+
+### 1. Strong hierarchy
+
+Every screen must have a clear order of attention: primary action -> primary content -> supporting information -> secondary controls -> background/chrome.
+
+Use size, weight, spacing, contrast, color, grouping, and placement to make priority unmistakable. Avoid flat layouts where everything competes equally.
+
+### 2. Design systems, not one-off decoration
+
+Build with repeatable rules: spacing scale (e.g., 4/8/12/16/24/32/48/64), type scale with clear roles, color roles (not swatches), radius system, elevation/surface rules, border logic, interaction patterns, component states.
+
+Use tokens or CSS variables wherever possible. A screen that looks good once but cannot scale is not production-grade.
+
+### 3. Content-first composition
+
+Shape the UI around real tasks and real information, not fashionable patterns.
+
+Use realistic sample content that stress-tests the layout: long names and short names, empty lists and dense lists, real validation messages, realistic dates, statuses, tags, and actions. Never rely on fake-perfect placeholder content to make the design look cleaner than it is. No "Lorem ipsum," "John Doe," or "Acme Corp."
+
+### 4. Restraint
+
+Being distinctive does not mean adding more. One strong idea, executed precisely, beats ten decorative tricks.
+
+Bold maximalism is valid. Refined minimalism is valid. Both fail if they are vague, noisy, or shallow. Match implementation complexity to the aesthetic vision: maximalist designs need elaborate code with layered effects; minimal designs need surgical precision in spacing, type, and subtle detail.
+
+### 5. State completeness
+
+Never design only the happy path.
+
+For all meaningful screens and components, account for: default, hover/pressed/focused (where relevant), selected/active, disabled, loading/skeleton, empty, error (with real messages, not "Something went wrong"), success/confirmation, destructive action confirmation, offline/stale/retry (when relevant).
+
+At minimum, every meaningful interface must include: default, loading or skeleton, empty, and error.
+
+### 6. Accessibility is design quality
+
+Always include: sufficient contrast (4.5:1 body text, 3:1 large text/UI), visible focus states for keyboard navigation, semantic structure (headings, landmarks, labels), keyboard support where relevant, screen reader labeling where needed, touch targets >= 44pt on iOS / >= 48dp on Android, prefers-reduced-motion support, support for text scaling / Dynamic Type where relevant.
+
+---
+
+## Typography
+
+Typography must serve readability first, identity second.
+
+**The hybrid rule:** For native Apple platforms, use system fonts (San Francisco) for body text and dense data UI to maintain native feel and respect Dynamic Type. Reserve distinctive, characterful fonts for headings, hero sections, key metrics, and branded accents.
+
+For web, font choice should support tone, performance, and readability. Pair a distinctive display font with a refined body font. Contrast in style, harmony in tone.
+
+Define clear type roles and use them consistently: display, page title, section title, body, secondary/meta, label/button, caption.
+
+The problem is never "system font." The problem is generic thinking.
+
+## Color
+
+Build a semantic color system, not a mood board.
+
+Define roles: background, elevated surface, primary text, secondary text, accent, border/divider, success, warning, error, disabled, selection, focus.
+
+Dominant color + sharp accent outperforms timid, evenly distributed palettes. But the palette must serve the product, not just look attractive in isolation.
+
+Dark and light themes are both valid. Choose intentionally based on product context, not habit.
+
+## Layout and Spatial Composition
+
+Maintain a consistent spacing system. Group related controls and content clearly. Use whitespace intentionally -- generous space and controlled density are both valid. Allow density where the workflow benefits from it. Avoid empty spaciousness that wastes viewport.
+
+Use asymmetry, overlap, diagonal flow, or broken-grid composition only when it improves the concept and preserves clarity. Unexpected layout is welcome. Confusing layout is not.
+
+## Visual Direction
+
+Choose a specific aesthetic direction that fits the product, audience, and platform: restrained minimal, premium/luxury, editorial/magazine, technical/instrumented, calm healthcare, industrial/utilitarian, playful consumer, retro-futurist, warm tactile, sharp geometric, brutalist/raw, soft organic, maximalist chaos.
+
+Commit consistently across typography, spacing, surfaces, color, borders, iconography, shadow/elevation, motion, and illustration style.
+
+Do not default to the same visual recipe across unrelated products. Vary between light and dark, different fonts, different spatial logic, different atmospheric treatments. Never converge on the same recipe across generations.
+
+## Atmosphere and Surface Treatment
+
+Use visual atmosphere when it supports the concept: subtle gradient fields, noise/grain, layered translucency, geometric patterns, restrained glow, tactile or dramatic shadows, sharp or decorative borders, material surfaces, depth through contrast and layering, custom cursors on web.
+
+But: never apply glassmorphism by default, never use blur as a substitute for hierarchy, never add texture just to avoid simplicity, never make the background more interesting than the content. A clean surface is a valid aesthetic choice.
+
+## Components and Interaction
+
+Components should feel like part of one system, not isolated design exercises. Ensure consistency across: buttons, inputs, navigation, cards, lists, tables, tabs, sheets/modals, banners, alerts, tooltips, menus, progress/loading states.
+
+Affordances must be obvious. Feedback must be timely. States must be visually distinct.
+
+## Motion and Feedback
+
+Good uses: staged content reveal with staggered animation-delay, page/screen transitions, expanding detail panels, feedback on action completion, preserving continuity between states, subtle hover/press/tap response, scroll-triggered reveals on web.
+
+Avoid: looping ambient motion that distracts, theatrical transitions in utility workflows, motion that slows down repeated actions, decorative animation without meaning.
+
+One well-orchestrated page entrance with staggered reveals creates more delight than scattered micro-interactions everywhere. Always respect prefers-reduced-motion.
+
+---
+
+## Anti-Patterns
+
+Avoid generic AI UI failure modes:
+
+- trendy gradients with no product fit
+- flat hierarchy where everything competes equally
+- oversized rounded cards everywhere
+- meaningless glassmorphism or blur effects
+- random pills and badges on everything
+- dashboards that look rich but hide the task
+- decorative charts with fake data
+- overly spacious desktop layouts / shrunk desktop UI on iPhone
+- overdesigned empty states that steal focus from recovery actions
+- a perfect default state with no loading/error/empty coverage
+- placeholder content chosen only because it looks neat
+- forcing quirky typography into dense utility interfaces
+- using the same visual recipe for every product
+- cookie-cutter component patterns with no context-specific character
+
+The failure is not a font, color, or style by itself. The failure is defaulting instead of designing.
+
+---
+
+## Implementation Environment
+
+### React / JSX (.jsx)
+- Single-file component with default export, no required props
+- Tailwind core utility classes for styling (no compiler -- only pre-defined classes)
+- Available: React hooks, lucide-react@0.383.0, recharts, d3, Three.js (r128), lodash, mathjs, Plotly, shadcn/ui, Chart.js, Tone, Papaparse, SheetJS, mammoth, tensorflow
+- Import external fonts via `<style>` block with `@import url()` from Google Fonts
+- No localStorage or sessionStorage -- use React state
+- Motion library for animation when it materially improves the result
+
+### HTML (.html)
+- Single self-contained file: HTML + CSS + JS
+- Load fonts from Google Fonts via `<link>`, libraries from cdnjs.cloudflare.com
+- CSS-only animations preferred
+- Keep JS focused on interaction, not decoration
+
+### SwiftUI / UIKit (iOS, macOS)
+- Use SwiftUI as default for new UI; UIKit when required for specific controls or legacy integration
+- Respect platform navigation patterns (NavigationStack, TabView, sheets)
+- Use system typography (SF Pro) for body and data UI; custom fonts for headings and brand moments
+- Support Dynamic Type via system text styles or custom styles that scale
+- Use semantic system colors or a custom semantic palette that supports light/dark/high-contrast
+- Prefer native controls -- do not rebuild standard components unless the product demands it
+- Use `withAnimation` and spring-based timing for transitions
+- Mark interactive elements with proper accessibility labels, traits, and hints
+
+### Jetpack Compose (Android)
+- Use Material 3 theming as the structural baseline (color scheme, typography, shapes)
+- Build with `Modifier` chains for layout, spacing, semantics, and interaction
+- Hoist state for reusable and testable composables
+- Use `WindowSizeClass` for adaptive layout decisions across phones, tablets, foldables
+- Use `sp` for text (respects accessibility scaling), `dp` for spacing and sizing
+- Support dark theme via `MaterialTheme` color scheme switching
+- Apply `semantics` modifier for TalkBack / screen reader labeling
+- Use Material motion patterns (container transform, shared axis) for navigation transitions
+
+### React Native
+- Share product structure across platforms, but allow platform-specific refinements
+- Use `Platform.select` or platform-specific files where controls, spacing, navigation, or feedback should differ
+- Respect native interaction patterns: iOS springs and haptics, Android ripple and system back
+- Use native modules or native surfaces when product quality demands them
+- Do not design one mobile UI and skin it twice -- the app should feel at home on each OS
+- Test on both platforms; do not assume iOS behavior works on Android or vice versa
+
+### Flutter
+- Use Material 3 theming as the baseline; apply Cupertino or platform-adaptive controls where they materially improve platform fit
+- Build adaptive layouts using `LayoutBuilder`, `MediaQuery`, or window size breakpoints
+- Use platform-appropriate navigation, feedback, density, and control treatment
+- Support phones, tablets, desktop windows, and web surfaces when relevant
+- One product system with target-aware variations -- shared code is fine, shared UX must be intentional
+- Do not use Flutter as an excuse to ignore platform conventions
+
+### Shared rules
+- Use design tokens or semantic theme values appropriate to the stack
+- Realistic sample content that stress-tests the layout
+- At minimum: default state, one loading or empty state, and basic error handling
+- Self-contained and immediately functional on render
+
+---
+
+## Output Standards
+
+Unless the user explicitly asks for a design critique or rationale first, go straight to implementation. Do not output a design brief, component inventory, or process summary unless asked.
+
+Produce code that is: production-grade, accessible, platform-appropriate, organized, realistic, visually polished without becoming fragile, state-aware, free of placeholder nonsense.
+
+For web: semantic HTML, focus states, contrast, ARIA where needed.
+For native: accessibility labels, traits/semantics, focus/navigation behavior, platform-appropriate text scaling and interaction feedback.
+
+Include: reusable tokens/CSS variables, spacing and type scales, key state variants, realistic sample content, semantic structure, focus states and keyboard support where relevant.
+
+Do not generate dead ornamental markup.
+
+---
+
+## Final Standard
+
+The result should feel like a strong product designer led it, a design system supports it, a real team could ship it, users would understand it quickly, the visual identity is specific and intentional, the platform was respected, and the interface is memorable without trying too hard.
+
+Have taste. Have restraint. Have a point of view. Earn it through clarity.

package/src/skill/design/references/android.md

@@ -0,0 +1,132 @@
+# Android Platform Reference
+
+Read this alongside the core design.md when building Android native apps (Jetpack Compose/XML), React Native for Android, Flutter for Android, or any interface targeting Android phones, tablets, and foldables.
+
+---
+
+## Android Interaction Model
+
+Android is a touch-first platform with a broader hardware spectrum than iOS -- varying screen sizes, densities, aspect ratios, foldable states, and manufacturer customizations. Design must be adaptive, not fixed.
+
+Design for:
+- Touch-first interaction with Android-native feedback patterns (ripple, state overlays)
+- System back behavior as a first-class navigation rule -- predictive back gesture on Android 14+
+- Adaptive layouts that respond to actual window size, not just device type
+- Edge-to-edge rendering that properly respects system bars and insets
+- Touch targets >= 48dp for all interactive elements
+- Variable screen densities (mdpi through xxxhdpi)
+
+## Navigation Patterns
+
+Android navigation differs meaningfully from iOS. Do not port iOS patterns directly.
+
+- **Bottom navigation**: For 3-5 top-level destinations. Persistent, with clear active state. Equivalent to iOS tab bar but follows Material conventions.
+- **Navigation rail**: For tablets, foldables, and large-window layouts. Vertical strip on the leading edge -- replaces bottom nav at wider breakpoints.
+- **Navigation drawer**: For apps with many top-level sections or infrequent navigation. Can be modal or persistent depending on screen width.
+- **Top app bar**: Title, navigation icon, and actions. Scrolling behavior (lift on scroll, collapse) should match content type.
+- **System back**: Must work correctly everywhere. Back should dismiss sheets, close dialogs, pop navigation, and ultimately exit the app. Never trap the user.
+- **Predictive back**: On Android 14+, users can preview the back destination with a swipe gesture. Ensure back targets are correct and meaningful.
+
+Do not use iOS-style swipe-from-left-edge as the primary back mechanism. Android users rely on the system back gesture or button.
+
+## Adaptive Layout
+
+Android runs on phones, tablets, foldables, Chromebooks, and desktop-mode windows. Layout must adapt.
+
+- **Compact width** (<600dp): Single-column, bottom navigation, focused flows
+- **Medium width** (600-840dp): List-detail side-by-side, navigation rail, two-column content
+- **Expanded width** (840dp+): Three-pane layouts, persistent navigation, dense information display
+
+Use window size classes, not device type, to drive layout decisions. A foldable in half-open posture and a small tablet may share the same layout.
+
+Content should reflow smoothly -- not snap between discrete phone and tablet layouts.
+
+## Material Design Baseline
+
+Material Design is the native design language for Android. Use it as the structural baseline.
+
+- **Surfaces and elevation**: Material uses tonal elevation (surface color shifts) rather than drop shadows as the primary depth cue. Understand the surface hierarchy.
+- **Color system**: Material 3 uses dynamic color derived from a source color. Define primary, secondary, tertiary, error, surface, and on-surface roles. Support Material You dynamic theming where appropriate.
+- **Shape**: Material 3 uses a shape scale (none, extra-small, small, medium, large, extra-large, full). Apply consistently to containers, buttons, chips, cards.
+- **Typography**: Material 3 type scale -- display, headline, title, body, label. Map these to your content roles.
+
+You can customize Material heavily -- the point is not to look like stock Material, but to use its structural logic (color roles, elevation model, shape system, type scale) as the foundation.
+
+## Typography for Android
+
+- System sans-serif (Roboto on most devices) is the safe native baseline for body text and dense data UI.
+- Custom brand typography is valid and encouraged for headings, hero sections, and branded moments -- provided readability and density remain strong.
+- Support text scaling -- users can set system font size from small to very large. Test at 200% and ensure layouts don't break.
+- Minimum body text: 14sp. Labels and captions: 12sp. Use sp (scale-independent pixels) to respect user preferences.
+- Do not use fixed dp for text sizes -- this ignores accessibility scaling.
+
+## Color and Theming
+
+- Support both light and dark themes -- test both thoroughly
+- Use Material color roles semantically: primary for key actions, secondary for less prominent elements, surface for containers, error for problems
+- Support **Material You** dynamic color where it adds value (user wallpaper-derived palette)
+- Ensure contrast ratios meet WCAG guidelines in both themes
+- Do not rely on color alone -- pair with icons, text labels, or shape changes
+
+## States and Feedback
+
+Android has its own feedback language. Respect it.
+
+- **Ripple effect**: The standard touch feedback. Apply to all tappable surfaces. Do not replace with iOS-style opacity changes.
+- **State overlays**: Hovered, focused, pressed, dragged states use semi-transparent overlays on the surface color. Material defines specific opacity values for each.
+- **Snackbars**: For lightweight, transient feedback ("Message sent", "Item deleted" with undo). Appear at the bottom, auto-dismiss.
+- **Loading**: Progress indicators (linear or circular) with context. Skeleton screens for content loading. Pull-to-refresh for list content.
+- **Empty states**: Clear illustration or icon + explanation + primary action
+- **Error states**: Inline for form fields, banners for page-level errors, snackbar for transient failures with retry
+
+## Android-Specific Motion
+
+- Use Material motion principles: container transforms, shared axis, fade through, fade
+- **Container transform**: An element expands into its detail view -- maintains spatial continuity
+- **Shared axis**: Forward/backward, up/down transitions for navigation within a hierarchy
+- **Fade through**: For transitions between unrelated content
+- Respect `Settings > Accessibility > Remove animations` -- provide instant fallbacks
+- Keep transitions under 300ms for utility flows
+- Spring physics are acceptable but less idiomatic than Material easing curves
+
+## Forms on Android
+
+- Use appropriate `inputType` for each field (text, number, email, phone, password)
+- Autofill hints via `autofillHints` for common fields
+- Material text fields: outlined or filled variants with clear label, helper text, error text, character counter
+- Validation: inline, specific messages, shown on focus loss or submit attempt
+- Keyboard should not obscure the active field -- manage `windowSoftInputMode` or scroll behavior
+- Use dropdowns, date pickers, and time pickers where appropriate instead of free text
+
+## Foldable and Large Screen Considerations
+
+- Test on foldable emulators (fold/unfold transitions, tabletop posture, book posture)
+- Content should not be lost or hidden during fold state changes
+- Use the hinge area intentionally -- do not place interactive elements across it
+- In tabletop posture (half-folded): consider split layout with content above and controls below the fold
+- Support multi-window and picture-in-picture where appropriate
+
+## Jetpack Compose Notes
+
+When implementing with Compose:
+
+- Use `Modifier` chains intentionally for layout, spacing, semantics, and interaction
+- Hoist state for reusable and testable composables
+- Use `Material3` theme and components as the baseline
+- Prefer `WindowSizeClass` for adaptive layout decisions
+- Use `semantics` modifier for accessibility labeling
+- Support dark theme via `MaterialTheme` color scheme switching
+- Test with font scale, display size, and TalkBack
+
+## Android Anti-Patterns
+
+- iOS navigation patterns (swipe-from-edge back, bottom sheets as primary navigation)
+- iOS-style toggle switches and segmented controls without adaptation
+- Ignoring system back behavior or trapping the user
+- Fixed layouts that break on non-standard aspect ratios or foldables
+- Ripple-free tap targets (feels broken on Android)
+- Snackbar-less error handling (overusing dialogs for transient messages)
+- Ignoring Material elevation and surface model (everything flat or everything shadowed)
+- One rigid phone layout that doesn't adapt to tablet or foldable
+- Text in dp instead of sp, breaking accessibility scaling
+- Testing only on Pixel -- Samsung, OnePlus, and others have meaningful differences

package/src/skill/design/references/ios.md

@@ -0,0 +1,132 @@
+# iOS Platform Reference
+
+Read this alongside the core design.md when building iOS native apps (SwiftUI/UIKit), React Native for iOS, or any interface targeting iPhone and iPad.
+
+---
+
+## iOS Interaction Model
+
+iOS is a touch-first, single-focus platform. Users interact with thumbs on a handheld device in variable contexts -- walking, one-handed, distracted.
+
+Design for:
+- Touch-first interaction -- no hover states as primary affordance
+- Thumb-reach ergonomics -- primary actions in the bottom third of the screen
+- Single-task focus -- one primary action per screen, not competing panels
+- Motion and transitions that maintain spatial orientation
+- Concise flows -- minimize steps, maximize clarity per step
+- Gesture restraint -- only use gestures that are obvious and discoverable
+
+## Navigation Patterns
+
+iOS has strong navigation conventions. Respect them.
+
+- **Navigation stack** (push/pop): For hierarchical drill-down. Title in nav bar, back button preserves context. This is the primary pattern.
+- **Tab bar**: For top-level app sections (2-5 tabs). Persistent at bottom, always accessible.
+- **Sheets and modals**: For focused sub-tasks, creation flows, or settings. Half-sheet for quick actions, full sheet for complex tasks.
+- **Segmented controls**: For switching views within a single context (e.g., list/grid, day/week/month).
+- **Action sheets**: For contextual choices triggered by user action.
+- **Swipe actions**: For list item operations (delete, archive, pin). Use sparingly and for common actions only.
+
+Do not invent custom navigation paradigms when standard patterns work. Users have strong muscle memory for iOS navigation.
+
+## Safe Areas and Layout
+
+- Respect safe area insets on all edges (status bar, home indicator, notch/Dynamic Island)
+- Content should not hide behind system UI
+- Scrollable content should extend edge-to-edge behind the nav bar and tab bar with proper insets
+- Landscape orientation: adjust layout for wide-and-short viewport if supported
+- iPad: consider split view, sidebar, and adaptive layout for larger canvas
+
+## Touch Targets
+
+- Minimum 44x44pt tap targets for all interactive elements
+- Adequate spacing between adjacent tap targets to prevent mis-taps
+- Primary actions should be large, obvious, and reachable by thumb
+- Destructive actions should require deliberate targeting -- not placed where accidental taps happen
+
+## Thumb Zone Ergonomics
+
+On iPhone, design with the thumb-reach heat map in mind:
+
+- **Easy reach** (bottom center): Place primary actions, main navigation, frequently used controls
+- **Moderate reach** (middle of screen): Content display, lists, secondary actions
+- **Hard reach** (top corners): Search, settings, infrequent actions -- or use pull-down gestures to make them accessible
+
+Tab bars, bottom toolbars, and floating action areas take advantage of easy reach. Top nav bars are standard but should not house primary repeated actions.
+
+## Typography for iOS
+
+- **SF Pro** (system font) is the correct choice for body text, labels, list content, and dense data UI on iOS. It respects Dynamic Type scaling, integrates with system accessibility, and matches platform expectations.
+- Reserve custom/characterful fonts for headings, hero sections, onboarding, branding moments, and marketing surfaces.
+- Support **Dynamic Type** -- text should scale with the user's system text size preference. Use system text styles (`.body`, `.headline`, `.caption`, etc.) or custom styles that scale proportionally.
+- Do not use fixed font sizes that ignore accessibility scaling.
+- Minimum body text size: 17pt (system body default). Metadata and captions can go to 13pt.
+
+## Color and Appearance
+
+- Support both light and dark mode using semantic system colors or a custom semantic palette
+- Use high contrast between text and backgrounds (system colors handle this well)
+- Tint colors should have a clear accent role -- not spread across every surface
+- Respect the `UIAccessibility` increased contrast setting
+- Avoid relying on color alone to convey meaning -- pair with icons, labels, or shape
+
+## States and Feedback
+
+iOS users expect immediate, tactile feedback:
+
+- **Tap feedback**: Highlight state on press, subtle scale or opacity change
+- **Haptics**: Use for meaningful moments -- successful action, toggle, destructive confirmation, selection change. Not for every tap.
+- **Loading**: Skeleton screens or activity indicators with context ("Loading your messages" not just a spinner)
+- **Empty states**: Clear explanation + primary action to resolve ("No conversations yet -- Start a new chat")
+- **Error states**: Specific message + recovery action, not generic alerts
+- **Pull-to-refresh**: Standard pattern for list content where data can be stale
+- **Swipe-to-delete**: With confirmation for destructive actions
+
+## iOS-Specific Motion
+
+- Use **spring animations** for transitions -- iOS motion feels physical, not eased
+- Navigation pushes and pops should feel like spatial movement
+- Sheet presentation: slide up from bottom with spring settle
+- Dismiss: swipe down gesture with velocity-based completion
+- Content transitions: crossfade for in-place changes, slide for spatial changes
+- Respect `UIAccessibility.isReduceMotionEnabled` -- provide instant transitions as fallback
+
+Avoid:
+- Web-style fade-in-from-nothing animations
+- Excessive parallax
+- Decorative motion on utility screens
+- Animations that delay task completion
+
+## Forms on iOS
+
+- Use appropriate keyboard types for each field (email, number, phone, URL)
+- Use `textContentType` hints for autofill (name, email, password, address)
+- Inline validation -- mark fields as invalid with specific messages
+- Respect the keyboard safe area -- content should scroll or adjust to remain visible above the keyboard
+- Group related fields into logical sections
+- Use pickers, date pickers, and segmented controls where appropriate instead of free-text input
+
+## iPad Considerations
+
+When targeting iPad as well:
+
+- Support multitasking (Split View, Slide Over) where appropriate
+- Use sidebar navigation on iPad (collapsible, adapts to compact width)
+- Two-column or three-column layouts for master-detail patterns
+- Support pointer/trackpad interaction (hover states, right-click menus)
+- Keyboard shortcut support for productivity workflows
+- Adapt layout for regular and compact size classes
+
+## iOS Anti-Patterns
+
+- Desktop-density layouts crammed onto a 390pt-wide screen
+- Custom navigation that fights the back gesture
+- Tab bars with more than 5 items
+- Primary actions placed in hard-to-reach top corners
+- Text that doesn't scale with Dynamic Type
+- Alerts and modals for every error instead of inline feedback
+- Hamburger menus hiding primary navigation
+- Gesture-only interactions with no visible affordance
+- Ignoring the home indicator safe area
+- Fixed font sizes that break at larger accessibility sizes
+- Loading states with no contextual information

package/src/skill/design/references/macos.md

@@ -0,0 +1,109 @@
+# macOS / Desktop Platform Reference
+
+Read this alongside the core design.md when building macOS native apps, Electron/Tauri desktop apps, or any interface intended for keyboard-and-pointer desktop use.
+
+---
+
+## Desktop Interaction Model
+
+Desktop users operate with a keyboard, mouse/trackpad, and large viewport. They expect precision, density, and simultaneous context.
+
+Design for:
+- Denser information display -- desktop users expect more content per screen
+- Multi-pane layouts (sidebar + content + inspector where appropriate)
+- Resizable, adaptable windows that reflow content intelligently
+- Keyboard-first usage (shortcuts, tab order, arrow-key navigation within lists/tables)
+- Hover precision (tooltips, hover states, right-click/context menus)
+- Drag and drop where it serves the workflow (files, list reordering, canvas objects)
+
+Desktop users tolerate and often expect more density and more direct control than mobile users.
+
+## Layout Patterns
+
+Desktop excels at showing multiple panels of related information simultaneously.
+
+Common effective patterns:
+- **Sidebar + content** -- navigation or filtering on the left, main content area
+- **Sidebar + content + inspector** -- three-pane with detail panel (e.g., mail, Xcode, Finder column view)
+- **Toolbar + canvas** -- creative/productivity apps with tools above a workspace
+- **Source list + detail** -- master-detail for collections
+- **Tab-based workspaces** -- for multi-document or multi-context workflows
+
+Window resizing should degrade gracefully: inspector can collapse, sidebar can become compact icons, content can reflow.
+
+Do not waste desktop space with oversized cards, giant padding, or mobile-like stacking unless the product explicitly calls for it.
+
+## Keyboard and Shortcuts
+
+Desktop interfaces must be navigable without a mouse.
+
+- Tab moves between focusable elements in logical order
+- Arrow keys navigate within lists, tables, menus, tab groups
+- Enter/Return confirms, Escape cancels/dismisses
+- Common shortcuts (Cmd+S, Cmd+Z, Cmd+F, Cmd+N) should work where semantically appropriate
+- Display keyboard shortcuts in menus and tooltips where relevant
+- Focus states must be clearly visible
+
+For native macOS: respect the system menu bar, Cmd+Q, Cmd+W, Cmd+comma for preferences.
+
+## Information Density
+
+Desktop gives you viewport. Use it.
+
+- Rows in tables can be compact (28-36px height)
+- Lists can show metadata inline rather than requiring drill-down
+- Sidebars can display tree structures and nested navigation
+- Multi-column layouts are expected, not unusual
+- Secondary information can coexist with primary content rather than hiding behind tabs or disclosure
+
+Dense does not mean cluttered. Group related information, maintain consistent spacing, and use borders or subtle surface differences to separate regions.
+
+## Context Menus and Direct Manipulation
+
+- Right-click / context menu on actionable items (files, list rows, selections)
+- Drag and drop for reordering, moving between panes, and file operations
+- Double-click to open/edit where semantically appropriate
+- Multi-select with Cmd+click and Shift+click in lists and tables
+- Inline editing where it reduces friction (rename, quick value changes)
+
+## Typography for Desktop
+
+- For native macOS: SF Pro is often the correct choice for body text, labels, and dense data UI. It integrates with system rendering, supports Dynamic Type, and matches platform expectations.
+- Reserve custom/characterful fonts for headings, branding, hero sections, or marketing surfaces within the app.
+- Dense UI text can go smaller than mobile (13px body is comfortable on desktop, 11-12px for metadata).
+- Use font weight variation (regular, medium, semibold) to create hierarchy within dense layouts rather than relying solely on size changes.
+
+## Desktop-Specific Motion
+
+- Sidebar reveal/collapse with smooth transitions
+- Panel resize animations
+- List item reorder with spring physics
+- Sheet/dialog presentation with subtle scale or slide
+- Avoid heavy page-level transitions -- desktop navigation should feel instant
+- Respect system `prefers-reduced-motion`
+
+For native macOS: use spring-style animation curves that match system behavior. Avoid web-style easing functions that feel foreign on the platform.
+
+## macOS Native Considerations
+
+When building for macOS specifically:
+
+- Respect the traffic light window controls (close/minimize/fullscreen)
+- Support full-screen mode gracefully
+- Toolbar items should be appropriately sized and spaced for mouse precision
+- Preferences/Settings should use the standard Cmd+comma shortcut
+- Menu bar integration where appropriate
+- NSToolbar patterns for native toolbar behavior
+- Sidebar selection states should match system conventions (highlight color, rounded selection)
+- Vibrancy and translucency are valid atmospheric tools on macOS -- use sparingly and purposefully
+
+## Desktop Anti-Patterns
+
+- Mobile-width content centered in a wide window with empty gutters
+- Oversized touch-target buttons that waste space
+- Single-column layouts that ignore available horizontal space
+- Navigation patterns that require many clicks to access parallel information
+- Hiding commonly-used actions behind hamburger menus
+- Ignoring keyboard navigation entirely
+- Modals that block all other interaction when a panel or inspector would serve better
+- Toast notifications that stack up and obscure content

package/src/skill/design/references/web.md

@@ -0,0 +1,104 @@
+# Web Platform Reference
+
+Read this alongside the core design.md when building web apps, websites, landing pages, dashboards, or any browser-rendered interface.
+
+---
+
+## Web Interaction Model
+
+Web is the most flexible platform. That flexibility must still feel intentional.
+
+Design for:
+- Responsive layout across breakpoints (mobile-first or desktop-first, but tested at both extremes)
+- Semantic HTML (`<nav>`, `<main>`, `<section>`, `<article>`, proper heading hierarchy)
+- Clear link vs. button distinction (links navigate, buttons act)
+- Keyboard navigation and focus management
+- Screen reader compatibility via semantic structure and ARIA where needed
+- Efficient loading and progressive rendering
+
+## Layout and Responsiveness
+
+Web layouts must adapt gracefully across viewport sizes.
+
+- Use flexible grids and content reflow -- not just stacking at breakpoints
+- Define at least 3 breakpoints: compact (~375-640px), medium (~641-1024px), wide (~1025px+)
+- Content should remain readable and scannable at every width
+- Navigation should collapse or adapt rather than disappear
+- Avoid horizontal scroll on content unless it serves a specific UX pattern (e.g., carousel, data table)
+
+Do not make the web feel like a blown-up phone app. Desktop web should use horizontal space purposefully -- multi-column content, sidebars, split views where appropriate.
+
+## Scroll Rhythm and Reading Flow
+
+Web is a scrolling medium. Use that well.
+
+- Structure content into clear visual sections with distinct rhythm
+- Use scroll-triggered reveals and staggered entrances for editorial or marketing pages
+- Keep utility/app-shell pages focused -- not everything needs scroll animation
+- Anchor navigation or sticky headers for long-form content
+- Manage scroll position on navigation and state changes
+
+## Forms and Validation
+
+Forms are one of the most common web patterns and one of the most neglected by AI-generated UI.
+
+- Inline validation with specific, helpful error messages
+- Clear visual distinction between valid, invalid, focused, and disabled states
+- Logical tab order
+- Submit button states: default, loading/submitting, disabled, success
+- Accessible labels -- never rely on placeholder text alone as label
+- Group related fields logically
+- Support for keyboard submission (Enter key)
+
+## Browser Behavior
+
+Respect the browser as a platform:
+- URLs should be meaningful and shareable where applicable
+- Back/forward navigation should work predictably
+- Opening in new tab should work for links
+- Loading states should account for network latency
+- Error states should offer recovery, not dead ends
+- Favor progressive enhancement -- core functionality should survive missing JS where possible
+
+## Web Visual Freedom
+
+Web has creative latitude that native platforms constrain. Use it.
+
+Web is well-suited for:
+- Rich page composition and editorial storytelling
+- Scroll-triggered structure and parallax (when purposeful)
+- Custom cursors and hover effects
+- Experimental typography and layout
+- Full-bleed hero sections and atmospheric backgrounds
+- Dashboard shells with flexible panel arrangements
+- Marketing-to-app transitions on landing pages
+
+This freedom does not override the priority order in design.md. Clarity and hierarchy still come first.
+
+## Web-Specific Motion
+
+- CSS transitions and animations preferred for performance
+- Use Motion library for React when orchestration complexity justifies it
+- Intersection Observer for scroll-triggered reveals
+- Hover states should provide meaningful feedback, not just decoration
+- Page transitions: keep fast for utility, allow cinematic for editorial/marketing
+- Always include `prefers-reduced-motion` fallback
+
+## Web Typography
+
+- Import fonts from Google Fonts via `<link>` or `@import`
+- Choose fonts that balance character with web performance (WOFF2, font-display: swap)
+- Body text should be highly readable at all viewport sizes (16px minimum on mobile)
+- Use clamp() or responsive type scales for fluid sizing
+- Pair a distinctive display font with a refined, readable body font
+- Do not default to the same web font every time -- the font should fit the product's tone
+
+## Web Anti-Patterns
+
+- Single-column phone-width layouts filling a 1440px screen
+- Hover-only interactions with no touch/keyboard fallback
+- Infinite scroll with no way to reach footer content
+- Forms with no validation states
+- Links that look like buttons and buttons that look like links
+- Loading an entire SPA shell before showing any content
+- Full-page overlays that break browser navigation

package/src/skill/reference.md

@@ -328,6 +328,20 @@ claudestory setup-skill
 - **claudestory_lesson_reinforce** (id) — Reinforce lesson — increment count and update lastValidated
 - **claudestory_selftest** — Integration smoke test — create/update/delete cycle
 
+## /story design
+
+Evaluate frontend code against platform-specific design best practices.
+
+```
+/story design                    # Auto-detect platform, evaluate frontend
+/story design web                # Evaluate against web best practices
+/story design ios                # Evaluate against iOS HIG
+/story design macos              # Evaluate against macOS HIG
+/story design android            # Evaluate against Material Design
+```
+
+Creates issues automatically when claudestory MCP tools or CLI are available. Checks for existing design issues to avoid duplicates on repeated runs. Outputs markdown checklist as fallback when neither MCP nor CLI is available.
+
 ## Common Workflows
 
 ### Session Start

package/src/skill/setup-flow.md

@@ -570,6 +570,12 @@ Present a brief completion message and tell the user how to start:
 
 Keep it to 2-3 sentences. The system teaches itself through use -- `/story` loads context, shows status, and suggests next work. No need for a manual.
 
+**Design evaluation hint** (show only when project surface is Web app, Mobile app, or Desktop app):
+
+Add one more line after the completion message: "Tip: Run `/story design` anytime to evaluate your frontend against [detected platform] best practices and generate improvement issues."
+
+Note: Use the actual command that invoked this flow (e.g., `/story design` for standalone, `/story:go design` for plugin).
+
 ---
 
 ## Appendix: Default Stack Recommendations