create-proto 0.4.5 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-proto",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "Scaffold a new Proto prototype: `npm create proto@latest myapp`. Designer-first native iOS prototyping environment that pairs with Claude Code.",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "@sherizan/proto-cli": "^0.4.2",
+    "@sherizan/proto-cli": "^0.5.0",
     "fs-extra": "^11.2.0",
     "qrcode-terminal": "^0.12.0",
     "validate-npm-package-name": "^5.0.1"

package/template/CLAUDE.md

@@ -24,11 +24,16 @@ You're the design tool inside a Prototo project. The designer prompts you in pla
 - `../components/proto/gestures` — `AnimatedView`, `useSharedValue`, `useAnimatedStyle`, `withSpring`, `Gesture`, `GestureDetector`, etc. Use **only** when the animation must read gesture state, scroll position, or interpolate continuously: "drag this card", "swipe to delete", "parallax this header". Driven by `react-native-reanimated` + `react-native-gesture-handler`.
 - `../components/proto/lottie` — `Lottie` component. Plays `.json` files dropped into `/assets/lottie/`. The designer brings the animation file (LottieFiles / After Effects export); you wire it: `<Lottie source={require('../assets/lottie/<name>.json')} />`. Defaults to `autoPlay` and `loop`. Driven by `lottie-react-native`.
 - `../components/proto/canvas` — `Canvas`, `Path`, `Circle`, `Rect`, `LinearGradient`, etc. For custom drawing that doesn't fit RN's box model: confetti bursts, custom charts, badge shapes. Driven by `@shopify/react-native-skia`.
+- `../components/proto/svg` — `Svg`, `Path`, `Circle`, `Rect`, `G`, `LinearGradient`, etc. For vector icons, logos, and illustrations. You can also import an SVG file directly: `import Logo from '../assets/logo.svg'` then `<Logo width={120} height={40} />`. Driven by `react-native-svg`. Use this for static vector art; reach for `canvas` only when you need to animate or compute the drawing.
 
-Never import `react-native-ease`, `react-native-reanimated`, `lottie-react-native`, or `@shopify/react-native-skia` directly in a screen — always route through the `../components/proto/<subpath>` module above. If `motion` can't express what's needed, fall back to `gestures`.
+Never import `react-native-ease`, `react-native-reanimated`, `lottie-react-native`, `@shopify/react-native-skia`, or `react-native-svg` directly in a screen — always route through the `../components/proto/<subpath>` module above. If `motion` can't express what's needed, fall back to `gestures`.
 
 **Custom** — when none of the above fit, write the component you need with React Native. Put shared ones in `/components/shared/`. The designer's vision wins; primitives are starting points, not constraints.
 
+## Adding a library
+
+To add any npm package (a font, an icon set, a utility), run `proto add <package>` — never `npm install` / `pnpm add` directly. `proto add` installs through `expo install`, which picks the version that matches this project and resolves dependencies cleanly, so the project doesn't break. If the package needs native code this Prototo doesn't bundle, `proto add` will say so — that feature won't appear on the device until the Proto team ships an updated Prototo.
+
 ## File layout
 
 ```
@@ -51,9 +56,59 @@ When the designer asks to change colors, typography, spacing, shape, accent, or
 
 When you add a new screen, add a one-line entry to `DESIGN.md`'s Screens section.
 
+## One palette, one place
+
+The theme colors live in `DESIGN.md` and the proto tokens — read them with `useTheme()` from `../components/proto`. When a design needs custom brand colors, fonts, or constants beyond the theme (e.g. a specific gradient or accent set), define them **once** in a single shared module (`/components/shared/theme.ts`) and import it everywhere that needs them. Never paste the same color/font constants inline into more than one screen — duplicated palettes drift out of sync. If you find a palette already inlined in a screen, lift it into the shared module and import it back.
+
+## Light, dark, and accessibility
+
+- **Dark mode is automatic.** `useTheme()` returns the right palette for the device's light or dark setting and re-renders when it flips. So use theme colors (`theme.surface.*`, `theme.text.*`, `theme.border.*`) instead of hardcoded hex/rgba, and the screen adapts for free. Custom brand colors in the shared theme module won't auto-adapt — if a design needs a dark variant of a brand color, define both and pick with the same light/dark signal. To pin a scheme for a prototype, set `colorScheme: 'light' | 'dark'` in `proto.config.js`.
+- **Text already scales** with the device's text-size setting (iOS Dynamic Type). Don't disable it. Lay out so text can grow a couple of steps without clipping — avoid fixed heights on text containers.
+- **Accessibility floors** live in `a11y` from `../components/proto`: tap targets ≥ `a11y.minTapTarget` (44pt), text contrast ≥ `a11y.minTextContrast`. After visual changes, the `proto shot` check (below) is where you confirm contrast holds — in both light and dark.
+
+## Check your work visually
+
+You can't see the Simulator by default, so after any visual change, look at it:
+
+1. Run `proto shot` — it captures the running Simulator to `.proto/last-shot.png`.
+2. Read that image and inspect it for real defects: overlapping elements, low contrast / unreadable text, clipping, cramped or uneven spacing, off-center layout, wrong colors.
+3. If something's off, fix it and capture again. Iterate until it looks right — don't make the designer be your QA.
+
+Do this especially after layout, color, typography, or spacing changes. If `proto shot` reports no preview is running, the designer needs to run `proto start` first.
+
+## Mock vs real data
+
+When a screen shows placeholder numbers that aren't yet wired to a real source, wrap them in `mock()` from `../components/proto` — `const conditions = mock({ wave: '0.8m' })`. It returns the value unchanged, so nothing breaks; it just makes stubbed data obvious and greppable so fake numbers never ship believing they're real. When you wire the value to a live source (a `fetch`), drop the `mock()` wrapper. (Don't use code comments to mark mock data — generated screens stay comment-free.)
+
+### Making it real
+
+When the designer says "use real data", follow this shape so every screen handles loading and failure the same way:
+
+1. Keep the `mock()` value as the **starting state** — it's what shows before the fetch resolves and if the network fails. Drop the `mock()` wrapper from the live value once wired.
+2. Fetch in an effect, guarding against the screen unmounting:
+
+   ```tsx
+   const [data, setData] = useState(FALLBACK);
+   const [loading, setLoading] = useState(true);
+   useEffect(() => {
+     let alive = true;
+     fetch(URL)
+       .then((r) => r.json())
+       .then((json) => { if (alive) setData(shape(json)); })
+       .catch(() => {})
+       .finally(() => { if (alive) setLoading(false); });
+     return () => { alive = false; };
+   }, []);
+   ```
+
+3. While `loading`, show a skeleton or the fallback — never a blank screen. On error, keep the fallback (the `.catch` above already does this); don't surface a raw error to the designer.
+4. Put fetch + shaping logic in `/components/shared/<name>Data.ts`, not inline in the screen.
+
+**Keyless APIs** (no key, CORS-open, good for prototypes): Open-Meteo (weather/marine/air), REST Countries, Open Library, PokéAPI, Art Institute of Chicago, TheMealDB, Wikipedia REST. Prefer these so "make it real" stays a one-prompt step. If a source needs a key, tell the designer that key goes in `proto.config.js`, nowhere else.
+
 ## When modifying
 
-Read the file first, rewrite the full file. Never partial edits.
+Read the file first, then make precise, targeted edits to the parts that change. Keep edits scoped — don't rewrite a whole file when a few lines change.
 
 ## Avoid
 

package/template/components/proto/a11y.ts

@@ -0,0 +1,12 @@
+/**
+ * Accessibility floors for native iOS prototypes. Small, fixed values that don't
+ * belong to a theme — they hold across light/dark and every palette.
+ */
+export const a11y = {
+  /** Apple's Human Interface minimum for a comfortable tap target, in points. */
+  minTapTarget: 44,
+  /** WCAG AA contrast floor for normal-size text (foreground vs background). */
+  minTextContrast: 4.5,
+  /** WCAG AA contrast floor for large text (≥ 24pt, or 19pt bold). */
+  minLargeTextContrast: 3,
+} as const;

package/template/components/proto/gestures/index.ts

@@ -1,4 +1,5 @@
 export {
+  default as Animated,
   default as AnimatedView,
   useSharedValue,
   useAnimatedStyle,
@@ -12,10 +13,13 @@ export {
   withRepeat,
   cancelAnimation,
   interpolate,
+  interpolateColor,
   Extrapolation,
   Easing,
   runOnJS,
   runOnUI,
 } from 'react-native-reanimated';
 
+export type { SharedValue } from 'react-native-reanimated';
+
 export { Gesture, GestureDetector, GestureHandlerRootView } from 'react-native-gesture-handler';

package/template/components/proto/index.ts

@@ -8,4 +8,6 @@ export { Toggle, type ToggleProps } from './Toggle';
 export { Divider } from './Divider';
 export { Modal, type ModalProps } from './Modal';
 export { useTheme, useAccent } from './useTheme';
+export { mock } from './mock';
+export { a11y } from './a11y';
 export type { Theme, ThemeName, ThemeOverrides, ProtoConfig } from './types';

package/template/components/proto/mock.ts

@@ -0,0 +1,13 @@
+/**
+ * Marks a value as placeholder/mock data — not yet wired to a real source.
+ *
+ * It's an identity function: it returns exactly what you pass in, so wrapping
+ * a value changes nothing at runtime. Its job is to make stubbed data obvious
+ * at a glance (and greppable) so it's never shipped believing it's real. When
+ * the value gets wired to a live source, drop the `mock()` wrapper.
+ *
+ *   const conditions = mock({ wave: '0.8m', wind: '8 km/h' });
+ */
+export function mock<T>(value: T): T {
+  return value;
+}

package/template/components/proto/svg/index.ts

@@ -0,0 +1,23 @@
+export {
+  default as Svg,
+  Circle,
+  Ellipse,
+  G,
+  Line,
+  Path,
+  Polygon,
+  Polyline,
+  Rect,
+  Use,
+  Defs,
+  LinearGradient,
+  RadialGradient,
+  Stop,
+  ClipPath,
+  Mask,
+  Pattern,
+  Text as SvgText,
+  TSpan,
+  TextPath,
+  Image as SvgImage,
+} from 'react-native-svg';

package/template/components/proto/tokens/base.ts

@@ -0,0 +1,75 @@
+import type { Theme } from '../types';
+
+export const base: Theme = {
+  surface: {
+    primary: '#FFFFFF',
+    secondary: '#F2F2F7',
+    card: '#FFFFFF',
+    nav: '#FFFFFF',
+  },
+  text: {
+    primary: '#000000',
+    secondary: 'rgba(0, 0, 0, 0.6)',
+    tertiary: 'rgba(0, 0, 0, 0.4)',
+    destructive: '#D70015',
+  },
+  blur: {
+    nav: 0,
+    card: 0,
+    modal: 0,
+  },
+  border: {
+    default: 'rgba(0, 0, 0, 0.1)',
+    strong: 'rgba(0, 0, 0, 0.2)',
+  },
+  radius: {
+    card: 12,
+    button: 10,
+    nav: 0,
+    modal: 24,
+  },
+  space: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+};
+
+export const baseDark: Theme = {
+  surface: {
+    primary: '#000000',
+    secondary: '#1C1C1E',
+    card: '#1C1C1E',
+    nav: '#000000',
+  },
+  text: {
+    primary: '#FFFFFF',
+    secondary: 'rgba(255, 255, 255, 0.6)',
+    tertiary: 'rgba(255, 255, 255, 0.4)',
+    destructive: '#FF453A',
+  },
+  blur: {
+    nav: 0,
+    card: 0,
+    modal: 0,
+  },
+  border: {
+    default: 'rgba(255, 255, 255, 0.15)',
+    strong: 'rgba(255, 255, 255, 0.3)',
+  },
+  radius: {
+    card: 12,
+    button: 10,
+    nav: 0,
+    modal: 24,
+  },
+  space: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+};

package/template/components/proto/tokens/liquidGlass.ts

@@ -36,3 +36,40 @@ export const liquidGlass: Theme = {
     xl: 32,
   },
 };
+
+export const liquidGlassDark: Theme = {
+  surface: {
+    primary: 'rgba(28, 28, 30, 0.72)',
+    secondary: 'rgba(28, 28, 30, 0.48)',
+    card: '#1c1c1e',
+    nav: 'rgba(28, 28, 30, 0.82)',
+  },
+  text: {
+    primary: '#FFFFFF',
+    secondary: 'rgba(255, 255, 255, 0.6)',
+    tertiary: 'rgba(255, 255, 255, 0.4)',
+    destructive: '#FF453A',
+  },
+  blur: {
+    nav: 40,
+    card: 20,
+    modal: 60,
+  },
+  border: {
+    default: 'rgba(255, 255, 255, 0.12)',
+    strong: 'rgba(255, 255, 255, 0.24)',
+  },
+  radius: {
+    card: 22,
+    button: 14,
+    nav: 0,
+    modal: 44,
+  },
+  space: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+};

package/template/components/proto/tokens/materialYou.ts

@@ -36,3 +36,40 @@ export const materialYou: Theme = {
     xl: 32,
   },
 };
+
+export const materialYouDark: Theme = {
+  surface: {
+    primary: '#1C1B1F',
+    secondary: '#2B2930',
+    card: '#211F26',
+    nav: '#1C1B1F',
+  },
+  text: {
+    primary: '#E6E1E5',
+    secondary: '#CAC4D0',
+    tertiary: '#938F99',
+    destructive: '#F2B8B5',
+  },
+  blur: {
+    nav: 0,
+    card: 0,
+    modal: 0,
+  },
+  border: {
+    default: '#49454F',
+    strong: '#938F99',
+  },
+  radius: {
+    card: 12,
+    button: 20,
+    nav: 0,
+    modal: 28,
+  },
+  space: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+};

package/template/components/proto/types.ts

@@ -1,4 +1,4 @@
-export type ThemeName = 'liquidGlass' | 'materialYou';
+export type ThemeName = 'liquidGlass' | 'materialYou' | 'base';
 
 export type Theme = {
   surface: {
@@ -49,6 +49,8 @@ export type ThemeOverrides = Partial<{
 export type ProtoConfig = {
   name?: string;
   theme?: ThemeName;
+  // 'system' (default) follows the device; 'light' / 'dark' pin the scheme.
+  colorScheme?: 'system' | 'light' | 'dark';
   accentColor?: string;
   tokens?: ThemeOverrides;
   screens?: { initial?: string };

package/template/components/proto/useTheme.ts

@@ -1,11 +1,20 @@
+import { useColorScheme } from 'react-native';
 import config from '../../proto.config.js';
-import { liquidGlass } from './tokens/liquidGlass';
-import { materialYou } from './tokens/materialYou';
+import { base, baseDark } from './tokens/base';
+import { liquidGlass, liquidGlassDark } from './tokens/liquidGlass';
+import { materialYou, materialYouDark } from './tokens/materialYou';
 import type { ProtoConfig, Theme, ThemeName, ThemeOverrides } from './types';
 
-const themes: Record<ThemeName, Theme> = {
+const lightThemes: Record<ThemeName, Theme> = {
   liquidGlass,
   materialYou,
+  base,
+};
+
+const darkThemes: Record<ThemeName, Theme> = {
+  liquidGlass: liquidGlassDark,
+  materialYou: materialYouDark,
+  base: baseDark,
 };
 
 function mergeTheme(base: Theme, overrides?: ThemeOverrides): Theme {
@@ -22,14 +31,21 @@ function mergeTheme(base: Theme, overrides?: ThemeOverrides): Theme {
 
 const cfg = config as ProtoConfig;
 
-// Named `use*` for ergonomics but reads module-level config; safe to call outside React.
+// A hook — it reads the system colour scheme so screens re-render when the device
+// switches between light and dark. Call it during render, like any hook.
+// `proto.config.js` can pin a scheme with `colorScheme: 'light' | 'dark'`; the
+// default ('system') follows the device.
 export function useTheme(): Theme {
+  const systemScheme = useColorScheme();
+  const preference = cfg.colorScheme ?? 'system';
+  const isDark = preference === 'dark' || (preference === 'system' && systemScheme === 'dark');
+
   const name: ThemeName = cfg.theme ?? 'liquidGlass';
-  const base = themes[name] ?? themes.liquidGlass;
+  const set = isDark ? darkThemes : lightThemes;
+  const base = set[name] ?? set.liquidGlass;
   return mergeTheme(base, cfg.tokens);
 }
 
-// Named `use*` for ergonomics but reads module-level config; safe to call outside React.
 export function useAccent(): string {
   return cfg.accentColor ?? '#007AFF';
 }

package/template/metro.config.js

@@ -2,4 +2,10 @@ const { getDefaultConfig } = require('expo/metro-config');
 
 const config = getDefaultConfig(__dirname);
 
+// Let screens import .svg files directly (import Logo from './logo.svg').
+// Managed by Proto — don't edit.
+config.transformer.babelTransformerPath = require.resolve('react-native-svg-transformer/expo');
+config.resolver.assetExts = config.resolver.assetExts.filter((ext) => ext !== 'svg');
+config.resolver.sourceExts = [...config.resolver.sourceExts, 'svg'];
+
 module.exports = config;

package/template/package.json

@@ -10,30 +10,45 @@
   },
   "dependencies": {
     "@expo/ui": "55.0.17",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "@shopify/flash-list": "2.0.2",
     "@shopify/react-native-skia": "2.4.18",
     "expo": "~55.0.26",
+    "expo-audio": "~55.0.14",
+    "expo-camera": "~55.0.18",
     "expo-clipboard": "~55.0.13",
     "expo-dev-client": "~55.0.35",
+    "expo-font": "~55.0.8",
     "expo-glass-effect": "~55.0.11",
     "expo-haptics": "~55.0.14",
+    "expo-image": "~55.0.11",
+    "expo-image-picker": "~55.0.20",
+    "expo-linear-gradient": "~55.0.14",
+    "expo-location": "~55.1.10",
+    "expo-maps": "~55.0.19",
     "expo-router": "~55.0.16",
     "expo-status-bar": "~55.0.6",
     "expo-symbols": "~55.0.9",
+    "expo-video": "~55.0.17",
     "lottie-react-native": "~7.3.4",
     "react": "19.2.0",
+    "react-dom": "19.2.0",
     "react-native": "0.83.6",
     "react-native-ease": "^0.7.2",
     "react-native-gesture-handler": "~2.30.1",
     "react-native-reanimated": "4.2.1",
     "react-native-safe-area-context": "5.6.2",
     "react-native-screens": "4.23.0",
+    "react-native-svg": "15.15.3",
+    "react-native-webview": "13.16.0",
     "react-native-worklets": "0.7.4"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",
-    "@sherizan/proto-cli": "^0.3.0",
+    "@sherizan/proto-cli": "^0.5.0",
     "@types/react": "~19.2.15",
     "babel-preset-expo": "~55.0.22",
+    "react-native-svg-transformer": "^1.5.0",
     "typescript": "^5.9.2"
   }
 }

package/template/screens/Home.tsx

@@ -2,12 +2,13 @@ import { useEffect, useState } from 'react';
 import { Pressable } from 'react-native';
 import * as Clipboard from 'expo-clipboard';
 import * as Haptics from 'expo-haptics';
-import Animated, {
+import {
+  Animated,
   useSharedValue,
   useAnimatedStyle,
   withTiming,
   Easing,
-} from 'react-native-reanimated';
+} from '../components/proto/gestures';
 import { Screen, Stack, Row, Text, Card, Divider } from '../components/proto';
 
 const STEPS = [