sysdesign: align iPad app with UX Design Specification v1.0 (draw-facade-intent creator experience)

[nigel-hall-codes]

Goal: Move the current iPad app implementation closer to the UX vision below. This is the source-of-truth design spec for the app's creator experience. analyze should produce a gap analysis + target architecture; plan should fan out child feat issues per screen/workflow.

---

San Francisco Generator iPad App — UX Design Specification v1.0

Purpose

Defines the creator experience for the San Francisco procedural building generation platform. Unlike traditional 3D modeling tools, this app is designed around drawing facade intent rather than manually constructing geometry.

Primary workflow:

Draw Facade Layout → Assign Regions → Configure Rules → Generate Variants → Apply To District → Generate Buildings

The user creates design systems rather than individual buildings.

Design Principles

1. Pencil First — every major workflow achievable with Apple Pencil. Feel closer to Procreate / Figma / Concepts than Unity / Blender / Maya.
2. Visual First — users rarely edit numbers directly. Instead of Window Count = 6, they draw a Window Zone and configure behavior visually.
3. Preview Everything — every change generates visual feedback. No hidden procedural systems.
4. Templates Over Buildings — templates are the primary content; buildings are generated results.
5. Fast Iteration — Draw → Generate → Evaluate → Adjust → Generate within seconds.

Application Structure

Dashboard · Templates · Buildings · Assets · Districts · Generation

Dashboard

Project overview. Counts (Templates, Assets, Buildings, Districts), Recent Work list, "Generate District Preview" action.

Templates (primary screen, ~40-50% of usage)

Create procedural facade systems.

Template Browser — cards showing Name, Building Count, District Usage, Last Modified.

Template Workspace — three panes: Layers (Regions, Assets) · Facade Canvas (Design Surface) · Properties (Rules, Variations).

Facade Canvas (core feature): user draws semantic regions, not geometry/meshes/windows.

• Region types: Window Zone, Door Zone, Storefront Zone, Sign Zone, Balcony Zone, Roof Zone, Decoration Zone, Utility Zone.
• Region creation (Pencil): Tap Region Tool → Draw Shape → Region Created. Shapes: Rectangle, Polygon, Freeform.
• Example: user draws "Upper Window Zone"; system understands the area contains windows; generator decides count, which windows, spacing, variations.

Layers Panel (Figma-like) — each layer supports Hide, Lock, Rename, Duplicate.

Properties Panel (context-sensitive):

• Window Zone Rules: Allowed Assets, Count Range, Spacing, Random Offset, Alignment, Probability (e.g. Victorian A 50% / B 30% / C 20%).
• Storefront Zone Rules: Allowed Storefronts, Glass Ratio, Awning Chance, Sign Position, Corner Handling.
• Sign Zone Rules: Sign Types, Maximum Width, Alignment, AI Sign Generation.

Variation Preview — Generate Variants (Variant 1..N). Evaluate randomness: too repetitive? too chaotic? enough variety? feels like SF?

Buildings

View generated buildings. Cards: 3D Preview, Address, District, Template, Override Count.

• Building Modal: Customize Building / View Template / Cancel.
• Customize Building: murals, custom signs, store branding, unique decorations, historic landmarks. Changes affect one building only.
• Building Canvas: like template canvas, but creates direct artwork rather than rules. Tools: Brush, Image, AI Sign, Text, Props, Erase.

Assets

Manage reusable content. Categories: Windows, Doors, Storefronts, Roofs, Signs, Balconies, Decorations, Street Furniture.

• Asset Browser: visual grid — Thumbnail, Category, Tags, Usage Count.
• Asset Detail: 3D Preview, Compatible Regions, Metadata, District Restrictions.

Districts

Control neighborhood identity.

• District Editor (e.g. Mission District): Template Distribution (weighted %), Color Palette (Base/Accent/Trim), Sign Style (Modern/Vintage/Bilingual/Tourist/Mixed).
• District Preview (most important review screen): Generate Street → 10-50 buildings using district rules. Views: Street View, Block View, Density View (generation distribution).

Generation

Produce Unity-ready content. Scope: Single Building / Block / Neighborhood / Entire City.

Pipeline:

OSM Footprint → District Rules → Template Selection → Region Evaluation → Asset Placement → Color Assignment → Building Generation → Unity Export

Future Features

• AI Facade Layout Generator — input "Mission Corner Store" → AI generates Window/Storefront/Sign/Roof Zones.
• Building Screenshot Analysis — import a photo → AI identifies windows/doors/storefronts/signs/balconies → creates a starting template.
• Procedural District Generator — input "North Beach" → AI proposes templates, palette, sign style, building mix.

Success Metric

A single creator can create 50–100 templates that generate 10,000–50,000 believable San Francisco buildings, while manually customizing only a small number of hero buildings and landmarks.