Proto Design

---
name: prototo-design
description: Design and refine native Prototo prototypes with a coherent visual identity, reusable components, purposeful motion, and screenshot-based review. Use for new screens, redesigns, or interaction polish within Prototo's supported runtime.
---

# Design with Prototo

Apply this guidance to the prototype being built, not to Prototo's own branding. Keep the host workflow's tools, file permissions, preview and publishing rules. A design request does not authorize publishing, dependency changes or editing other projects. The project's existing design and the user's references take priority over these defaults.

## Choose a direction that belongs to this app

Before a substantial new screen or redesign, identify the audience, primary action and visual character. If the brief is sufficient, choose a direction and proceed; ask only when an unresolved preference would materially change the result. Default to a considered, restrained style suited to the app's purpose. Do not give every app the same café palette, giant headline, gradient background or grid of rounded cards.

Record a compact direction in DESIGN.md: the visual character; colour and type roles; spacing and shape choices; image treatment; and where motion helps. For a small edit, preserve those decisions and change only what is needed. Use an existing reference faithfully when provided. Do not substitute a new aesthetic for a specific request.

Make one element carry the screen's personality: its imagery, typographic hierarchy, composition or a meaningful interaction. Keep surrounding controls clear and calm. Design using believable content of realistic length. A product list needs usable products, prices and selection states, not decorative metrics or filler slogans. A request for a new visual identity authorizes reconsidering the palette and imagery as well as layout; preserve the app's data and flows, but do not mistake the scaffold's colours for user-mandated branding.

## Apply a shared profile when supported

When list_design_profiles and apply_design_profile are available, read the project design and capabilities before composing a new app or a requested restyle. Choose Warm, Utility, Editorial or Expressive from the returned descriptions and composition guidance. Apply the returned exact version with the current revision. For a brand-new unbranded scaffold, use preserveExisting=false so its starter accent does not override the chosen direction; pass the user's explicit brand values as overrides. Existing projects preserve overrides by default. Small follow-up edits keep the profile and do not reapply it.

The operation writes effective runtime values and refreshes the managed DESIGN.md section together. Put project rationale and inspected reference links outside its markers. Never hand-edit generated token notes, overwrite a custom configuration that the tool refuses, or change managed components to bypass a capability check. If profile tools or compatible components are unavailable, preserve the current design and use supported existing APIs; do not claim that a profile was applied. A guide update alone does not add runtime capabilities. Read screenFooter, purchaseAction and skeleton capabilities separately; older projects may support profiles without these components.

Use these category references as starting points when the user has no stronger direction:

| Category | References | Pattern to investigate |
|---|---|---|
| Finance | Cash App, Revolut | Money hierarchy, quick actions, financial complexity |
| Social | Instagram, TikTok | Feed mechanics, creation, engagement |
| Dating | Tinder, Bumble | Discovery, profiles, progressive decisions |
| Games | Brawl Stars, Clash Royale | Lobby, progression, currencies, rewards |
| Lifestyle | Airbnb, Strava | Discovery and habit-driven experiences |
| News | NYTimes, Apple News | Content hierarchy, editorial feeds, reading |
| Productivity | Notion, Todoist | Information structure, creation, task completion |
| AI | ChatGPT, Perplexity | Conversation, prompt input, tools and sourced answers |

For a new app or substantial visual redesign, use connected Mobbin before choosing the visual direction. Search the relevant task and reference pair, inspect actual images and discard mismatched results. For coffee ordering, Starbucks and Blue Bottle Coffee are useful starting points for menu, customization and pickup. Start with Standard search; keep initial research to at most three requests with up to five results each. Record the actual app/screen links, two or three useful observations, and the decisions they inform in DESIGN.md. A search result alone is not inspected evidence. Do not research all sixteen apps for every project or repeat research for small edits. Mobbin's game searches have returned unrelated apps: use authentic game captures before claiming a game reference was inspected. If research is unavailable, proceed from built-in profiles without claiming external evidence. Adapt useful patterns to the app's own brand; screenshots establish neither motion behaviour nor native API support.

## Give the app a visual identity

Layout polish is only one part of a redesign. Choose a coordinated palette, imagery/artwork treatment and surface treatment that suit this app. Record their implemented choices in DESIGN.md alongside the profile. When the user asks for visual differentiation, check that the actual preview differs meaningfully in colour and visual language, not just labels and spacing.

Useful directions include warm paper with ink and an original illustration; crisp utility surfaces with a fine grid or contour accent; editorial layouts with selective photography and restrained texture; or expressive media with a bounded mesh/light field. These are options, not fixed category mappings. Retain a quiet treatment when the user wants it. Do not add every effect to every screen. Put a stronger visual treatment in a useful hero or completion state; keep forms, totals and reading surfaces calm. An ordinary accent wash is not a substitute for art direction.

Use the installed expo-linear-gradient for a simple gradient. Skia is appropriate for original illustrations, repeated patterns, grain, layered gradients and procedural shaders; use it when those are part of the chosen direction. Keep labels, controls and navigation in native/Prototo components over or beside the canvas so accessibility and Dynamic Type remain intact. Artwork must have a clear relationship to the app; do not reuse the same stock hero image by habit. When suitable imagery is unavailable, an original vector composition avoids a broken remote asset. Never distribute reference screenshots as product artwork.

For a Skia treatment in components/shared:
- Verify @shopify/react-native-skia is installed. Use Canvas with Fill/Shader for a procedural field, and native Skia paths/shapes for illustrations. Create RuntimeEffect once outside render; handle a null result or compilation exception with a solid/gradient fallback. Do not assert compilation success with `!`.
- A minimal shader has `uniform float2 resolution; half4 main(float2 p) { float2 uv = p / max(resolution, float2(1)); return half4(uv.x, uv.y, 0.5, 1); }`. This demonstrates coordinates, not a finished palette. Pass the canvas's measured width/height to resolution and palette colours as uniforms. Use Canvas onSize with a shared value and derived uniforms on Fabric; Canvas onLayout is unsupported there, and Stack does not forward that prop. Put the canvas in an explicitly bounded parent, disable its pointer events, and hide decorative artwork from accessibility.
- Start with a static shader. Stable low-opacity grain, contours or a light field can establish identity without perpetual animation. If motion serves the brief, stop its clock while offscreen/backgrounded and under Reduce Motion; retain a static composition. Avoid stacked full-screen blurs or multiple continuously redrawing canvases.
- Static Skia artwork can be rendered once to a bounded offscreen surface and shown with the installed native image component. Cache a small number of results by artwork/palette key and release native pictures, surfaces and snapshots after encoding. This preserves original drawing/shader work without depending on a live canvas surviving navigation. Keep a solid fallback when rendering fails. This approach is for static art, not animated shaders; verify live canvases separately.
- Keep text on controlled-contrast surfaces; inspect light/dark, compact layout and the fallback on the actual native runtime. Navigate away and back, then change appearance; confirm canvases remain visible. Successful TypeScript/export does not prove that a shader compiled or rendered. Do not claim frame-rate or power measurements from screenshots.

## Compose with hierarchy and room

- Give the screen one clear primary action. Organize related content through spacing and alignment before adding containers or borders. Cards are useful for independently actionable groups, not every paragraph.
- Choose type roles deliberately. The available system font is a valid choice; use weight, scale and line height to establish hierarchy. Only use a custom font when its actual asset and loading path are available. Never name an unbundled font and assume it renders.
- Use the project theme for surfaces, text, spacing and radius. Read the actual component API before styling: for example Card accepts glass/padding, not an arbitrary style prop, while Stack and Row accept style. Reuse a component's built-in padding instead of nesting more padding accidentally.
- A light/dark palette needs deliberate text and surface pairs. When the host allows proto.config.js edits, put supported brand overrides there. Prefer apply_design_profile for supported managed settings. For additional values outside that contract, define permitted extra design values once in components/shared/theme.ts, using the active scheme; do not edit managed files or duplicate palettes across screens. Keep DESIGN.md consistent with what the code actually uses.
- Give photographs a deliberate crop, stable aspect ratio, useful focal point and loading/error fallback. Use a consistent image treatment. Never imply an image has loaded until it is visible in the preview.
- Plan for narrow screens, safe areas, native headers, tab bars, keyboards and larger text. Let text wrap and containers grow. Preserve Dynamic Type. Interactive targets should be at least 44 points, and selection should have a non-colour cue.
- Reserve display-sized typography for meaningful headlines. At accessibility sizes, simplify decorative copy and artwork, stack labels/prices that no longer fit side by side, and replace crowded segmented choices with an appropriate native selection control. Keep body text and controls responsive to the user's text-size setting; do not disable scaling to preserve a screenshot composition.

## Reusable native patterns

Build custom compositions in components/shared using the installed Prototo primitives. Keep product data and state in the screen or a shared model; the same value must drive the summary, detail screen and confirmation. Reuse a pattern when behavior matches, while allowing its visual treatment to suit the app.

**Component boundary:** generated screens and shared compositions must not import View, Text, Pressable, Image, ScrollView or Animated from react-native. Use Prototo Stack/Row/Text/Screen for layout, Motion.Pressable for custom press targets, Motion.View for animated containers, and the installed expo-image Image for photographs. Non-visual React Native APIs such as AccessibilityInfo are allowed. Existing source can contain older patterns; copying it does not make those patterns the preferred API for a redesign. Preserve its data and behavior while using the supported components for changed UI. Keep generated screens free of comments and TypeScript type declarations.

**Image-led item:** one clear image, a title, a concise useful detail and the relevant price/status. Make either the whole item or a clear button the action; avoid nested press targets. Do not put critical text over an unpredictable image without checking contrast. In a collection, keep image ratios and baselines consistent.

**Selection group:** use native Picker for short mutually exclusive choices, Toggle for independent settings, and Stepper for a bounded count. For choices that need a richer label or image, use a selectable row/card with an explicit selected marker and accessibility state. Give the group a label; preserve selection while moving through the flow. An unavailable choice explains why.

**Persistent purchase action:** when screenFooter and purchaseAction are supported, use `<Screen footer={<PurchaseAction total={formattedTotal} detail={orderSummary} label="Review order" onPress={openReview} />}>` around the choices. The action is outside the scroll content at ordinary text sizes and respects native tabs and the keyboard. At accessibility font scales or short viewports it becomes part of the scrolling content so choices remain reachable. Keep detail concise and use the screen model's immediate derived total; the component does not calculate prices. Do not wrap Screen in another ScrollView, absolutely position the footer, or manually add a tab-bar spacer. Check native header/back behavior in the actual route. For unsupported projects, retain a visible ordinary Button and offer a separate new study instead of inventing footer support.

**Detail and checkout:** lead with the item and its current state, group customization controls, then show the derived total near the primary action. Use the existing native Modal for a compact checkout sheet or a native route for longer content. Preserve swipe dismissal and back behavior. Do not emulate a native sheet with an animated full-screen View. Give long content an appropriate scrolling route instead of allowing a fit-to-content sheet to overflow.

**List row:** align the primary label, supporting information and trailing value/action consistently. Separate groups with spacing or restrained dividers. Use actual SF Symbols through SymbolView where appropriate. A row's label should describe its action without relying on an icon alone.

**Loading is a baseline primitive:** plan initial loading, loaded, empty and error/retry states for every asynchronous region without waiting for the user to ask. When skeleton is supported, compose SkeletonBlock shapes inside Skeleton's placeholder to match the arriving rows, image ratios and text hierarchy. Use one boundary per region and a short contextual label. Example: `<Skeleton loading={pending && !data && !error} label="Loading menu" active={isFocused} placeholder={<Stack><SkeletonBlock height={160} radius={16} /><SkeletonBlock width="65%" /></Stack>}>{content}</Skeleton>`. Read the supported API; do not invent shape/animation props or draw per-screen shimmer implementations.

The primitive reserves placeholder space immediately, reveals it after 180 ms, shares one native shimmer clock and removes loading immediately when content is ready. It follows theme colours, honours live Reduce Motion changes with static shapes, pauses in the background, and exposes one busy accessibility element while hiding decorative blocks. Pass active=false for an unfocused route or offscreen region; use the router's focus hook and list viewability for those cases. Match skeleton dimensions to the real responsive layout, including larger text. Skeleton does not fetch data or decide when a request failed: connect loading to actual request state, end it on error/cancellation, and show a useful retry action. Keep existing content visible during refresh. Do not fake network delays or show skeletons over ready local/mock data. For images, keep the Image mounted so its load/error callbacks can fire; overlay a bounded skeleton until the image resolves instead of putting the unloaded image inside Skeleton's unmounted children. A failed image needs a stable fallback, not an endless shimmer. Older projects without skeleton support keep a concise accessible loading message; do not import a missing primitive or edit managed files to add it.

**Empty and completion states:** an empty view explains what belongs there and offers a next action. Completion shows what changed, any important details and the next useful action. Show a simulated result as a prototype result; do not claim a real order, payment or booking occurred.

Use native tabs and stacks already supported by the project, native controls, and native materials when they suit the composition. Native navigation supplies its own transition. Do not wrap it in a second competing animation. Prefer the system header material; do not add an opaque brand-colour fill or divider by habit. Keep titles and actions legible in both appearances. Preserve the managed TouchDots wrapper.

Respect existing compact-title guards for the reported iOS 26 scroll/push/back freeze; they are a compatibility workaround, not a universal visual preference. For an explicitly requested navigation study, inspect the installed router API: SDK 57 exposes headerLargeTitleEnabled (headerLargeTitle is deprecated). Use a native scroll container with automatic insets and check actual collapse, back button, swipe-back, repeated pushes, tab switching and both appearances before accepting that screen. The Coffee fixture passes these simulator checks with a transparent native large title, but this does not establish a general runtime fix or phone acceptance. Keep untested projects' guards and avoid layering custom blur over native scroll-edge effects.

## Motion that responds to the user

Pick a small, consistent motion vocabulary. The default is prompt feedback with gentle settling, not a succession of reveals. Frequent actions must remain fast. Do not add ambient motion unless it serves this particular design.

- Use components/proto/motion (Motion.View and Motion.Pressable) for supported declarative state transitions, small scale feedback and fades. Paths depend on the importing file; from components/shared the prefix is ../proto, from screens it is ../components/proto. Inspect the installed types before choosing animate or transition properties. Motion uses flat animation fields: `animate={{ scale: 1 }}` and `pressedAnimate={reduceMotion ? { scale: 1 } : { scale: 0.985 }}`. The React Native style form `transform: [{ scale: ... }]` is not valid inside animate/pressedAnimate. Set the resting value explicitly so release returns to it.
- Use components/proto/gestures for drag-, swipe- or scroll-driven motion: shared values, animated styles, spring/timing helpers and gesture handlers. Do not drive continuous gestures through React state on every frame. Avoid changing layout measurements each frame when a transform can express the same effect.
- Let native buttons, toggles, tabs and sheets handle their built-in feedback. Add custom motion only to the surrounding product state that otherwise needs explanation. Never delay a state update or navigation until a decorative animation completes.
- Useful starting ranges for custom motion are 100–160 ms for press feedback, 180–280 ms for a state change, and a short damped spring for release. These are tuning starting points, not guarantees. Check interruption, rapid repeated taps and cancellation; movement should settle to the latest state.
- Prefer small displacement and opacity/transform changes. Price updates must immediately reflect the real derived value; animation cannot briefly show an incorrect total. Keep mounting keys stable so selecting an option does not reset the whole screen.
- Honour Reduce Motion using supported React Native accessibility APIs; skip decorative translation, scale and stagger when enabled and retain immediate state changes. Default to reduced motion until the asynchronous preference check resolves, and keep that safe default if the check fails. Subscribe to preference changes and clean up listeners, timers and interrupted animation work. Native transitions should keep their system accessibility behavior.
- Use haptics sparingly for a meaningful selection or completion, through installed expo-haptics APIs. Avoid double feedback on native controls. Haptics are optional feedback, never the only signal.
- Use Lottie only with a supplied or verified asset and Skia only when custom drawing materially helps. Do not invent asset files or import new native packages. A shared-element transition is a separate compatibility task; do not promise it from a static screenshot.

## Review the result before presenting it

Before submitting edits, audit the actual changed code: supported imports; real image fallback behavior; the preserved pricing/data logic; immediate totals; Reduce Motion behavior; and the primary action's position on a phone. Do not count a DESIGN.md claim as implementation. When copying through a JSON tool argument, check that intended line breaks become real newlines in rendered text, not a visible backslash followed by n. Prefer natural text wrapping unless a deliberate break improves the layout.

For a redesign comparison, name the concrete differences from the baseline. Reusing essentially the same composition with larger gaps or extra cards is not sufficient evidence of improved hierarchy. Keep the primary action and useful product information easy to find, and use the screenshot to check that decorative content has not pushed them needlessly below the fold.

Use the host's available build and preview tools. Inspect the actual current-revision screenshots, not only source code or a successful build. Prioritize: broken/blocked UI; clipped content and wrong totals; hierarchy and legibility; inconsistent spacing/components; then optional decoration. Fix demonstrated issues together and capture again, rather than rebuilding for every speculative adjustment. Respect the host's retry and build limits.

Check the main screen, a detail/selection state and a completion or empty state as relevant. Review initial loading, fast/cached responses without skeleton flashes, refresh retention, error/retry and image fallback, actual font rendering, long labels, contrast, native chrome and bottom controls. Test dark mode, larger text, keyboard and scrolling when those controls are available. Otherwise name the untested cases briefly; do not claim they passed.

Screenshots establish appearance only. Test gestures, interruption, back navigation, sheet dismissal, Reduce Motion and perceived smoothness in an interactive simulator or on the user's iPhone. Haptics require an actual device. When unavailable, provide a short, specific phone checklist instead of claiming the app feels smooth.

For a comparison, preserve the baseline, use the same content/device/routes, and record what changed. Assess hierarchy, consistency, readability, useful states and interaction clarity. A visually different result is not automatically a better one. Keep screenshots private and publish only according to the user's request and the host workflow.