create-proto 0.1.0

package/template/CLAUDE.md

@@ -0,0 +1,71 @@
+# Proto Project — Claude Code Instructions
+
+You are the design tool inside a Proto project. The iOS Simulator is the canvas. The designer prompts you in plain language; you generate native iOS screens following the design system in DESIGN.md. Designers never touch files.
+
+## Three rules
+
+**1. Native iOS first.** Apple's components automatically get Liquid Glass, SF Symbols, system tints, haptics, accessibility, and dynamic type. Always prefer them when they exist:
+
+| Need | Use |
+|---|---|
+| Tab bar | `expo-router/unstable-native-tabs` (`NativeTabs` + `Icon sf={{default, selected}}` in `app/_layout.tsx`) |
+| SF Symbol icon | `expo-symbols` `SymbolView` |
+| System button | `@expo/ui/swift-ui` `Button` |
+| System toggle | `@expo/ui/swift-ui` `Toggle` |
+| Form / settings list | `@expo/ui/swift-ui` `Form` + `Section` |
+| Liquid Glass surface | `expo-glass-effect` `GlassView` directly |
+
+Never wrap a native component just to add Proto branding. Native > custom.
+
+**2. Proto primitives are fallbacks for what native doesn't ship.** Use `/components/proto` for layout helpers, generic surfaces, themed text — never to rebuild Apple-native UI.
+
+**3. DESIGN.md is the only source of design tokens.** Read it before every change. Never hardcode colour, spacing, radius, or typography. If the designer asks to change tokens, update DESIGN.md.
+
+If DESIGN.md's "Component Library" section names a third-party library (Tamagui, Gluestack, etc.), use that library's components first, Proto primitives as fallback. Otherwise use Proto primitives only.
+
+## File layout
+
+```
+/app/<route>.tsx       thin re-export of a screen (one-line wrapper)
+/app/_layout.tsx       NativeTabs root layout (when app has tabs)
+/screens/<Name>.tsx    actual screen component (PascalCase, default export)
+/components/shared/    designer-created shared components
+/components/proto/     Proto primitives — read-only, do not edit
+```
+
+For a new screen `screens/Settings.tsx`, add a matching `app/settings.tsx`:
+
+```tsx
+import Settings from '../screens/Settings';
+export default function SettingsRoute() { return <Settings />; }
+```
+
+Route filenames are lowercase kebab-case. Then add a one-line description to the Screens section of DESIGN.md.
+
+## Proto primitives (`/components/proto`)
+
+```
+Screen    title?, scrollable?        SafeAreaView + ScrollView wrapper
+Stack     gap?, padding?             vertical flex
+Row       gap?, align?               horizontal flex
+Text      size, color, style?        themed RN Text (sizes: title/headline/body/caption/label)
+Card      glass?, padding?           surface; glass={true} = real Liquid Glass on iOS 26+
+Button    label, variant?, onPress   custom animated button — for iOS system style use @expo/ui Button
+Toggle    label, value, onChange     themed RN Switch — for iOS system look use @expo/ui Toggle
+Divider   —                          1px separator
+Modal     title?, visible, ...       RN Modal wrapper
+```
+
+## When modifying a screen
+
+Read the file first, then rewrite the full file. Never partial edits or diffs.
+
+## Never
+
+- Never import from `react-native` directly — use a library, native iOS, or Proto fallback
+- Never build a custom tab bar — always `expo-router/unstable-native-tabs`
+- Never put logic in `/app/` files — they re-export a screen, nothing else
+- Never use SF Symbol private-use Unicode codepoints (like `''`) as text — they don't render in plain Text. Use `expo-symbols` `SymbolView` or native components that take SF symbol names
+- Never edit `/components/proto/`, `.proto/`, `app.config.js`, `babel.config.js`, `metro.config.js`
+- Never add a build step, dependency, or visual editor
+- Never tell the designer to open or edit a file manually

package/template/DESIGN.md

@@ -0,0 +1,53 @@
+# DESIGN.md
+> Source of truth for {{APP_NAME}}'s design system.
+> Update by prompting Claude Code: "update DESIGN.md, [what to change]"
+> Last updated: {{DATE}}
+
+## App
+- Name: {{APP_NAME}}
+- Theme: liquidGlass
+- Platform: iOS
+
+## Component Library
+- Package: proto (built-in)
+- Import from: ../components/proto
+- Fallback: proto
+
+## Colour
+- Accent: #007AFF
+- Surface primary: rgba(255,255,255,0.72)
+- Surface secondary: rgba(255,255,255,0.48)
+- Surface card: rgba(255,255,255,0.60)
+- Surface nav: rgba(255,255,255,0.82)
+- Text primary: #000000
+- Text secondary: rgba(0,0,0,0.5)
+- Text tertiary: rgba(0,0,0,0.3)
+- Destructive: #FF3B30
+
+## Typography
+- Title: 34px / bold / tracking -0.4
+- Headline: 22px / semibold / tracking -0.4
+- Body: 17px / regular
+- Caption: 12px / regular / text-secondary
+- Label: 13px / medium
+
+## Spacing
+- xs: 4 / sm: 8 / md: 16 / lg: 24 / xl: 32
+
+## Shape
+- Card radius: 22
+- Button radius: 14
+- Modal radius: 44
+- Input radius: 12
+
+## Effects
+- Card blur: 20
+- Nav blur: 40
+- Modal blur: 60
+- Border: rgba(255,255,255,0.4)
+
+## Components in use
+- Screen, Stack, Row, Text, Card, Button, Toggle, Nav, Modal, Divider
+
+## Screens
+- Home (initial) — starter screen

package/template/README.md

@@ -0,0 +1,6 @@
+# {{name}}
+
+Built with Proto.
+
+Run `proto start` to preview on your phone.
+Run `proto add "describe a screen"` to generate a new screen.

package/template/app/index.tsx

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

package/template/app.config.js

@@ -0,0 +1 @@
+module.exports = require('./.proto/expo-config/app.json');

package/template/babel.config.js

@@ -0,0 +1,7 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: [require.resolve('react-native-worklets/plugin')],
+  };
+};

package/template/components/proto/Button.tsx

@@ -0,0 +1,61 @@
+import { Pressable, type ViewStyle } from 'react-native';
+import Animated, { useSharedValue, useAnimatedStyle, withTiming } from 'react-native-reanimated';
+import * as Haptics from 'expo-haptics';
+import { useTheme, useAccent } from './useTheme';
+import { Text } from './Text';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
+
+export type ButtonProps = {
+  label: string;
+  variant?: ButtonVariant;
+  onPress?: () => void;
+};
+
+export function Button({ label, variant = 'primary', onPress }: ButtonProps) {
+  const theme = useTheme();
+  const accent = useAccent();
+  const scale = useSharedValue(1);
+
+  const animated = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }));
+
+  const handlePressIn = () => {
+    scale.value = withTiming(0.96, { duration: 80 });
+  };
+  const handlePressOut = () => {
+    scale.value = withTiming(1, { duration: 120 });
+  };
+  const handlePress = () => {
+    Haptics.selectionAsync().catch(() => {});
+    onPress?.();
+  };
+
+  const palette: Record<ButtonVariant, { bg: string; fg: string }> = {
+    primary: { bg: accent, fg: '#FFFFFF' },
+    secondary: { bg: theme.surface.secondary, fg: theme.text.primary },
+    ghost: { bg: 'transparent', fg: accent },
+    destructive: { bg: theme.text.destructive, fg: '#FFFFFF' },
+  };
+  const { bg, fg } = palette[variant];
+
+  const baseStyle: ViewStyle = {
+    backgroundColor: bg,
+    borderRadius: theme.radius.button,
+    paddingVertical: theme.space.sm + 4,
+    paddingHorizontal: theme.space.md,
+    alignItems: 'center',
+    justifyContent: 'center',
+  };
+
+  return (
+    <Pressable onPressIn={handlePressIn} onPressOut={handlePressOut} onPress={handlePress}>
+      <Animated.View style={[baseStyle, animated]}>
+        <Text size="label" style={{ color: fg }}>
+          {label}
+        </Text>
+      </Animated.View>
+    </Pressable>
+  );
+}

package/template/components/proto/Card.tsx

@@ -0,0 +1,63 @@
+import { View } from 'react-native';
+import { BlurView } from 'expo-blur';
+import { GlassView, isLiquidGlassAvailable } from 'expo-glass-effect';
+import type { ReactNode } from 'react';
+import { useTheme } from './useTheme';
+
+export type CardProps = {
+  glass?: boolean;
+  padding?: number;
+  children?: ReactNode;
+};
+
+export function Card({ glass = false, padding, children }: CardProps) {
+  const theme = useTheme();
+  const pad = padding ?? theme.space.md;
+
+  if (glass) {
+    if (isLiquidGlassAvailable()) {
+      return (
+        <GlassView
+          style={{
+            borderRadius: theme.radius.card,
+            borderWidth: 1,
+            borderColor: theme.border.default,
+            padding: pad,
+            overflow: 'hidden',
+          }}
+        >
+          {children}
+        </GlassView>
+      );
+    }
+    return (
+      <View
+        style={{
+          borderRadius: theme.radius.card,
+          overflow: 'hidden',
+          borderWidth: 1,
+          borderColor: theme.border.default,
+          backgroundColor: theme.surface.card,
+        }}
+      >
+        <BlurView intensity={theme.blur.card} tint="light" style={{ padding: pad }}>
+          {children}
+        </BlurView>
+      </View>
+    );
+  }
+
+  return (
+    <View
+      style={{
+        backgroundColor: theme.surface.card,
+        borderRadius: theme.radius.card,
+        borderWidth: 1,
+        borderColor: theme.border.default,
+        padding: pad,
+      }}
+    >
+      {children}
+    </View>
+  );
+}

package/template/components/proto/Divider.tsx

@@ -0,0 +1,15 @@
+import { View } from 'react-native';
+import { useTheme } from './useTheme';
+
+export function Divider() {
+  const theme = useTheme();
+  return (
+    <View
+      style={{
+        height: 1,
+        width: '100%',
+        backgroundColor: theme.border.default,
+      }}
+    />
+  );
+}

package/template/components/proto/Modal.tsx

@@ -0,0 +1,43 @@
+import { Modal as RNModal, Pressable, View } from 'react-native';
+import type { ReactNode } from 'react';
+import { useTheme } from './useTheme';
+import { Text } from './Text';
+
+export type ModalProps = {
+  title: string;
+  visible: boolean;
+  onClose?: () => void;
+  children?: ReactNode;
+};
+
+export function Modal({ title, visible, onClose, children }: ModalProps) {
+  const theme = useTheme();
+  return (
+    <RNModal
+      visible={visible}
+      transparent
+      animationType="slide"
+      onRequestClose={onClose}
+    >
+      <Pressable
+        onPress={onClose}
+        style={{ flex: 1, backgroundColor: 'rgba(0, 0, 0, 0.4)' }}
+      >
+        <Pressable
+          onPress={() => {}}
+          style={{
+            marginTop: 'auto',
+            backgroundColor: theme.surface.primary,
+            borderTopLeftRadius: theme.radius.modal,
+            borderTopRightRadius: theme.radius.modal,
+            padding: theme.space.lg,
+            gap: theme.space.md,
+          }}
+        >
+          <Text size="headline">{title}</Text>
+          {children}
+        </Pressable>
+      </Pressable>
+    </RNModal>
+  );
+}

package/template/components/proto/Row.tsx

@@ -0,0 +1,28 @@
+import { View, type ViewProps } from 'react-native';
+import type { ReactNode } from 'react';
+
+export type RowProps = {
+  gap?: number;
+  align?: 'start' | 'center' | 'end';
+  children?: ReactNode;
+  style?: ViewProps['style'];
+};
+
+const alignMap = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+} as const;
+
+export function Row({ gap = 0, align = 'start', style, children }: RowProps) {
+  return (
+    <View
+      style={[
+        { flexDirection: 'row', alignItems: alignMap[align], gap },
+        style,
+      ]}
+    >
+      {children}
+    </View>
+  );
+}

package/template/components/proto/Screen.tsx

@@ -0,0 +1,38 @@
+import { ScrollView, View } from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import type { ReactNode } from 'react';
+import { useTheme } from './useTheme';
+import { Text } from './Text';
+
+export type ScreenProps = {
+  title?: string;
+  scrollable?: boolean;
+  children?: ReactNode;
+};
+
+export function Screen({ title, scrollable = true, children }: ScreenProps) {
+  const theme = useTheme();
+  const Body = scrollable ? ScrollView : View;
+  return (
+    <SafeAreaView
+      style={{ flex: 1, backgroundColor: theme.surface.primary }}
+      edges={['top', 'left', 'right']}
+    >
+      {title ? (
+        <View style={{ paddingHorizontal: theme.space.md, paddingTop: theme.space.md, paddingBottom: theme.space.sm }}>
+          <Text size="title">{title}</Text>
+        </View>
+      ) : null}
+      <Body
+        style={{ flex: 1 }}
+        contentContainerStyle={
+          scrollable
+            ? { padding: theme.space.md, gap: theme.space.md }
+            : undefined
+        }
+      >
+        {scrollable ? children : <View style={{ flex: 1, padding: theme.space.md, gap: theme.space.md }}>{children}</View>}
+      </Body>
+    </SafeAreaView>
+  );
+}

package/template/components/proto/Stack.tsx

@@ -0,0 +1,17 @@
+import { View, type ViewProps } from 'react-native';
+import type { ReactNode } from 'react';
+
+export type StackProps = {
+  gap?: number;
+  padding?: number;
+  children?: ReactNode;
+  style?: ViewProps['style'];
+};
+
+export function Stack({ gap = 0, padding = 0, style, children }: StackProps) {
+  return (
+    <View style={[{ flexDirection: 'column', gap, padding }, style]}>
+      {children}
+    </View>
+  );
+}

package/template/components/proto/Text.tsx

@@ -0,0 +1,37 @@
+import { Text as RNText, type TextProps as RNTextProps, type TextStyle } from 'react-native';
+import type { ReactNode } from 'react';
+import { useTheme, useAccent } from './useTheme';
+
+export type TextSize = 'title' | 'headline' | 'body' | 'caption' | 'label';
+export type TextColor = 'primary' | 'secondary' | 'accent' | 'destructive';
+
+export type TextProps = {
+  size?: TextSize;
+  color?: TextColor;
+  children?: ReactNode;
+  style?: RNTextProps['style'];
+};
+
+const sizeMap: Record<TextSize, { fontSize: number; fontWeight: TextStyle['fontWeight'] }> = {
+  title: { fontSize: 34, fontWeight: '700' },
+  headline: { fontSize: 22, fontWeight: '600' },
+  body: { fontSize: 17, fontWeight: '400' },
+  caption: { fontSize: 13, fontWeight: '400' },
+  label: { fontSize: 13, fontWeight: '600' },
+};
+
+export function Text({ size = 'body', color = 'primary', style, children }: TextProps) {
+  const theme = useTheme();
+  const accent = useAccent();
+  const palette: Record<TextColor, string> = {
+    primary: theme.text.primary,
+    secondary: theme.text.secondary,
+    accent,
+    destructive: theme.text.destructive,
+  };
+  return (
+    <RNText style={[sizeMap[size], { color: palette[color] }, style]}>
+      {children}
+    </RNText>
+  );
+}

package/template/components/proto/Toggle.tsx

@@ -0,0 +1,40 @@
+import { Platform, Switch as RNSwitch, View } from 'react-native';
+import { Host, Toggle as SwiftUIToggle } from '@expo/ui/swift-ui';
+import { useAccent, useTheme } from './useTheme';
+import { Text } from './Text';
+
+export type ToggleProps = {
+  label: string;
+  value: boolean;
+  onChange?: (value: boolean) => void;
+};
+
+export function Toggle({ label, value, onChange }: ToggleProps) {
+  const theme = useTheme();
+  const accent = useAccent();
+
+  return (
+    <View
+      style={{
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        paddingVertical: theme.space.sm,
+      }}
+    >
+      <Text size="body">{label}</Text>
+      {Platform.OS === 'ios' ? (
+        <Host matchContents>
+          <SwiftUIToggle isOn={value} onIsOnChange={(next) => onChange?.(next)} />
+        </Host>
+      ) : (
+        <RNSwitch
+          value={value}
+          onValueChange={onChange}
+          trackColor={{ false: theme.border.default, true: accent }}
+          thumbColor="#FFFFFF"
+        />
+      )}
+    </View>
+  );
+}

package/template/components/proto/index.ts

@@ -0,0 +1,11 @@
+export { Screen, type ScreenProps } from './Screen';
+export { Stack, type StackProps } from './Stack';
+export { Row, type RowProps } from './Row';
+export { Text, type TextProps, type TextSize, type TextColor } from './Text';
+export { Card, type CardProps } from './Card';
+export { Button, type ButtonProps, type ButtonVariant } from './Button';
+export { Toggle, type ToggleProps } from './Toggle';
+export { Divider } from './Divider';
+export { Modal, type ModalProps } from './Modal';
+export { useTheme, useAccent } from './useTheme';
+export type { Theme, ThemeName, ThemeOverrides, ProtoConfig } from './types';

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

@@ -0,0 +1,38 @@
+import type { Theme } from '../types';
+
+export const liquidGlass: Theme = {
+  surface: {
+    primary: 'rgba(255, 255, 255, 0.72)',
+    secondary: 'rgba(255, 255, 255, 0.48)',
+    card: 'rgba(255, 255, 255, 0.6)',
+    nav: 'rgba(255, 255, 255, 0.82)',
+  },
+  text: {
+    primary: '#000000',
+    secondary: 'rgba(0, 0, 0, 0.5)',
+    tertiary: 'rgba(0, 0, 0, 0.3)',
+    destructive: '#FF3B30',
+  },
+  blur: {
+    nav: 40,
+    card: 20,
+    modal: 60,
+  },
+  border: {
+    default: 'rgba(255, 255, 255, 0.4)',
+    strong: 'rgba(255, 255, 255, 0.7)',
+  },
+  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

@@ -0,0 +1,38 @@
+import type { Theme } from '../types';
+
+export const materialYou: Theme = {
+  surface: {
+    primary: '#FFFBFE',
+    secondary: '#E6E1E5',
+    card: '#F4EFF4',
+    nav: '#FFFBFE',
+  },
+  text: {
+    primary: '#1C1B1F',
+    secondary: '#49454F',
+    tertiary: '#79747E',
+    destructive: '#B3261E',
+  },
+  blur: {
+    nav: 0,
+    card: 0,
+    modal: 0,
+  },
+  border: {
+    default: '#CAC4D0',
+    strong: '#79747E',
+  },
+  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

@@ -0,0 +1,55 @@
+export type ThemeName = 'liquidGlass' | 'materialYou';
+
+export type Theme = {
+  surface: {
+    primary: string;
+    secondary: string;
+    card: string;
+    nav: string;
+  };
+  text: {
+    primary: string;
+    secondary: string;
+    tertiary: string;
+    destructive: string;
+  };
+  blur: {
+    nav: number;
+    card: number;
+    modal: number;
+  };
+  border: {
+    default: string;
+    strong: string;
+  };
+  radius: {
+    card: number;
+    button: number;
+    nav: number;
+    modal: number;
+  };
+  space: {
+    xs: number;
+    sm: number;
+    md: number;
+    lg: number;
+    xl: number;
+  };
+};
+
+export type ThemeOverrides = Partial<{
+  surface: Partial<Theme['surface']>;
+  text: Partial<Theme['text']>;
+  blur: Partial<Theme['blur']>;
+  border: Partial<Theme['border']>;
+  radius: Partial<Theme['radius']>;
+  space: Partial<Theme['space']>;
+}>;
+
+export type ProtoConfig = {
+  name?: string;
+  theme?: ThemeName;
+  accentColor?: string;
+  tokens?: ThemeOverrides;
+  screens?: { initial?: string };
+};