@codeyam/codeyam-cli 0.1.0-staging.50df560 → 0.1.0-staging.5370992

package/codeyam-cli/templates/design-systems/mono-brutalist-design-system.md

@@ -0,0 +1,256 @@
+# Mono-Brutalist Design System
+
+> Raw, typographic, terminal-warm UI. Monospace identity, dashed borders, single mint-green accent. For any web or mobile app.
+
+## Philosophy
+
+Brutalism's exposed skeleton — visible grids, raw type, no embellishment — warmed with organic off-whites, sage greens, and monospaced type. Feels like a well-worn notebook: structured but human.
+
+**Rules:**
+
+1. Monospace font carries the identity — labels, tags, metadata, inputs, buttons, nav all use mono
+2. Dashed borders are the signature element — used on tags, chips, empty states, never on structural containers
+3. Single chromatic accent (mint green) — resist adding secondary colors
+4. Never use pure black (`#000`) or pure white (`#fff`) — everything lives between warm off-white and dark olive
+
+---
+
+## Colors
+
+### Light Mode
+
+```css
+[data-theme='light'] {
+  --bg-base: #eeece6; /* warm off-white page bg */
+  --bg-surface: #fafaf7; /* cards, panels */
+  --bg-surface-raised: #ffffff; /* modals, overlays */
+  --bg-inverse: #2d3228; /* dark olive — inverted accent blocks, headers */
+
+  --text-primary: #2d3228; /* headings, primary content */
+  --text-secondary: #555550; /* body, descriptions */
+  --text-muted: #777772; /* labels, metadata */
+  --text-faint: #999994; /* placeholders, disabled */
+
+  --border: #e2dfd6; /* solid borders — cards, panels, dividers */
+  --border-dashed: #999690; /* dashed borders — tags, chips, empty states */
+
+  --shadow-sm: none; /* no shadows in this system — borders do the work */
+  --shadow-md: none;
+}
+```
+
+### Dark Mode
+
+```css
+[data-theme='dark'] {
+  --bg-base: #1a1e18;
+  --bg-surface: #222820;
+  --bg-surface-raised: #2a3028;
+  --bg-inverse: #2d3228; /* unchanged — constant anchor */
+
+  --text-primary: #e0ddd6;
+  --text-secondary: #a8a89e;
+  --text-muted: #6a7a64;
+  --text-faint: #4a5a44;
+
+  --border: #2e3628;
+  --border-dashed: #3e4a38;
+  /* Accent unchanged. Inverse surfaces unchanged. */
+}
+```
+
+Respect `@media (prefers-color-scheme: dark)` on `:root:not([data-theme="light"])`.
+
+### Accents
+
+```css
+/* Mint green — the only chromatic accent. Unchanged between modes. */
+--accent: #b8e0a0; /* primary: on dark surfaces, active indicators */
+--accent-soft: #c5e8b0; /* light mode soft fill; dark mode: #1e3a18 */
+--accent-dark: #82b870; /* darker variant for emphasis */
+```
+
+### Semantic
+
+```css
+--success-bg: #dff0d4;
+--success-text: #3a5c2a;
+--danger-bg: #f0d4d4;
+--danger-text: #5c2a2a;
+/* Dark mode: --success-bg: #1e3018; --success-text: #82b870; */
+```
+
+### Ordered Palette
+
+```css
+/* Single-accent system — categorical sequence uses value/opacity variations */
+--palette-1: #2d3228; /* ink */
+--palette-2: #82b870; /* accent dark */
+--palette-3: #b8e0a0; /* accent */
+--palette-4: #555550; /* secondary */
+--palette-5: #999690; /* muted */
+```
+
+---
+
+## Typography
+
+**Font stack:** `'Courier New', Courier, monospace` (identity — labels, tags, inputs, buttons, nav), `system-ui, -apple-system, sans-serif` (headings and body prose only). Optional upgrade: `'DM Mono'` for mono.
+
+| Style       | Size                     | Weight | Font | Notes                                                        |
+| ----------- | ------------------------ | ------ | ---- | ------------------------------------------------------------ |
+| Display     | `clamp(28px, 5vw, 56px)` | 300    | Sans | `letter-spacing: -0.02em; line-height: 1.2`                  |
+| H1          | `clamp(22px, 3vw, 36px)` | 400    | Sans | `letter-spacing: -0.02em`                                    |
+| H2          | 18px                     | 500    | Sans | Card titles                                                  |
+| H3          | 14px                     | 500    | Sans | Panel titles                                                 |
+| Body        | 13px                     | 400    | Sans | `line-height: 1.6`                                           |
+| Mono L      | 13px                     | 400    | Mono | Large mono labels                                            |
+| Mono M      | 12px                     | 400    | Mono | Default — inputs, content text                               |
+| Mono S      | 11px                     | 400    | Mono | Tags, metadata, table cells. `letter-spacing: 0.03em`        |
+| Mono XS     | 10px                     | 400    | Mono | Section labels, footers. `uppercase; letter-spacing: 0.12em` |
+| Large Value | `clamp(28px, 4vw, 44px)` | 300    | Sans | Emphasized numbers. `letter-spacing: -0.02em`                |
+
+**Key distinctions:**
+
+- ALL CAPS labels always use `letter-spacing: 0.10em` minimum
+- Wrapping user-generated content in quotes (`"text like this"`) is a signature pattern
+- Mono for everything structural/interactive; sans only for headings and prose
+
+---
+
+## Spacing & Radius
+
+Base unit: 4px. Scale: 4, 8, 12, 16, 20, 24, 32, 40, 48px.
+
+| Context                | Value  |
+| ---------------------- | ------ |
+| Card padding (compact) | `16px` |
+| Card padding (default) | `24px` |
+| Grid gap (cards)       | 10px   |
+| Section gap            | 32px   |
+
+```css
+--radius-sm: 8px; /* badges */
+--radius-md: 12px; /* inputs, small cards */
+--radius-lg: 16px; /* cards, panels */
+--radius-xl: 20px; /* modals */
+--radius-pill: 100px; /* buttons, tag pills */
+```
+
+---
+
+## Layout
+
+### Common Patterns
+
+- **Sidebar/Header:** Dark olive (`--bg-inverse`), same in both modes — constant anchor
+- **Top bar:** Sticky, dark olive bg, mint accent for active nav
+- **Bottom nav (mobile):** Dark olive bg, mint accent active indicator
+- **Main content:** flex-1, `--bg-base`, 40px padding (desktop), 20px (mobile)
+
+### Navigation States
+
+- Section labels: Mono XS, uppercase, `letter-spacing: 0.12em`, `--text-muted`
+- Nav items: Mono M, `--text-secondary`. Hover → `--bg-surface` bg. Active → mint accent text on inverse bg
+- Dark olive header is always present — `--bg-inverse`, `z-index: 20`
+
+### Mobile / Small Viewport
+
+- Single column, 20px padding
+- Cards full-width, `--radius-lg`
+- Tag pills in horizontal scroll row (no wrap)
+- Tap targets minimum 44px height
+- Display type scales down via clamp
+
+---
+
+## Components
+
+### Card
+
+```css
+.card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  padding: 24px;
+}
+```
+
+**Variants:** `default` (surface), `inverted` (ink bg, no border), `accent` (accent-soft bg, accent border).
+
+**Interactive states:** hover → subtle bg shift only. No transforms, no shadows.
+
+**Card anatomy:** Label row (ALL CAPS mono) → content → footer (timestamp + tag pill).
+
+### Value Card
+
+Card with: label (Mono XS, uppercase), emphasized value (Large Value style), optional trend indicator (`--success-text` for up, `--danger-text` for down, italic). Stats row: grid with thin border gaps between cards.
+
+### Button
+
+```css
+.btn {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  padding: 12px 22px;
+  border-radius: var(--radius-pill);
+  letter-spacing: 0.04em;
+  cursor: pointer;
+}
+```
+
+| Variant   | Background     | Text             | Border                              |
+| --------- | -------------- | ---------------- | ----------------------------------- |
+| Primary   | `--bg-inverse` | `--accent`       | none                                |
+| Secondary | transparent    | `--text-primary` | `1.5px dashed var(--border-dashed)` |
+| Ghost     | transparent    | `--text-muted`   | `1px solid var(--border)`           |
+
+Primary: always dark bg + mint text. All buttons use mono font, pill radius.
+
+### Tag / Pill (signature element)
+
+`font-family: mono; font-size: 11px; padding: 4px 11px; border-radius: 100px; border: 1.5px dashed var(--border-dashed); letter-spacing: 0.03em; background: transparent`. Active → solid border + inverse bg + white text. Accent variant → accent-dark border + accent-dark text.
+
+### Badge
+
+`font-family: mono; font-size: 10px; padding: 3px 10px; border-radius: 100px; letter-spacing: 0.04em`. Variants: trending (inverse bg + accent text), rising (success bg + success text), default (base bg + muted text).
+
+### Input
+
+`font-family: mono; font-size: 12px; padding: 12px 16px; border-radius: var(--radius-md); border: 1px solid var(--border); background: var(--bg-base)`. Focus: `border-color: var(--border-dashed)`. Placeholder: `--text-faint`, mono.
+
+### Table
+
+Header: Mono XS uppercase labels, `--text-muted`. Rows: Mono S, `--text-secondary`, `border-bottom: 1px solid var(--border)`. Hover → `--bg-base`. Numbers: `--text-primary`, weight 500.
+
+### Empty State
+
+Centered dashed circle (`1.5px dotted var(--accent-dark)`, 50px, `+` inside) on accent-soft background. Lowercase conversational text: `"no items here yet"`.
+
+---
+
+## Motion
+
+```css
+--transition-fast: 100ms ease; /* button/tag hover */
+--transition-base: 120ms ease; /* card hover, general */
+--transition-slow: 200ms ease-out; /* modals, panels */
+```
+
+Grounded and minimal — things slide and fade, never bounce. No spring physics, parallax, rotation, or scale-up on hover. Page load: staggered fade-up, 40ms delay per item.
+
+---
+
+## Checklist
+
+- [ ] Background is warm off-white (`#eeece6`) or dark olive (`#1a1e18`) — never pure black or white
+- [ ] Monospace font on all labels, tags, inputs, buttons, and nav — sans only for headings/prose
+- [ ] Tags/pills use dashed borders — structural containers use solid borders
+- [ ] Only one chromatic accent (mint green) — no secondary colors
+- [ ] Primary buttons: dark bg + mint text, always pill-shaped
+- [ ] ALL CAPS labels have letter-spacing 0.10em+
+- [ ] Dark olive inverse surfaces are the same in both light and dark mode
+- [ ] No box-shadows — borders and background contrast only
+- [ ] User content wrapped in quotes (`"..."`) where applicable
+- [ ] Motion is grounded — fade and slide only, no bounce

package/codeyam-cli/templates/design-systems/neo-brutalist-design-system.md

@@ -0,0 +1,294 @@
+# Neo-Brutalist Design System
+
+> Hard-edged, warm, editorial UI. Offset shadows, bold borders, hot pink accent. For any web or mobile app.
+
+## Philosophy
+
+Heavy black borders and offset box shadows create a "printed" feel. Warm off-white base (never pure white or grey). Typography is heavy and confident. No gradients. No rounded corners over 18px.
+
+**Rules:**
+
+1. Cards always have `border: 2px solid` + offset box shadow
+2. Interactive elements "press" on hover/active (`translate(2px, 2px)`, shadow removed)
+3. Dark mode inverts backgrounds but keeps accent colors identical
+4. Dark cards/sidebar stay dark in both modes
+
+---
+
+## Colors
+
+### Light Mode
+
+```css
+[data-theme='light'] {
+  --bg-base: #f5f0e8; /* warm off-white page bg */
+  --bg-surface: #ffffff; /* cards, panels */
+  --bg-muted: #ede8de; /* subtle sections, table headers */
+  --bg-inverse: #0d0d0d; /* dark surfaces */
+
+  --text-primary: #0d0d0d;
+  --text-secondary: #666666;
+  --text-muted: #999999;
+  --text-inverse: #ffffff;
+
+  --border: #0d0d0d;
+  --border-light: #e5ddd0; /* internal dividers */
+
+  --shadow-sm: 2px 2px 0px #0d0d0d;
+  --shadow-md: 4px 4px 0px #0d0d0d;
+  --shadow-lg: 6px 6px 0px #0d0d0d;
+  --shadow-accent: 4px 4px 0px #ff90e8;
+}
+```
+
+### Dark Mode
+
+```css
+[data-theme='dark'] {
+  --bg-base: #111111;
+  --bg-surface: #1a1a1a;
+  --bg-muted: #222222;
+  --text-primary: #f5f0e8;
+  --text-secondary: #aaaaaa;
+  --text-muted: #666666;
+  --text-inverse: #0d0d0d;
+  --border: #f5f0e8;
+  --border-light: #2a2a2a;
+  --shadow-sm: 2px 2px 0px #f5f0e8;
+  --shadow-md: 4px 4px 0px #f5f0e8;
+  --shadow-lg: 6px 6px 0px #f5f0e8;
+  /* Accents unchanged. Dark cards/sidebar unchanged. */
+}
+```
+
+Respect `@media (prefers-color-scheme: dark)` on `:root:not([data-theme="light"])`.
+
+### Accents
+
+```css
+/* These don't change between modes */
+--pink: #ff90e8; /* primary: CTAs, active nav, highlights */
+--pink-light: #ffe4f8;
+--teal: #14b8a6; /* secondary: success states, live data */
+--teal-light: #ccfbf1;
+--teal-dark: #0f766e;
+--yellow: #facc15; /* tertiary: alerts, featured labels */
+--yellow-light: #fef9c3;
+--yellow-dark: #ca8a04;
+--orange: #fb923c; /* quaternary: warnings */
+```
+
+### Semantic
+
+```css
+--success-bg: #d1fae5;
+--success-text: #065f46;
+--danger-bg: #fee2e2;
+--danger-text: #991b1b;
+--warning-bg: #fef9c3;
+--warning-text: #854d0e;
+/* Dark mode: --success-bg: #052e16; --success-text: #86efac; etc. */
+```
+
+### Ordered Palette
+
+```css
+/* For any categorical sequence: tags, categories, avatars, etc. */
+--palette-1: #ff90e8; /* pink */
+--palette-2: #14b8a6; /* teal */
+--palette-3: #facc15; /* yellow */
+--palette-4: #fb923c; /* orange */
+--palette-5: #818cf8; /* purple */
+```
+
+---
+
+## Typography
+
+**Font stack:** `'DM Sans', sans-serif` (body), `'DM Serif Display', serif` (display/h1), `'DM Mono', monospace` (code)
+
+| Style       | Size                     | Weight              | Notes                                                 |
+| ----------- | ------------------------ | ------------------- | ----------------------------------------------------- |
+| Display     | `clamp(28px, 4vw, 48px)` | 400 (Serif Display) | `letter-spacing: -1.5px; line-height: 1.1`            |
+| H1          | `clamp(22px, 3vw, 36px)` | 900                 | `letter-spacing: -1px`                                |
+| H2          | 20px                     | 900                 | `letter-spacing: -0.5px`                              |
+| H3          | 15px                     | 700                 |                                                       |
+| Label       | 11px                     | 700                 | `uppercase; letter-spacing: 1px; color: --text-muted` |
+| Body        | 14px                     | 400                 | `line-height: 1.6`                                    |
+| Body SM     | 13px                     | 400                 | `line-height: 1.5`                                    |
+| Large Value | `clamp(22px, 3vw, 32px)` | 900                 | `letter-spacing: -1px` — for emphasized numbers       |
+
+**Common pattern — eyebrow + title:** Label above H2 in almost every section.
+
+---
+
+## Spacing & Radius
+
+Base unit: 4px. Scale: 4, 8, 12, 16, 20, 24, 28, 32, 40, 48px.
+
+| Context                | Value       |
+| ---------------------- | ----------- |
+| Card padding (compact) | `16px 18px` |
+| Card padding (default) | `22px 24px` |
+| Card padding (large)   | `28px 28px` |
+| Grid gap               | 18px        |
+
+```css
+--radius-sm: 8px;
+--radius-md: 12px;
+--radius-lg: 18px; /* cards — max radius in the system */
+--radius-pill: 999px; /* badges, avatars */
+```
+
+---
+
+## Layout
+
+### Common Patterns
+
+- **Sidebar:** 220px fixed left, `--bg-inverse`, always dark in both modes
+- **Top nav:** Sticky, 64px height, `--bg-base`, bottom border
+- **Bottom nav (mobile):** Fixed, 64px, `--pink-light` active bg. Add `env(safe-area-inset-bottom)` padding
+- **Main content:** flex-1, `--bg-base`, padding `36px 40px`
+
+### Navigation States
+
+- Logo mark: 36px accent square + bold name
+- Nav items: 14px, `10px 14px` padding, rounded 10px. Hover/active → `--pink` bg + dark text
+- Top nav active link: inverse bg pill
+
+### Mobile / Small Viewport
+
+- Single column, 16px padding
+- Cards stack vertically, buttons full-width in forms
+- Reduce shadows to `--shadow-sm`
+
+---
+
+## Components
+
+### Card
+
+```css
+.card {
+  background: var(--bg-surface);
+  border: 2px solid var(--border);
+  border-radius: var(--radius-lg);
+  padding: 22px 24px;
+  box-shadow: var(--shadow-md);
+  position: relative;
+  overflow: hidden;
+}
+```
+
+**Variants:** `default` (white), `dark` (inverse bg + accent shadow), `pink`, `teal`, `yellow`, `muted` (base bg).
+
+**Interactive states:** hover → `translateY(-3px)` + `shadow-lg`. Active → `translate(2px, 2px)` + `shadow-sm`.
+
+### Value Card
+
+Card with: decorative accent circle (top-right, 64px, 20% opacity), icon box (40px, accent bg, 2px border, rounded 10px), label (eyebrow), emphasized value (Large Value style), optional trend badge (pill, success/danger colors).
+
+### Button
+
+```css
+.btn {
+  padding: 11px 22px;
+  border-radius: var(--radius-md);
+  font-weight: 700;
+  font-size: 14px;
+  border: 2px solid var(--border);
+}
+.btn:hover {
+  transform: translate(-1px, -1px);
+}
+.btn:active {
+  transform: translate(2px, 2px);
+  box-shadow: none;
+}
+```
+
+| Variant   | Background     | Text             | Border/Shadow             |
+| --------- | -------------- | ---------------- | ------------------------- |
+| Primary   | `--pink`       | `--text-primary` | `--shadow-md`             |
+| Secondary | `--bg-surface` | `--text-primary` | `--shadow-sm`             |
+| Teal      | `--teal`       | `--text-primary` | `--shadow-md`             |
+| Yellow    | `--yellow`     | `--text-primary` | `--shadow-md`             |
+| Dark      | `--bg-inverse` | `--text-inverse` | `--shadow-accent`         |
+| Ghost     | transparent    | `--text-primary` | none; hover: `--bg-muted` |
+
+| Size         | Padding     | Font Size |
+| ------------ | ----------- | --------- |
+| SM           | `7px 14px`  | 12px      |
+| MD (default) | `11px 22px` | 14px      |
+| LG           | `15px 30px` | 16px      |
+
+Icon-only: 40x40, no padding, `--radius-sm`.
+
+### Badge / Pill
+
+`padding: 3px 10px; border-radius: 999px; font-size: 11px; font-weight: 700; border: 1.5px solid currentColor`. Semantic variants: success, danger, warning, pink, teal, yellow, neutral. Solid variant: inverse bg+text.
+
+### Input
+
+`padding: 11px 16px; border: 2px solid var(--border); border-radius: var(--radius-md); font-size: 14px`. Focus: `box-shadow: 0 0 0 3px var(--pink)`. Input-group: input + button joined with zero'd inner radii.
+
+### Table
+
+Container: card shell (border, radius-lg, shadow-md, overflow hidden). Header: `--bg-muted`, 11px uppercase labels. Rows: `16px 28px` padding, `--border-light` divider, hover → muted bg.
+
+### Progress Bar
+
+Track: 12px height, `--bg-muted`, pill radius, 2px border. Fill: pill radius, accent color. Animate: `width 0.8s cubic-bezier(0.34, 1.56, 0.64, 1)`.
+
+### Avatar
+
+Square-ish (`--radius-sm`), 2px border. Sizes: 28/36/48px. Cycle through ordered palette colors.
+
+### Tag / Chip
+
+`padding: 5px 12px; border-radius: 999px; border: 2px solid var(--border); font-size: 13px; font-weight: 600`. Hover → pink bg. Active → inverse bg+text.
+
+### Tooltip
+
+`background: --bg-inverse; border: 2px solid --pink; border-radius: --radius-md; padding: 10px 16px; color: --text-inverse; font-size: 13px`. Bold label + bold value.
+
+---
+
+## Motion
+
+```css
+--transition-fast: 120ms ease; /* button press */
+--transition-base: 180ms ease; /* card hover, general */
+```
+
+Bouncy and tactile — elements lift and press. Staggered fade-up on page load:
+
+```css
+@keyframes fadeUp {
+  from {
+    opacity: 0;
+    transform: translateY(12px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+/* animation: fadeUp 0.4s ease forwards; delay: n * 0.05s */
+```
+
+---
+
+## Checklist
+
+- [ ] Background is `#F5F0E8` (light) or `#111111` (dark) — never pure white or grey
+- [ ] Every card has 2px border + offset box shadow
+- [ ] Interactive elements press-shift on :active
+- [ ] DM Sans (body) + DM Serif Display (headlines) + DM Mono (code)
+- [ ] At least one pink element visible on every screen
+- [ ] Labels: 11px uppercase, letter-spacing 1px
+- [ ] Badges are pill-shaped with border
+- [ ] Dark sidebar/cards unchanged in dark mode
+- [ ] No gradients anywhere
+- [ ] Spacing follows 4px grid

package/codeyam-cli/templates/expo-react-native/MOBILE_SETUP.md

@@ -78,6 +78,121 @@ Use Tailwind classes on React Native components:
 </View>
 ```
 
+## CodeYam Scenario Data
+
+### AsyncStorage Seeding
+
+AsyncStorage uses `localStorage` on web, so CodeYam's existing localStorage injection works automatically. Use the `localStorage` field in scenario JSON to pre-populate storage:
+
+```json
+{
+  "name": "With Saved Items",
+  "url": "/",
+  "dimensions": ["iPhone 16"],
+  "localStorage": {
+    "items": "[{\"id\":\"1\",\"title\":\"Buy groceries\",\"done\":false},{\"id\":\"2\",\"title\":\"Walk the dog\",\"done\":true}]"
+  }
+}
+```
+
+Values must be JSON strings (matching how AsyncStorage stores them). Your `storage.get()` calls will read this data normally.
+
+### API Mocking
+
+For apps that fetch from APIs, use relative URLs so CodeYam's proxy can intercept and mock them:
+
+```tsx
+// Use relative URLs — these go through the CodeYam proxy
+const response = await fetch('/api/items');
+```
+
+Then provide mock routes in your scenario data:
+
+```json
+{
+  "name": "With API Data",
+  "url": "/",
+  "dimensions": ["iPhone 16"],
+  "routes": {
+    "/api/items": {
+      "body": [{ "id": 1, "title": "First item" }],
+      "status": 200
+    }
+  }
+}
+```
+
+### Device Presets
+
+Mobile projects default to these screen sizes:
+
+| Preset            | Width | Height |
+| ----------------- | ----- | ------ |
+| iPhone 16         | 393   | 852    |
+| iPhone 16 Pro Max | 430   | 932    |
+| iPhone SE         | 375   | 667    |
+| Pixel 8           | 412   | 915    |
+| iPad mini         | 744   | 1133   |
+
+## Design Tokens (lib/theme.ts)
+
+All design tokens live in `lib/theme.ts` — this is the **single source of truth** for colors, spacing, typography, and border radius. Import and use in every component:
+
+```tsx
+import { theme } from '@/lib/theme';
+
+<View
+  style={{ backgroundColor: theme.colors.bgBase, padding: theme.spacing.lg }}
+>
+  <Text
+    style={{ fontSize: theme.fontSize.lg, color: theme.colors.textPrimary }}
+  >
+    Hello
+  </Text>
+</View>;
+```
+
+**Do NOT:**
+
+- Use CSS custom properties (`var(--token)`) — they don't work in React Native
+- Hardcode color strings or pixel values in components
+- Create a separate `globals.css` token system — `lib/theme.ts` is the only source
+
+When a design system is selected, populate `lib/theme.ts` with its tokens.
+
+## Testing
+
+Tests use Jest with the `jest-expo` preset. Run with:
+
+```bash
+npx jest                          # Run all tests
+npx jest app/hooks/useCounter.ts  # Run specific test file
+```
+
+The Jest config is in `package.json`. The `transformIgnorePatterns` is pre-configured to handle Expo and React Native module transforms — you should not need to modify it.
+
+## Web vs Native Differences
+
+The CodeYam editor previews your app via **Expo Web** (react-native-web in a browser). Some differences from native iOS/Android devices are expected:
+
+| Aspect           | Web Preview                                            | Native Device                                           |
+| ---------------- | ------------------------------------------------------ | ------------------------------------------------------- |
+| **Fonts**        | System fonts, may differ in weight/metrics/line-height | Loaded custom fonts (if added via expo-font)            |
+| **SafeAreaView** | No effect (no notch in browser)                        | Applies real safe area insets for notch, home indicator |
+| **Platform.OS**  | Returns `'web'`                                        | Returns `'ios'` or `'android'`                          |
+| **Shadows**      | Uses CSS `box-shadow` (works well)                     | Uses RN shadow props (iOS) or `elevation` (Android)     |
+| **Gestures**     | Mouse drag events                                      | Touch/swipe with inertia                                |
+| **StatusBar**    | No visible effect                                      | Controls device status bar appearance                   |
+| **Haptics**      | No-op                                                  | Real haptic feedback via `expo-haptics`                 |
+
+**The web preview is for layout and data verification.** Test final visual polish on a real device or simulator:
+
+```bash
+npm run ios       # iOS Simulator
+npm run android   # Android Emulator
+npm start         # Pick platform from Expo menu
+```
+
 ## Building for Production
 
 ```bash

package/codeyam-cli/templates/expo-react-native/app/_layout.tsx

@@ -1,12 +1,13 @@
 import '../global.css';
 import { Stack } from 'expo-router';
 import { StatusBar } from 'expo-status-bar';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
 
 export default function RootLayout() {
   return (
-    <>
+    <SafeAreaProvider>
       <Stack screenOptions={{ headerShown: false }} />
       <StatusBar style="auto" />
-    </>
+    </SafeAreaProvider>
   );
 }

package/codeyam-cli/templates/expo-react-native/global.css

@@ -1,3 +1,10 @@
+/* NativeWind / Tailwind utility layer.
+ *
+ * Design tokens are defined in lib/theme.ts — that is the single source
+ * of truth for colors, spacing, typography, and border radius.
+ * Do NOT define CSS custom properties here for design tokens.
+ * React Native components cannot read CSS variables.
+ */
 @tailwind base;
 @tailwind components;
 @tailwind utilities;