@anthropologies/claudestory 0.1.55 → 0.1.57

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

@@ -2,6 +2,8 @@
 
 This file is referenced from SKILL.md when no `.story/` directory exists but project indicators are present. SKILL.md has already determined that setup is needed before routing here.
 
+**Skill command name:** When this file references `/story` in user-facing output, use the actual command that invoked you (e.g., `/story` for standalone install, `/story:go` for plugin install). Same for `/story auto` -- use `/story:go auto` if invoked as a plugin.
+
 **If arriving from Step 2b (scaffold detection):** The project already has an empty `.story/` scaffold but no tickets. Skip 1a and start at **1b. Existing Project -- Analyze**.
 
 ## Design Rules
@@ -568,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