@anthropologies/claudestory 0.1.56 → 0.1.58

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