React prototype system

React Prototype System

Build the experience as a system, then compose the screens. Optimize first for learning, interaction, fidelity, and changeability while leaving a clear path to production.

Core Contract

Apply these rules throughout the task:

1. Inspect the design source and repository before writing code.

2. Preserve the repository's framework, conventions, tokens, components, and tooling unless the task requires a greenfield setup.

3. Default new or otherwise unconstrained React implementations to TypeScript and Tailwind CSS. In an existing repository, use them when present; do not migrate a coherent local stack unless the user requests it.

4. Preserve meaningful Figma names for components, variants, props, and internal elements after normalizing them for code. Infer missing, generic, or autogenerated names from product role and context.

5. If the Figma file has a design system, map its variables, styles, modes, and semantic tokens into the project's Tailwind-supported theme mechanism before implementing product components. If it has none, use the Tailwind default theme as the baseline.

6. Put each exported component in a file with the same component name, make the component responsive, and compose pages from those responsive components.

7. Work from experience and flow to components and implementation:

   experience -> interaction flow -> states -> component contracts -> tokens -> implementation

8. Build dependencies from lower layers to higher layers:

   tokens -> primitives -> patterns -> layouts -> screens -> flows

9. Prefer stateless display components controlled by explicit props and callbacks.

10. Keep mock data, side effects, navigation, and orchestration outside reusable display components.

11. Implement the primary path and at least one relevant failure or recovery path.

12. Use real design assets when provided. Determine every persisted asset's format from its bytes or parseable SVG XML, not its URL suffix; SVG content must use an .svg suffix.

13. Do not replace inspectable product imagery or icons with vague placeholders.

14. Verify behavior and visual fidelity in a running browser at representative desktop and mobile sizes.

15. Protect the first useful render in impact order: async waterfalls, initial bundle, server/client boundaries, duplicate client work, re-renders, browser rendering, then JavaScript micro-optimizations.

16. Stop adding architecture or optimization when it no longer improves learning, fidelity, responsiveness, reuse, or changeability.

Treat these as defaults, not permission to fight an established codebase. Local patterns win when they already solve the same problem coherently.

Workflow

1. Classify the Request

Identify all three dimensions before implementation:

• Code context: existing application, isolated package, or greenfield prototype.
• Design scope: component, screen, multi-screen flow, or design-system exploration.
• fidelity target: exact reconstruction, close interpretation, or open-ended concept.

If the user does not specify fidelity, reproduce the supplied design closely. Do not redesign it merely to make implementation easier.

If implementation tooling is unspecified, use TypeScript and Tailwind CSS for a greenfield or otherwise unconstrained prototype. Do not migrate an established project solely to enforce this default.

2. Gather Evidence

Inspect the repository for framework, routes, TypeScript configuration, Tailwind or other styling setup, tokens, icon libraries, assets, state libraries, test commands, and component conventions. Inspect every relevant design frame, variant, breakpoint, annotation, and asset.

Record the minimum working model needed to implement confidently:

• Figma component, component-set, variant, property, and meaningful layer names
• missing or autogenerated names that require contextual inference
• design-system variables, collections, modes, text styles, effects, and shared components
• visual hierarchy and geometry
• typography, color, spacing, radii, borders, and shadows
• reusable regions and variants
• interactive controls and transitions
• loading, empty, error, permission, and recovery states that are shown or implied
• desktop/mobile relationships
• required images, icons, fonts, and content, including source, declared MIME, detected format, final filename, and import strategy
• primary-path async dependencies, heavy optional modules, server/client boundaries, and likely repeated work

Read design-intake.md for Figma, screenshot, visual-spec, or incomplete-design tasks. For a substantial flow, copy prototype-brief.md into a temporary working note and fill only the useful sections.

Whenever a Figma asset is downloaded or persisted, read figma-assets.md. Treat response Content-Type as evidence and the downloaded bytes or parseable SVG root as authoritative. Do not import the asset until its suffix and integrity have been verified.

3. Model Before JSX

Create seven small internal artifacts before coding:

1. A screen or flow map.
2. A Figma-to-code naming map, including every inferred name that affects public APIs or file placement.
3. A component inventory grouped by layer.
4. A design-system and Tailwind token map, or an explicit decision to use Tailwind defaults.
5. A state and scenario matrix.
6. An asset and responsive-behavior map.
7. A critical-path map covering first useful render, deferred work, data ownership, and material performance risks.

Do not turn these into user-facing documentation unless requested. Use them to resolve ownership and prevent page-first sprawl.

Read architecture.md when deciding layers, folder placement, dependency direction, or greenfield structure.

4. Establish the Visual Foundation

Map design evidence to the existing design system first. Add or extend tokens only for values that recur or carry semantic meaning. Keep one-off composition values local when turning them into global tokens would create noise.

If the Figma file exposes a design system, build its Tailwind foundation before product components:

1. inventory primitive and semantic variables, styles, modes, and component properties
2. reuse equivalent repository tokens where they already exist
3. map the remaining semantics into the project's supported Tailwind theme, configuration, or CSS-variable mechanism
4. preserve Figma semantic names after code-safe normalization
5. implement primitives and product components only after the token layer is available

If the Figma file has no design system, use the Tailwind default color, spacing, typography, radius, shadow, and breakpoint scales as the baseline. Extend them only when required to reproduce material design evidence.

Establish, in this order:

1. font loading and text roles
2. color and surface roles
3. spacing and layout constraints
4. radius, border, shadow, and elevation roles
5. motion durations and easing when motion is part of the design

Do not use a generic theme as a substitute for reading the source.

When using Tailwind CSS, prefer configured utilities over repeated arbitrary values, while keeping true one-off composition values local.

5. Build Bottom-Up

Implement the smallest coherent vertical slice while maintaining layer direction:

1. Reuse or extend existing primitives.
2. Build reusable visual patterns.
3. Add domain components that accept data and callbacks.
4. Compose layouts and screens.
5. Connect routes, state transitions, and mock behaviors.

When Figma provides a design system, complete its mapped Tailwind token foundation before the first product component. When it does not, avoid inventing a large abstract system before the first working screen; extract reusable pieces as evidence appears and keep screen-specific composition close to the screen.

Write React components in .tsx and non-JSX modules in .ts when the default stack applies. Use Tailwind utility classes for component styling and responsive behavior, following any class-merging and variant conventions already present.

Normalize a meaningful Figma component name to PascalCase and use it for both the exported symbol and file, such as Product card -> ProductCard in ProductCard.tsx. Preserve meaningful Figma variant and property names as typed props. Infer only names that are absent, generic, or autogenerated.

Make the component itself responsive with Tailwind breakpoint and state utilities. Keep the page focused on importing, composing, and connecting responsive components; do not rebuild their internal desktop and mobile markup inside the page.

Before adding imports for persisted Figma assets, run the skill-local audit_figma_assets.py against the downloaded file or asset directory. Review the read-only report first; use --fix only for safe suffix renames, then update every code, CSS, markup, manifest, fixture, test, and documentation reference to the old filename. Re-run the audit after those edits. The fixer must never overwrite a conflicting target or stand in for intentional SVG sanitization.

Read figma-naming-and-tokens.md for naming normalization, missing-name inference, Figma design-system detection, Tailwind token mapping, component files, and responsive page composition. Read component-contracts.md when defining component boundaries, props, variants, TypeScript types, or semantic behavior. The optional create_component.py helper may scaffold a stateless host-element component in a greenfield project; do not use it when the repository has a different generator or file convention.

6. Protect the Critical Path

After editing several React components, adding real async work, crossing a server/client boundary, or introducing a heavy dependency, review the changed route as one runtime path.

Apply improvements in this order:

1. Start independent async work together; defer awaits until their values are needed.
2. Keep the initial module graph narrow with statically analyzable imports and meaningful lazy boundaries for heavy off-path features.
3. In server-rendered repositories, parallelize independent regions, keep request data out of shared module state, and serialize only fields consumed by client components.
4. Reuse the repository's existing client data and request-deduplication layer; keep prototype mocks deterministic instead of adding production infrastructure.
5. Derive values during render, run action-specific side effects in event handlers, use functional updates for previous-state changes, and define components outside other component renders.
6. Add memoization, transitions, deferred values, virtualization, or hot-path JavaScript changes only when the work is expensive or supported by profiling evidence.

Preserve stable geometry across lazy, loading, and Suspense boundaries. Use existing framework image, caching, package-import, and code-splitting capabilities before adding dependencies or custom infrastructure.

Read react-performance.md for async dependency mapping, bundle decisions, server/client boundaries, client data, hooks, re-render policy, hydration, media delivery, review severity, and verification evidence.

7. Make States and Data Deliberate

Place state at the narrowest owner that coordinates every consumer. Keep derived values derived. Keep server or mock data separate from display components. Represent mutually exclusive statuses explicitly instead of combining contradictory booleans.

Create deterministic mock scenarios for the states needed to evaluate the design. At minimum include:

• the primary populated state
• one relevant failure, empty, permission, or recovery state

Add loading, long text, overflow, first-use, offline, and destructive-action states when the product surface makes them plausible or the source shows them.

Read state-and-mocks.md. Copy state-matrix.md only when a multi-state prototype needs a persistent scenario inventory.

8. Complete the Interaction Flow

Make controls perform their implied actions. Connect navigation, menus, tabs, dialogs, filters, forms, undo, retry, and dismissal as the design requires. Prefer a deterministic local simulation over dead controls or unnecessary backend work.

Keep screens focused on import -> compose -> connect. Move reusable behavior into hooks or controllers and side effects into services or existing data layers.

Read flows-motion-responsive.md for page composition, flow modeling, motion boundaries, responsive behavior, and accessibility.

9. Verify in the Browser

Run the application and validate the actual rendered result. Use browser screenshots and DOM or console inspection where available.

Verify in this order:

1. route loads and the main flow completes
2. major regions, geometry, and responsive constraints match
3. typography, assets, color, and surfaces match
4. states, focus, keyboard behavior, and recovery work
5. motion supports the transition and respects reduced motion
6. request order, lazy boundaries, hydration, and expensive repeated renders show no primary-path regression
7. tests, type checks, lint, and build pass as supported by the repository

Compare against the source at representative design dimensions and at least one narrow viewport. Fix the largest perceptual or behavioral mismatch first, then repeat.

Read verification.md before declaring the task complete.

Reference Routing

Load only the references needed for the current task:

Need	Read
Interpret a Figma frame, screenshot, annotation, or asset set	design-intake.md
Download, persist, rename, import, inline, or debug a Figma asset	figma-assets.md
Preserve or infer Figma names and map a Figma design system into Tailwind	figma-naming-and-tokens.md
Choose layers, folders, imports, or greenfield structure	architecture.md
Define component APIs, props, variants, semantics, or types	component-contracts.md
Review async waterfalls, bundles, server/client boundaries, hooks, re-renders, hydration, or runtime performance	react-performance.md
Decide state ownership, data boundaries, or mock scenarios	state-and-mocks.md
Compose pages, interactions, motion, responsive behavior, or accessibility	flows-motion-responsive.md
Review fidelity, behavior, code quality, and completion	verification.md

Completion Gate

Do not call the prototype complete until all applicable statements are true:

• The intended route or entry point renders without runtime errors.
• New or otherwise unconstrained React code uses TypeScript and Tailwind CSS.
• Meaningful component, prop, variant, and internal names trace to Figma; inferred names are semantic and context-based.
• A Figma design system is represented through Tailwind-compatible tokens before components consume it, or Tailwind defaults are used when no design system exists.
• Every reusable exported component lives in a matching named file and owns its responsive behavior.
• Pages compose and connect responsive components instead of reproducing their internal markup.
• The primary flow is usable from start to finish.
• A relevant alternate, failure, or recovery state is reachable.
• Reusable display components do not fetch, navigate, or own unrelated business state.
• Independent async work on the primary path is not serialized without a dependency reason, and heavy off-path modules are deferred when the split is meaningful.
• Server/client boundaries pass only required data and contain no request-specific mutable module state.
• Derived values are not mirrored through effects; action logic lives in handlers; memoization and concurrent APIs solve an evidenced cost.
• Every persisted design asset has content that matches its suffix; SVG structure and import behavior are valid for the repository.
• Every responsive SVG has a valid viewBox, and any remaining asset-audit warning is resolved or explicitly justified for the chosen rendering strategy.
• Any asset rename is reflected in all code, CSS, markup, manifest, fixture, test, documentation, and public-path references.
• Supplied assets are used correctly and no inspectable content is replaced by arbitrary placeholders.
• Desktop and narrow layouts are coherent and free of unintended overlap or clipping.
• Interactive elements use appropriate semantics, labels, focus behavior, and keyboard access.
• The result has been visually compared with the design source after rendering.
• Supported checks pass, or remaining failures are reported with their cause.

Anti-Patterns

Correct these immediately when encountered:

• starting with a monolithic page and extracting only after it becomes unmanageable
• duplicating an existing local primitive or icon
• placing fetches, routing, or global state inside a visual card or row
• inventing a prop for every possible future need
• using boolean combinations that permit impossible states
• hardcoding business data in JSX instead of passing data or using mocks
• awaiting independent operations sequentially or blocking a whole route on one independently renderable region
• eagerly importing a heavy off-path feature, hiding import paths from static analysis, or introducing a broad catch-all barrel without a local convention
• passing full server records through a client boundary when the component consumes only a few fields
• storing request-specific mutable data in server module scope
• synchronizing derived state or user-action flags through effects
• memoizing cheap expressions, every callback, or every component without a measured or structurally expensive render
• treating one desktop frame as proof of responsive behavior
• adding motion inside every component instead of at transition boundaries
• declaring visual fidelity from code inspection without running the interface
• replacing a supplied product asset with a generic stock image, emoji, or hand-drawn substitute
• trusting a Figma export URL or suggested filename instead of detecting the downloaded content format
• storing SVG XML under .png, rasterizing it without a product requirement, or renaming it without updating every reference
• assuming SVG imports become React components without checking the repository's bundler and TypeScript setup
• inlining SVG with active content, broken IDs, missing responsive geometry, or unreviewed external references
• introducing JavaScript or a parallel styling system when TypeScript and Tailwind CSS are the selected defaults
• carrying autogenerated names such as Frame123 into public component or prop APIs
• renaming a meaningful Figma component without a product or code-contract reason
• hardcoding visual values in components while bypassing an available Figma design system
• inventing a parallel custom theme when the Figma file has no design system and Tailwind defaults are sufficient
• duplicating desktop and mobile component markup in a page instead of making the named component responsive