AI Skill Report Card
Generating Smart Prototypes
Quick Start14 / 15
Two entry modes. Detect which one applies before doing anything else:
Mode A — Replication (reference zip/design provided, "make it look/work like this"): Skip PRD discussion. Extract patterns → pick framework → generate. Ask at most 1-2 clarifying questions only if framework or target platform is ambiguous.
Mode B — New Build (no reference, describing an app idea from scratch): Run a short PRD alignment pass first (see Workflow) before generating anything.
User: "Here's a zip of a prototype, rebuild the onboarding flow in React Native"
→ Mode A. Unzip, analyze component tree + interactions, confirm framework = React Native,
generate directly. No PRD questions.
User: "I want to build a habit tracker app"
→ Mode B. Ask 3-5 PRD questions (users, core flows, platform, must-have features), then generate.
Recommendation▾
Add a concrete before/after example showing actual generated code snippet or file tree output, not just process description
Workflow15 / 15
Mode A: Replication Pattern (standardized, low-question)
Progress:
- [ ] Unzip/inspect reference asset(s)
- [ ] Extract design tokens (colors, spacing, typography, radii, shadows)
- [ ] Map component hierarchy (screens → layouts → components → primitives)
- [ ] Identify state management pattern used (hooks/context/redux/provider/bloc/riverpod)
- [ ] Catalog interactions & animation timings (easing, durations, triggers)
- [ ] Confirm target framework (ask only if not stated or inferable from zip)
- [ ] Scaffold project with framework's standard structure
- [ ] Implement screens in priority order: nav shell → primary flow → secondary screens
- [ ] Wire up interactivity (all buttons/inputs/nav functional, no dead ends)
- [ ] Apply responsive breakpoints
- [ ] Run accessibility pass (WCAG 2.1 AA)
- [ ] Run testing protocol (see below)
- [ ] Package deliverable + README with run instructions
Extraction rules when analyzing a reference zip:
- If it's a React/RN project: read
package.jsonfor stack fingerprint, scansrc/componentsfor hierarchy, grep foruseState/useReducer/Context.Provider/zustand/reduxto identify state pattern, grep fortransition/animate/Animated/framer-motion/durationfor animation specs. - If it's Flutter: read
pubspec.yaml, scanlib/widgetsandlib/screens, grep forStatefulWidget/Provider/Riverpod/Bloc, grep forAnimationController/Duration(. - If it's static designs (Figma export, images, HTML/CSS): extract tokens visually — color hex values, spacing scale (4/8px grid detection), font stack, corner radii, elevation/shadow values. Infer component boundaries from visual grouping.
- Never guess silently on ambiguous business logic (e.g., "does this button submit or save-draft?") — flag it as an assumption in the output README rather than blocking generation with a question.
Default assumption policy: proceed with the most conventional interpretation and log assumptions; only ask a question if the ambiguity blocks technical implementation (e.g., target framework genuinely unknown).
Mode B: New Build — PRD Alignment (ask before generating)
Ask a single consolidated batch, not one-by-one:
- Who is the primary user and what's the core task/flow (1-2 sentences)?
- Target platform: web, mobile, or both? Which framework preference, if any?
- What are the 3-5 must-have screens/features for v1?
- Any existing brand/design system or reference inspiration to match?
- Any specific interactions/animations that are core to the experience?
Then produce a short PRD (problem, users, scope, out-of-scope, screen list, success criteria) before scaffolding. Proceed to the same generation pipeline as Mode A once confirmed.
Generation Pipeline (shared, framework-specific execution)
| Step | React + TypeScript | React Native | Flutter |
|---|---|---|---|
| Scaffold | Vite + TS template | Expo (managed workflow) | flutter create |
| Styling | Tailwind CSS + shadcn/ui | NativeWind or StyleSheet + React Native Paper | Material 3 widgets / Cupertino |
| State | useState/useReducer + Context; Zustand for shared state | Same as React web | Riverpod (preferred) or Provider |
| Navigation | React Router | React Navigation (stack + tabs) | go_router |
| Forms | react-hook-form + zod validation | react-hook-form | flutter_form_builder |
| Animation | Framer Motion | React Native Reanimated | flutter's AnimationController / implicit animations |
| Icons | lucide-react | lucide-react-native / @expo/vector-icons | Material Icons / Cupertino Icons |
Low-resource build config defaults:
- No monorepo tooling unless requested; single-package project.
- No heavy state libraries (Redux) unless the reference explicitly uses one — prefer built-in state.
- Dev server only; skip production bundling/CI setup unless asked.
- Use CDN/local fonts, avoid pulling in large asset pipelines.
Recommendation▾
Include a worked example of the assumption-logging README output to make the 'flag don't ask' pattern tangible
Trusted Component Library References
- React/Web: shadcn/ui (primary), Radix UI primitives, MUI (when Material design language is needed), Headless UI, Tailwind UI patterns for layout reference.
- React Native: React Native Paper, NativeBase, Expo's built-in components, React Navigation examples.
- Flutter: Flutter Widget Catalog (official), Material 3 widget gallery, flutter_gems.dev for curated packages.
- Design inspiration/reference (visual only, not code source): Mobbin, Dribbble, Page Flows, Material Design guidelines, Apple Human Interface Guidelines.
Always prefer copying accessible, tested component code (e.g., shadcn/ui's copy-paste model) over reinventing primitives like dialogs, dropdowns, or date pickers.
Interactivity & Accessibility Requirements (apply to every generated prototype)
- Every button/link has a real
onClick/onPress/onTaphandler — no placeholder no-ops. Use console log or local state transition minimum; wire to a mock data layer for CRUD-like flows. - Forms validate on submit and show inline error states.
- Navigation must be fully traversable (no orphan screens, back navigation works).
- Responsive breakpoints: mobile (<640px), tablet (640-1024px), desktop (>1024px) for web/React; safe-area-aware layouts for RN/Flutter across phone and tablet.
- WCAG 2.1 AA baseline: semantic HTML/roles, visible focus states, min 4.5:1 text contrast, all interactive elements reachable via keyboard (web) or accessible via screen reader labels (
accessibilityLabel/Semanticswidget), alt text on images, min 44x44px touch targets on mobile. - Loading, empty, and error states included for any data-driven view, not just the happy path.
Testing Protocol (run before delivering)
Progress:
- [ ] Every interactive element mapped and manually triggered once (list them)
- [ ] Navigation graph traced start-to-finish with no dead ends
- [ ] Resize/viewport check at 375px, 768px, 1280px (or RN/Flutter device sizes: small phone, tablet)
- [ ] Form validation checked for empty/invalid/valid input
- [ ] Keyboard-only pass (web) or screen-reader label check (mobile)
- [ ] Contrast spot-check on primary text/background pairs
- [ ] Cross-framework parity check if same prototype requested in multiple stacks: same screens, same flow, same states
- [ ] README lists how to run, what's mocked vs real, and assumptions made
Deliver a short test report alongside the code: list of interactive elements verified, screen sizes checked, and any known gaps.
Cross-Agent Reusability
Standardized I/O contract any agent (Claude, Codex, etc.) can follow:
Input schema:
{
"mode": "replicate" | "new_build",
"reference_assets": ["path/to/design.zip", "path/to/inspiration.png"],
"framework": "react-ts" | "react-native" | "flutter" | null,
"prd": { "users": "", "core_flows": [], "must_have_screens": [] } | null
}
Output contract: a project directory following the framework's standard scaffold, plus PROTOTYPE_README.md containing: run instructions, assumptions made, component/state mapping to the reference (if Mode A), test report, and a features/roadmap note for follow-on iteration.
This contract lets any agent invoke the skill by populating the input schema and consuming the output directory + README deterministically, regardless of the underlying model.
Best Practices
- Prioritize fidelity to the reference's interaction logic and structure over pixel-perfect styling when trade-offs are forced.
- Keep component trees shallow and named to mirror the reference (helps diffing/comparison later).
- Mock backend calls with realistic delays (300-600ms) and loading states rather than instant fake data.
- Log every non-obvious assumption in the README instead of asking mid-generation.
Common Pitfalls
- Don't launch into PRD questions for a clear replication request — this violates the low-friction pattern.
- Don't add Redux/Bloc/heavy DI frameworks by default — only mirror what the reference or explicit requirement calls for.
- Don't ship screens with non-functional buttons or unreachable routes — every element must be testable.
- Don't skip responsive/accessibility passes to save time — they're part of the definition of done, not optional polish.
- Don't over-fetch external references live; rely on the curated library list above unless the user supplies specific new sources.