create-proto 0.8.3 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-proto",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Scaffold a new Proto prototype: `npm create proto@latest myapp`. Describe a screen, watch your prototype run natively on iPhone — designer-first, paired with Claude Code.",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "fs-extra": "^11.2.0",
     "qrcode-terminal": "^0.12.0",
     "validate-npm-package-name": "^5.0.1",
-    "@sherizan/proto-cli": "^0.8.18"
+    "@sherizan/proto-cli": "^0.8.20"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/template/AGENTS.md

@@ -3,8 +3,9 @@
 You're the design tool inside a Prototo project. The designer prompts in plain language; you build native iOS screens. The iOS Simulator is the canvas. Designers never touch files: they prompt, you write.
 
 ## Read first
-- `DESIGN.md` — tokens and the project's decisions. Keep it alive: update it when colors, type, spacing, shape or accent change, and add a one-line entry to its Screens section for every new screen.
+- `DESIGN.md` — tokens and the project's decisions. Keep it alive: update it when colors, type, spacing, shape or accent change, and add a one-line entry to its Screens section for every new screen. Brand changes go in `proto.config.js` too (see Branding).
 - `/screens/` — what already exists.
+- `screens/Components.tsx` — every component running live in this project's brand: the working reference for each prop. Delete it and `app/components.tsx` (plus Home's "See the components" button) only if the designer asks.
 
 ## Building blocks (use whatever fits)
 
@@ -43,7 +44,7 @@ You're the design tool inside a Prototo project. The designer prompts in plain l
 
 **Sensors** — `expo-sensors` (`Accelerometer`, `Gyroscope`, `DeviceMotion`, `Magnetometer`, `Barometer`, `Pedometer`). Guard with `isAvailableAsync()` and render a still fallback: the Simulator never fires motion, only a real iPhone does (via a published link in the Prototo app). Call `requestPermissionsAsync()` before `DeviceMotion` or `Pedometer`.
 
-**Custom** — when nothing fits, write it with React Native in `/components/shared/`. The designer's vision wins.
+**Custom** — when nothing fits, write it with React Native in `/components/shared/`. The designer's vision wins. Every component you add there gets a live example, with its name as the label, in the "Your components" section of `screens/Components.tsx`, so the designer (and their team, after a remix) can see and reuse it.
 
 **Adding a package** — `npx proto add <package>` only (never `npm install` / `pnpm add`; bare `proto` isn't on PATH). It says when a package needs native code Prototo doesn't bundle.
 
@@ -84,7 +85,9 @@ export default function Layout() {
 
 ## Theme, dark mode, accessibility
 - Colors come from `useTheme()` (`theme.surface.*`, `theme.text.*`, `theme.border.*`): light/dark is automatic, so no hardcoded hex. `colorScheme: 'light' | 'dark'` in `proto.config.js` pins a scheme.
-- Custom brand colors, fonts or constants live **once** in `/components/shared/theme.ts` (define light + dark variants if needed). Never paste a palette into more than one screen; lift any you find.
+- Spacing comes from `theme.space` (`xs` 4 · `sm` 8 · `md` 16 · `lg` 24 · `xl` 32) for every `gap`, `padding` and margin: no raw numbers, so a brand spacing change reaches every screen.
+- **Branding** — accent, theme, colors, radius and spacing live in `proto.config.js`, which every component reads: `accentColor`, `theme` (`'liquidGlass'`\|`'base'`), and `tokens` overrides (`surface`, `text`, `border`, `radius`, `space`, `blur`; same keys as `useTheme()`). A brand prompt edits `proto.config.js` AND DESIGN.md in the same change, then `get_simulator_screenshot` of the Components screen to check it. Editing DESIGN.md alone changes nothing on screen.
+- Brand values `proto.config.js` has no key for (a font, an extra color, constants) live **once** in `/components/shared/theme.ts` (define light + dark variants if needed). Never paste a palette into more than one screen; lift any you find.
 - Text scales with Dynamic Type: never disable it, avoid fixed heights on text containers.
 - `a11y` from `../components/proto`: tap targets ≥ `a11y.minTapTarget` (44pt), contrast ≥ `a11y.minTextContrast`, in light and dark.
 

package/template/app/_layout.tsx

@@ -15,6 +15,7 @@ export default function RootLayout() {
             headerLargeTitle: true,
           }}
         />
+        <Stack.Screen name="components" options={{ title: 'Components', headerLargeTitle: true }} />
       </Stack>
     </TouchDots>
   );

package/template/app/components.tsx

@@ -0,0 +1,5 @@
+import Components from '../screens/Components';
+
+export default function ComponentsRoute() {
+  return <Components />;
+}

package/template/components/proto/Screen.tsx

@@ -43,14 +43,22 @@ export function Screen({ scrollable = true, gradient, children }: ScreenProps) {
   ) : null;
 
   if (scrollable) {
+    // A hex wash paints the ScrollView's own background, fixed to the viewport, so it reaches the
+    // bottom edge under the home indicator and in the bounce. A wash inside the content stops at the
+    // content box, which iOS insets above the home indicator.
+    const hexWash = washColor && /^#[0-9a-f]{6}$/i.test(washColor);
     return (
       <ScrollView
-        style={{ flex: 1, backgroundColor: theme.surface.primary }}
-        // With a wash the content box fills the viewport so the gradient reaches the bottom edge.
-        contentContainerStyle={{ padding, gap: padding, flexGrow: washColor ? 1 : undefined }}
+        style={{
+          flex: 1,
+          backgroundColor: theme.surface.primary,
+          experimental_backgroundImage: hexWash ? `linear-gradient(to bottom, ${washColor}00, ${washColor}1A)` : undefined,
+        }}
+        // ponytail: a named colour wash still rides inside the content box (small gap at the bottom).
+        contentContainerStyle={{ padding, gap: padding, flexGrow: washColor && !hexWash ? 1 : undefined }}
         contentInsetAdjustmentBehavior="automatic"
       >
-        {wash}
+        {hexWash ? null : wash}
         {children}
       </ScrollView>
     );

package/template/screens/Components.tsx

@@ -0,0 +1,264 @@
+import { useState, Fragment } from 'react';
+import { SymbolView } from 'expo-symbols';
+import {
+  Screen,
+  Stack,
+  Row,
+  Text,
+  Card,
+  Button,
+  Toggle,
+  Slider,
+  Stepper,
+  Picker,
+  DatePicker,
+  Menu,
+  Input,
+  Modal,
+  Alert,
+  Divider,
+  Lottie,
+  useTheme,
+  useAccent,
+} from '../components/proto';
+
+function Section({ title, note, children }) {
+  const { space } = useTheme();
+  const items = Array.isArray(children) ? children.filter(Boolean) : [children];
+  return (
+    <Stack gap={space.sm}>
+      <Text size="label" color="secondary" style={{ paddingHorizontal: space.xs }}>
+        {title.toUpperCase()}
+      </Text>
+      <Card glass padding={space.lg}>
+        <Stack gap={space.lg}>
+          {items.map((item, index) => (
+            <Fragment key={index}>
+              {index > 0 ? <Divider /> : null}
+              {item}
+            </Fragment>
+          ))}
+        </Stack>
+      </Card>
+      {note ? (
+        <Text size="caption" color="secondary" style={{ paddingHorizontal: space.xs }}>
+          {note}
+        </Text>
+      ) : null}
+    </Stack>
+  );
+}
+
+function Item({ name, children }) {
+  const { space } = useTheme();
+  return (
+    <Stack gap={space.sm}>
+      <Text size="caption" color="secondary">
+        {name}
+      </Text>
+      {children}
+    </Stack>
+  );
+}
+
+function Pair({ name, value }) {
+  return (
+    <Row align="center" style={{ justifyContent: 'space-between' }}>
+      <Text size="body">{name}</Text>
+      <Text size="body" color="secondary">
+        {value}
+      </Text>
+    </Row>
+  );
+}
+
+function Swatch({ name, color }) {
+  const { space } = useTheme();
+  return (
+    <Stack gap={space.xs} align="center">
+      <SymbolView name="circle.fill" size={40} tintColor={color} />
+      <Text size="caption" color="secondary">
+        {name}
+      </Text>
+    </Stack>
+  );
+}
+
+export default function Components() {
+  const theme = useTheme();
+  const accent = useAccent();
+  const [toggle, setToggle] = useState(true);
+  const [slider, setSlider] = useState(0.4);
+  const [count, setCount] = useState(2);
+  const [segment, setSegment] = useState('Day');
+  const [size, setSize] = useState('Medium');
+  const [flavour, setFlavour] = useState('Mango');
+  const [date, setDate] = useState(new Date());
+  const [text, setText] = useState('');
+  const [sheet, setSheet] = useState(false);
+  const [alert, setAlert] = useState(false);
+
+  return (
+    <Screen scrollable gradient>
+      <Stack gap={theme.space.xl}>
+        <Text size="body" color="secondary" style={{ paddingHorizontal: theme.space.xs }}>
+          Everything your agent builds with, in your brand. Name any of these in a prompt.
+        </Text>
+
+        <Section title="Your brand" note="Your brand lives in DESIGN.md. Ask your agent to change it and everything here follows.">
+          <Row style={{ justifyContent: 'space-between' }}>
+            <Swatch name="Accent" color={accent} />
+            <Swatch name="Text" color={theme.text.primary} />
+            <Swatch name="Secondary" color={theme.text.secondary} />
+            <Swatch name="Tertiary" color={theme.text.tertiary} />
+            <Swatch name="Destructive" color={theme.text.destructive} />
+          </Row>
+          <Stack gap={theme.space.md}>
+            <Row align="center" style={{ justifyContent: 'space-between' }}>
+              <Text size="title">Title</Text>
+              <Text size="caption" color="secondary">title</Text>
+            </Row>
+            <Row align="center" style={{ justifyContent: 'space-between' }}>
+              <Text size="headline">Headline</Text>
+              <Text size="caption" color="secondary">headline</Text>
+            </Row>
+            <Row align="center" style={{ justifyContent: 'space-between' }}>
+              <Text size="body">Body</Text>
+              <Text size="caption" color="secondary">body</Text>
+            </Row>
+            <Row align="center" style={{ justifyContent: 'space-between' }}>
+              <Text size="label">Label</Text>
+              <Text size="caption" color="secondary">label</Text>
+            </Row>
+            <Row align="center" style={{ justifyContent: 'space-between' }}>
+              <Text size="caption">Caption</Text>
+              <Text size="caption" color="secondary">caption</Text>
+            </Row>
+          </Stack>
+          <Stack gap={theme.space.md}>
+            <Pair name="Card corners" value={`${theme.radius.card}`} />
+            <Pair name="Button corners" value={`${theme.radius.button}`} />
+            <Pair
+              name="Spacing"
+              value={`${theme.space.xs} · ${theme.space.sm} · ${theme.space.md} · ${theme.space.lg} · ${theme.space.xl}`}
+            />
+          </Stack>
+        </Section>
+
+        <Section title="Your components" note="Components you build for this prototype show up here, ready to reuse.">
+          <Text size="body" color="secondary">
+            None yet
+          </Text>
+        </Section>
+
+        <Section title="Buttons">
+          <Item name="Button">
+            <Stack gap={theme.space.sm}>
+              <Button label="Primary" />
+              <Button label="Secondary" variant="secondary" />
+              <Button label="Destructive" variant="destructive" />
+              <Button label="Ghost" variant="ghost" />
+            </Stack>
+          </Item>
+          <Item name="Button with a symbol">
+            <Button label="Add to favourites" variant="secondary" systemImage="star.fill" />
+          </Item>
+          <Item name="Menu">
+            <Row>
+              <Menu
+                label="Options"
+                systemImage="ellipsis.circle"
+                items={[
+                  { label: 'Share', systemImage: 'square.and.arrow.up' },
+                  { label: 'Duplicate', systemImage: 'plus.square.on.square' },
+                  { label: 'Delete', systemImage: 'trash', destructive: true },
+                ]}
+              />
+            </Row>
+          </Item>
+        </Section>
+
+        <Section title="Controls">
+          <Item name="Toggle">
+            <Toggle label="Notifications" value={toggle} onChange={setToggle} />
+          </Item>
+          <Item name="Slider">
+            <Slider value={slider} onChange={setSlider} />
+          </Item>
+          <Item name="Stepper">
+            <Stepper label={`Guests: ${count}`} value={count} onChange={setCount} min={1} max={8} />
+          </Item>
+          <Item name="DatePicker">
+            <DatePicker label="Check in" value={date} onChange={setDate} />
+          </Item>
+          <Item name="Input">
+            <Input placeholder="Your name" value={text} onChangeText={setText} />
+          </Item>
+        </Section>
+
+        <Section title="Pickers">
+          <Item name="Picker">
+            <Picker options={['Day', 'Week', 'Month']} value={segment} onChange={setSegment} />
+          </Item>
+          <Item name="Picker menu">
+            <Picker variant="menu" label="Size" options={['Small', 'Medium', 'Large']} value={size} onChange={setSize} />
+          </Item>
+          <Item name="Picker wheel">
+            <Picker variant="wheel" options={['Mango', 'Lychee', 'Pandan', 'Durian']} value={flavour} onChange={setFlavour} />
+          </Item>
+        </Section>
+
+        <Section title="Overlays">
+          <Item name="Modal">
+            <Button label="Open a sheet" variant="secondary" onPress={() => setSheet(true)} />
+          </Item>
+          <Item name="Alert">
+            <Button label="Show an alert" variant="secondary" onPress={() => setAlert(true)} />
+          </Item>
+        </Section>
+
+        <Section title="Layout">
+          <Item name="Card">
+            <Card>
+              <Text size="body">A plain card</Text>
+            </Card>
+          </Item>
+          <Item name="Row">
+            <Row gap={theme.space.md}>
+              <Text size="body">One</Text>
+              <Text size="body">Two</Text>
+              <Text size="body">Three</Text>
+            </Row>
+          </Item>
+          <Item name="Divider">
+            <Divider label="or" />
+          </Item>
+        </Section>
+
+        <Section title="Motion">
+          <Item name="Lottie">
+            <Lottie source={require('../assets/lottie/logo-prototo.json')} style={{ width: 64, height: 64 }} />
+          </Item>
+        </Section>
+      </Stack>
+
+      <Modal title="A bottom sheet" visible={sheet} onClose={() => setSheet(false)}>
+        <Text size="body" color="secondary">
+          It fits its content. Swipe down to close.
+        </Text>
+        <Button label="Done" onPress={() => setSheet(false)} />
+      </Modal>
+
+      <Alert
+        title="Delete this draft?"
+        message="You can't undo this."
+        visible={alert}
+        onClose={() => setAlert(false)}
+        actions={[
+          { label: 'Cancel', cancel: true },
+          { label: 'Delete', destructive: true },
+        ]}
+      />
+    </Screen>
+  );
+}

package/template/screens/Home.tsx

@@ -1,5 +1,6 @@
 import { useEffect, type ReactNode } from 'react';
 import { SymbolView } from 'expo-symbols';
+import { router } from 'expo-router';
 import * as Clipboard from 'expo-clipboard';
 import * as Haptics from 'expo-haptics';
 import {
@@ -10,7 +11,7 @@ import {
   withTiming,
   Easing,
 } from '../components/proto/gestures';
-import { Screen, Stack, Row, Text, Card, Button, Divider, Lottie, useAccent } from '../components/proto';
+import { Screen, Stack, Row, Text, Card, Button, Divider, Lottie, useTheme, useAccent } from '../components/proto';
 
 // Prototo Desktop sets EXPO_PUBLIC_PROTO_DESKTOP=1 when it runs `proto start`
 // (Metro inlines it at bundle time). In the desktop the terminal sits beside
@@ -44,6 +45,7 @@ function Enter({ delay, children }: { delay: number; children: ReactNode }) {
 
 function ExampleCard({ example }: { example: (typeof EXAMPLES)[number] }) {
   const accent = useAccent();
+  const { space } = useTheme();
 
   const handleCopy = async () => {
     await Clipboard.setStringAsync(example.prompt);
@@ -51,10 +53,10 @@ function ExampleCard({ example }: { example: (typeof EXAMPLES)[number] }) {
   };
 
   return (
-    <Card glass padding={16}>
-      <Row gap={14} align="center">
+    <Card glass padding={space.md}>
+      <Row gap={space.md} align="center">
         <SymbolView name="text.bubble" size={22} tintColor={accent} />
-        <Stack gap={2} style={{ flex: 1 }}>
+        <Stack gap={space.xs} style={{ flex: 1 }}>
           <Text size="label" color="accent">
             {example.label}
           </Text>
@@ -71,22 +73,23 @@ function ExampleCard({ example }: { example: (typeof EXAMPLES)[number] }) {
 }
 
 export default function Home() {
+  const { space } = useTheme();
   return (
     <Screen scrollable gradient>
-      <Stack gap={24}>
+      <Stack gap={space.lg}>
         <Enter delay={0}>
-          <Card glass padding={24}>
-            <Row gap={16} align="center">
+          <Card glass padding={space.lg}>
+            <Row gap={space.md} align="center">
               <Lottie
                 source={require('../assets/lottie/logo-prototo.json')}
                 style={{ width: 48, height: 48 }}
               />
-              <Stack gap={4} style={{ flex: 1 }}>
+              <Stack gap={space.xs} style={{ flex: 1 }}>
                 <Text size="headline">You're in.</Text>
                 <Text size="body" color="secondary">
                   {IN_DESKTOP
                     ? 'Describe a screen in the terminal beside this preview. It appears here as it builds.'
-                    : `In a terminal: cd {{APP_NAME}} && claude (or codex). Then paste a prompt below.`}
+                    : 'Copy a prompt below, or just say what you want.'}
                 </Text>
               </Stack>
             </Row>
@@ -94,7 +97,7 @@ export default function Home() {
         </Enter>
 
         <Enter delay={120}>
-          <Stack gap={10}>
+          <Stack gap={space.sm}>
             <Text size="label" color="secondary">
               Try one of these
             </Text>
@@ -105,11 +108,19 @@ export default function Home() {
         </Enter>
 
         <Enter delay={240}>
-          <Stack gap={12}>
-            <Divider />
-            <Text size="caption" color="secondary">
-              Each prompt builds on the last. Prototo reads DESIGN.md before every change.
-            </Text>
+          <Stack gap={space.lg}>
+            <Stack gap={space.sm}>
+              <Divider />
+              <Text size="caption" color="secondary">
+                Each prompt builds on the last. Your design system lives in DESIGN.md, and your agent reads it before every change.
+              </Text>
+            </Stack>
+            <Button
+              label="See the components"
+              variant="secondary"
+              systemImage="square.grid.2x2"
+              onPress={() => router.push('/components')}
+            />
           </Stack>
         </Enter>
       </Stack>