openuispec 0.1.18 → 0.1.19

package/README.md

@@ -4,6 +4,8 @@
 
 OpenUISpec is a **semantic UI specification format** that replaces cross-platform frameworks with a declarative design language. Instead of sharing runtime code across platforms, you share the *spec* — and AI generates native SwiftUI, Jetpack Compose, and React code from it.
 
+OpenUISpec is a shared UI sync language for native products, optimized for solo developers but equally usable by teams. It is not a pixel-perfect design format like Figma and it is not a shared runtime like Flutter or React Native. Its job is to keep product intent, interaction contracts, flows, tokens, and platform outputs aligned while still allowing bounded native variation on iOS, Android, and web.
+
 ## Why
 
 Cross-platform frameworks (Flutter, React Native, KMP/CMP) solve code duplication by sharing a runtime. OpenUISpec solves it by sharing **intent**:
@@ -13,7 +15,7 @@ Cross-platform frameworks (Flutter, React Native, KMP/CMP) solve code duplicatio
 | Cross-platform framework | Runtime code | Abstraction layer |
 | **OpenUISpec** | **Semantic spec** | **Native per platform** |
 
-The result: each platform feels native, but every app stays consistent because it's generated from the same source of truth.
+The result: each platform feels native, but every app stays semantically consistent because it's generated from the same source of truth.
 
 ## How it works
 
@@ -56,7 +58,18 @@ Then hand your spec to any AI code generator:
 
 > Generate a native iOS app from this OpenUISpec. Follow all contract state machines, apply token ranges for iOS, and implement navigation flows as defined. Use `platform/ios.yaml` for SwiftUI-specific overrides.
 
-See the [TaskFlow example](./examples/taskflow/) for a complete spec covering all 7 contract families.
+Before platform code generation, the AI should refresh its understanding of the current target toolchain and platform conventions instead of relying on stale memory. This matters most for project formats, resource wiring, navigation APIs, packaging rules, and other implementation details that change across toolchain versions.
+
+For platform generation, treat these as hard output constraints:
+
+- Generate a valid native project or target that actually bundles every required runtime resource. Converting spec inputs into platform-native resource files is insufficient unless those files are attached to the final app target and resolve at runtime.
+- Do not ship unresolved resource identifiers in the UI. Raw localization keys, token references, asset names, or placeholder paths mean the generated output is incomplete.
+- Do not use a container or navigation primitive without defining its behavior for every supported size class and form factor. Master-detail patterns must provide a non-empty compact fallback instead of assuming large-screen behavior.
+
+See the examples for concrete reference projects:
+
+- [TaskFlow](./examples/taskflow/) for a compact spec covering all 7 contract families
+- [Todo Orbit](./examples/todo-orbit/openuispec/) for a bilingual task app with generated iOS, Android, and web targets under `examples/todo-orbit/generated/`
 
 ## Repository structure
 
@@ -89,37 +102,41 @@ openuispec/
 │   │   └── validation.schema.json     # Validation rule definitions
 │   └── validate.ts                     # Validation script (npm run validate)
 ├── examples/
-│   └── taskflow/                        # Complete example app
-│       ├── openuispec.yaml              # Root manifest + data model + API endpoints
-│       ├── tokens/
-│       │   ├── color.yaml               # Brand + semantic + status colors
-│       │   ├── typography.yaml          # Font family + 8-step type scale
-│       │   ├── spacing.yaml             # 4px base unit, 9-step scale
-│       │   ├── elevation.yaml           # 4-level elevation (none/sm/md/lg)
-│       │   ├── motion.yaml              # Durations, easings, patterns
-│       │   ├── layout.yaml              # Size classes, primitives, reflow rules
-│       │   ├── themes.yaml              # Light, dark, warm variants
-│       │   └── icons.yaml              # Icon registry with platform mappings
-│       ├── contracts/                   # Standard contract extensions + custom contracts
-│       │   ├── input_field.yaml       # Standard contract with cut_corner variant
-│       │   └── x_media_player.yaml    # Custom media player contract (Section 12)
-│       ├── screens/
-│       │   ├── home.yaml                # Task list with search, filters, FAB, adaptive nav
-│       │   ├── task_detail.yaml         # Full task view with actions + assignee sheet
-│       │   ├── projects.yaml            # Project grid + new project dialog
-│       │   ├── project_detail.yaml      # Single project with task list (stub)
-│       │   ├── settings.yaml            # Preferences, toggles, account management
-│       │   ├── profile_edit.yaml        # Edit profile form (stub)
-│       │   └── calendar.yaml            # Calendar view (stub)
-│       ├── flows/
-│       │   ├── create_task.yaml         # Task creation form (sheet presentation)
-│       │   └── edit_task.yaml           # Task editing flow
-│       ├── locales/
-│       │   └── en.json                  # English locale (ICU MessageFormat)
-│       └── platform/
-│           ├── ios.yaml                 # SwiftUI overrides + behaviors
-│           ├── android.yaml             # Compose overrides + behaviors
-│           └── web.yaml                 # React overrides + responsive rules
+│   ├── taskflow/                        # Compact reference spec
+│   │   ├── openuispec.yaml              # Root manifest + data model + API endpoints
+│   │   ├── tokens/
+│   │   │   ├── color.yaml               # Brand + semantic + status colors
+│   │   │   ├── typography.yaml          # Font family + 8-step type scale
+│   │   │   ├── spacing.yaml             # 4px base unit, 9-step scale
+│   │   │   ├── elevation.yaml           # 4-level elevation (none/sm/md/lg)
+│   │   │   ├── motion.yaml              # Durations, easings, patterns
+│   │   │   ├── layout.yaml              # Size classes, primitives, reflow rules
+│   │   │   ├── themes.yaml              # Light, dark, warm variants
+│   │   │   └── icons.yaml               # Icon registry with platform mappings
+│   │   ├── contracts/                   # Standard contract extensions + custom contracts
+│   │   │   ├── input_field.yaml         # Standard contract with cut_corner variant
+│   │   │   └── x_media_player.yaml      # Custom media player contract (Section 12)
+│   │   ├── screens/
+│   │   │   ├── home.yaml                # Task list with search, filters, FAB, adaptive nav
+│   │   │   ├── task_detail.yaml         # Full task view with actions + assignee sheet
+│   │   │   ├── projects.yaml            # Project grid + new project dialog
+│   │   │   ├── project_detail.yaml      # Single project with task list (stub)
+│   │   │   ├── settings.yaml            # Preferences, toggles, account management
+│   │   │   ├── profile_edit.yaml        # Edit profile form (stub)
+│   │   │   └── calendar.yaml            # Calendar view (stub)
+│   │   ├── flows/
+│   │   │   ├── create_task.yaml         # Task creation form (sheet presentation)
+│   │   │   └── edit_task.yaml           # Task editing flow
+│   │   ├── locales/
+│   │   │   └── en.json                  # English locale (ICU MessageFormat)
+│   │   └── platform/
+│   │       ├── ios.yaml                 # SwiftUI overrides + behaviors
+│   │       ├── android.yaml             # Compose overrides + behaviors
+│   │       └── web.yaml                 # React overrides + responsive rules
+│   └── todo-orbit/                      # Full showcase app with generated targets
+│       ├── openuispec/                  # Source OpenUISpec project
+│       ├── generated/                   # Generated iOS, Android, and web apps
+│       └── artifacts/                   # Screenshots and supporting outputs
 ├── cli/                                 # CLI tool (openuispec init, drift, validate)
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
@@ -214,7 +231,7 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is st
 
 ## Status
 
-**v0.1 — Draft**. The spec covers all foundational layers. One complete example app (TaskFlow) demonstrates full coverage.
+**v0.1 — Draft**. The spec covers all foundational layers. TaskFlow provides a compact reference app, and Todo Orbit extends coverage with localization, recurring-rule flows, custom contracts, and generated native/web targets.
 
 ### Roadmap
 
@@ -231,6 +248,7 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is st
 - [x] Form system (validation rules, field dependencies)
 - [x] Drift detection (spec change tracking per platform)
 - [x] CLI tool (`openuispec init` for project scaffolding + AI rules)
+- [x] Multi-platform showcase app (`examples/todo-orbit/`)
 - [ ] More example apps (e-commerce, social, dashboard)
 
 ## Contributing

package/cli/index.ts

@@ -43,7 +43,7 @@ Usage:
   openuispec drift --snapshot --target <t>  Snapshot current state
   openuispec validate [group...]            Validate spec files
 
-Validate groups: manifest, tokens, screens, flows, platform, locales, custom_contracts
+Validate groups: manifest, tokens, screens, flows, platform, locales, contracts
 
 Docs: https://openuispec.rsteam.uz
 `);

package/docs/stress-test-maturity-report.md

@@ -0,0 +1,97 @@
+# OpenUISpec Stress Test & Maturity Assessment
+
+Date: 2026-03-14
+
+## Scope
+This assessment stress-tested the project at four layers:
+
+1. **Schema correctness pressure** across both reference specs (`taskflow`, `todo-orbit`).
+2. **Type safety and implementation consistency** in the TypeScript toolchain.
+3. **Change-tracking workflow resilience** using drift snapshot/check across all declared targets.
+4. **Generated output comparison** to verify functional parity across platform outputs without requiring pixel-perfect identity.
+
+## Commands executed
+
+```bash
+npm ci
+npm run validate                                # from examples/taskflow (workspace script)
+npx tsx ../../../schema/validate.ts            # from examples/todo-orbit/openuispec
+npx tsc --noEmit
+for t in ios android web; do
+  npx tsx ../../../drift/index.ts --snapshot --target "$t"
+  npx tsx ../../../drift/index.ts --target "$t"
+done
+python - <<'PY'
+from pathlib import Path
+roots={
+  'web':Path('examples/todo-orbit/generated/web/Todo Orbit/src'),
+  'ios':Path('examples/todo-orbit/generated/ios/Todo Orbit/Sources/TodoOrbit'),
+  'android':Path('examples/todo-orbit/generated/android/Todo Orbit/app/src/main/java/uz/rsteam/todoorbit')
+}
+for k,r in roots.items():
+  code=[p for p in r.rglob('*') if p.is_file() and p.suffix in ['.tsx','.ts','.swift','.kt','.css']]
+  loc=sum(sum(1 for _ in p.open('r',encoding='utf-8')) for p in code)
+  print(f"{k}: files={len(code)} loc={loc}")
+PY
+rg --files "examples/todo-orbit/artifacts/screenshots"
+```
+
+## Results summary
+
+- **Validation stress**: Passed for both example projects (all manifests, tokens, screens, flows, platform files, locales, and contracts).
+- **Compiler stress**: `tsc --noEmit` passed.
+- **Workflow stress (drift)**:
+  - Initial condition required snapshots (expected for first run).
+  - After snapshot creation, all three targets (`ios`, `android`, `web`) reported **0 changed / 0 added / 0 removed**.
+
+## Generated output comparison (functional parity, not pixel parity)
+
+The repository already frames Todo Orbit as a showcase with generated outputs for web, iOS, and Android. In this model, differences in structure/styling between generators or AI agents are expected.
+
+### Comparison policy used
+
+- **Do compare**: coverage of screens/flows/features, data model usage, localization support, and contract intent.
+- **Do not require**: identical widget trees, identical naming, exact spacing/typography values, or 1:1 rendered pixels.
+
+### Observed output differences (expected)
+
+- Web output is centralized in a small React surface (`src/App.tsx`, `src/main.tsx`, `src/styles.css`), while iOS/Android split into screen/component/flow files in platform-native patterns.
+- Code volume differs by target (`web: 3 files / 3013 LOC`, `ios: 11 files / 1516 LOC`, `android: 11 files / 1992 LOC`), which is normal because generated architecture choices vary by platform and template style.
+
+### Observed output alignment (good)
+
+- All targets include the same core feature set represented in spec: home/tasks, analytics, settings, task editor flow, and recurring-rule flow.
+- Localization assets exist for EN/RU in generated native outputs and in web runtime messages.
+- Reference screenshots exist for corresponding web and Android screens (`home`, `analytics`, `settings`), indicating practical parity at user-flow level rather than pixel-level equivalence.
+
+## Maturity score (0–5)
+
+- **Specification maturity: 4.0 / 5**
+  - Strong: clear schema decomposition, contract model, and examples.
+  - Gap: project still explicitly marked **v0.1 Draft**.
+
+- **Implementation maturity: 3.9 / 5**
+  - Strong: deterministic validators, lint-like contract usage checks, drift hashing, and multi-target generated examples.
+  - Gap: limited automated unit/integration test coverage in root scripts.
+
+- **Operational readiness: 3.7 / 5**
+  - Strong: practical CLI workflows for init/validate/drift and documented generated project layout.
+  - Gap: baseline onboarding friction for generated app dependency installation can be high in constrained environments.
+
+**Overall maturity estimate: 3.9 / 5 (promising, near early-production for spec tooling, with remaining work in generator conformance automation).**
+
+## What this says about idea–implementation fit
+
+- **Idea fit is high**: the repository architecture matches the thesis (“share semantic intent, generate native apps”).
+- **Implementation fit is good**: current tooling already enforces many promised invariants (schema + contract usage + drift).
+- **Cross-generator variance is acceptable**: output can differ by coding agent/LLM as long as contract behavior and user flows remain faithful to spec intent.
+- **Main risk is ecosystem hardening, not concept validity**: next maturity gains likely come from deeper automated tests, generator conformance tests, and CI reproducibility across generated targets.
+
+## Recommended next stress tests
+
+1. Add a `test` script with unit tests for validator edge-cases (especially custom contracts and malformed wrappers).
+2. Add golden-file conformance tests for drift output and schema error formatting.
+3. Add CI matrix that validates both examples + executes drift check for all targets.
+4. Add conformance checks that compare generated outputs on **feature parity** (screens, flows, actions, i18n keys), not snapshot pixel identity.
+5. Add “break tests” (intentionally invalid fixtures) to ensure failure messages stay actionable.
+6. Add benchmark scripts for validator runtime and drift checks on scaled synthetic specs.

package/examples/todo-orbit/AGENTS.md

@@ -0,0 +1,127 @@
+# OpenUISpec — AI Assistant Rules
+# ================================
+# This project uses OpenUISpec to define UI as a semantic spec.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: "ios", "android", "web"
+
+## What is OpenUISpec
+OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
+
+## Spec location
+- Spec root: `openuispec/`
+- Manifest: `openuispec/openuispec.yaml` — always read this first.
+- Tokens: `openuispec/tokens/` — colors, typography, spacing, motion, icons, themes
+- Screens: `openuispec/screens/` — one YAML file per screen
+- Flows: `openuispec/flows/` — multi-step navigation journeys
+- Contracts: `openuispec/contracts/` — UI component definitions
+- Platform: `openuispec/platform/` — per-target overrides (iOS, Android, Web)
+- Locales: `openuispec/locales/` — i18n strings (JSON, ICU MessageFormat)
+
+**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths (e.g. `../../shared/locales`). Always read `openuispec.yaml` to find the real directories.
+
+## If spec directories are empty (first-time setup)
+This means the project has existing UI code but hasn't been specced yet. Your job:
+
+1. **Find existing screens** — scan the codebase for UI screen files (SwiftUI views, Compose screens, React components/pages).
+2. **Create stubs** — for each screen, create `openuispec/screens/<name>.yaml` with:
+   ```yaml
+   screen_name:
+     semantic: "Brief description of what this screen does"
+     status: stub
+     layout:
+       type: scroll_vertical
+   ```
+3. **Extract tokens** — scan the codebase for colors, fonts, spacing values and create token files in `openuispec/tokens/`.
+4. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml` based on the existing code.
+5. **Spec screens on demand** — when the user asks to spec a screen, read the native code, create a full spec, and change `status: draft` → `ready`.
+
+## Screen and flow status
+- `stub` — placeholder, not yet specced. Drift detection skips these.
+- `draft` — actively being specced. Tracked by drift.
+- `ready` — fully specified (default if omitted). Tracked by drift.
+
+## Making UI changes
+1. Read the relevant spec files before modifying any UI code.
+2. If the change requires a spec update, modify the spec FIRST, then update code.
+3. Never modify generated code without updating the spec.
+4. When adding a new screen, create the corresponding spec file.
+5. When removing a screen, remove the spec file and update flow references.
+
+## After modifying spec files
+1. Run `openuispec validate` to check specs against the schema.
+2. Run `openuispec drift --snapshot --target <target>` for each affected platform.
+3. Run `openuispec drift` to verify no untracked drift remains.
+
+## Learning OpenUISpec — where to find the docs
+All documentation is in the installed `openuispec` package. Search in this order:
+1. **Local:** `node_modules/openuispec/` (project dependency)
+2. **Global:** run `npm root -g` to get the global prefix, then look in `<prefix>/openuispec/`
+3. **Online fallback:** if not installed, fetch from:
+   - `https://openuispec.rsteam.uz/llms-full.txt` — complete spec + all JSON schemas
+   - `https://openuispec.rsteam.uz/llms.txt` — concise summary with links
+
+Inside the package:
+1. **Full specification:** `spec/openuispec-v0.1.md` — the complete spec (read this to understand the format)
+2. **Example app:** `examples/taskflow/` — a complete working app with all file types
+3. **JSON Schemas:** `schema/` — validation schemas that define the exact structure of every file type
+
+## Token file structure — root wrapper key required
+Every token file must have a single root key matching the token type. Do NOT put properties at the top level.
+- `tokens/color.yaml` → root key: `color`
+- `tokens/typography.yaml` → root key: `typography`
+- `tokens/spacing.yaml` → root key: `spacing`
+- `tokens/elevation.yaml` → root key: `elevation`
+- `tokens/motion.yaml` → root key: `motion`
+- `tokens/layout.yaml` → root key: `layout`
+- `tokens/themes.yaml` → root key: `themes`
+- `tokens/icons.yaml` → root key: `icons`
+
+## File formats and schemas — read before creating spec files
+Before creating or editing any spec file, read the corresponding JSON Schema. Do not guess the file format.
+
+| File | Schema (in `schema/` inside the installed package) | Root key |
+|------|--------|----------|
+| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` |
+| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` |
+| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` |
+| `platform/*.yaml` | `platform.schema.json` | `platform` |
+| `locales/*.json` | `locale.schema.json` | (object) |
+| `contracts/x_*.yaml` | `custom-contract.schema.json` | `contract` |
+| `tokens/color.yaml` | `tokens/color.schema.json` | `color` |
+| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` |
+| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` |
+| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` |
+| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` |
+| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` |
+| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` |
+| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` |
+
+Shared type definitions (actions, data-binding, adaptive, validation, common) are in `schema/defs/`.
+
+Workflow: read the schema → read an example from `examples/taskflow/` → create the YAML → run `openuispec validate`.
+
+## Spec format reference
+- 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback
+- Custom contracts: prefixed with `x_` (e.g., `x_media_player`)
+- Data binding: `$data:`, `$state:`, `$param:`, `$t:` prefixes
+- Actions: typed objects (navigate, api_call, set_state, confirm, sequence, feedback, etc.)
+- Adaptive layout: size classes (compact, regular, expanded) with per-section overrides
+
+## Output directories
+Drift tracks spec changes per target. By default state is stored in `generated/<target>/<project>/`.
+To map targets to actual code directories, set `generation.output_dir` in `openuispec.yaml`:
+```yaml
+generation:
+  output_dir:
+    web: "../web-ui/"
+    android: "../kmp-ui/"
+    ios: "../kmp-ui/iosApp/"
+```
+Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is stored inside each output directory.
+
+## CLI commands
+- `openuispec init` — scaffold a new spec project
+- `openuispec validate [group...]` — validate spec files against schemas
+- `openuispec drift --target <t>` — check for spec drift
+- `openuispec drift --snapshot --target <t>` — snapshot current state
+- `openuispec drift --all` — include stubs in drift check

package/examples/todo-orbit/CLAUDE.md

@@ -0,0 +1,127 @@
+# OpenUISpec — AI Assistant Rules
+# ================================
+# This project uses OpenUISpec to define UI as a semantic spec.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: "ios", "android", "web"
+
+## What is OpenUISpec
+OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
+
+## Spec location
+- Spec root: `openuispec/`
+- Manifest: `openuispec/openuispec.yaml` — always read this first.
+- Tokens: `openuispec/tokens/` — colors, typography, spacing, motion, icons, themes
+- Screens: `openuispec/screens/` — one YAML file per screen
+- Flows: `openuispec/flows/` — multi-step navigation journeys
+- Contracts: `openuispec/contracts/` — UI component definitions
+- Platform: `openuispec/platform/` — per-target overrides (iOS, Android, Web)
+- Locales: `openuispec/locales/` — i18n strings (JSON, ICU MessageFormat)
+
+**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths (e.g. `../../shared/locales`). Always read `openuispec.yaml` to find the real directories.
+
+## If spec directories are empty (first-time setup)
+This means the project has existing UI code but hasn't been specced yet. Your job:
+
+1. **Find existing screens** — scan the codebase for UI screen files (SwiftUI views, Compose screens, React components/pages).
+2. **Create stubs** — for each screen, create `openuispec/screens/<name>.yaml` with:
+   ```yaml
+   screen_name:
+     semantic: "Brief description of what this screen does"
+     status: stub
+     layout:
+       type: scroll_vertical
+   ```
+3. **Extract tokens** — scan the codebase for colors, fonts, spacing values and create token files in `openuispec/tokens/`.
+4. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml` based on the existing code.
+5. **Spec screens on demand** — when the user asks to spec a screen, read the native code, create a full spec, and change `status: draft` → `ready`.
+
+## Screen and flow status
+- `stub` — placeholder, not yet specced. Drift detection skips these.
+- `draft` — actively being specced. Tracked by drift.
+- `ready` — fully specified (default if omitted). Tracked by drift.
+
+## Making UI changes
+1. Read the relevant spec files before modifying any UI code.
+2. If the change requires a spec update, modify the spec FIRST, then update code.
+3. Never modify generated code without updating the spec.
+4. When adding a new screen, create the corresponding spec file.
+5. When removing a screen, remove the spec file and update flow references.
+
+## After modifying spec files
+1. Run `openuispec validate` to check specs against the schema.
+2. Run `openuispec drift --snapshot --target <target>` for each affected platform.
+3. Run `openuispec drift` to verify no untracked drift remains.
+
+## Learning OpenUISpec — where to find the docs
+All documentation is in the installed `openuispec` package. Search in this order:
+1. **Local:** `node_modules/openuispec/` (project dependency)
+2. **Global:** run `npm root -g` to get the global prefix, then look in `<prefix>/openuispec/`
+3. **Online fallback:** if not installed, fetch from:
+   - `https://openuispec.rsteam.uz/llms-full.txt` — complete spec + all JSON schemas
+   - `https://openuispec.rsteam.uz/llms.txt` — concise summary with links
+
+Inside the package:
+1. **Full specification:** `spec/openuispec-v0.1.md` — the complete spec (read this to understand the format)
+2. **Example app:** `examples/taskflow/` — a complete working app with all file types
+3. **JSON Schemas:** `schema/` — validation schemas that define the exact structure of every file type
+
+## Token file structure — root wrapper key required
+Every token file must have a single root key matching the token type. Do NOT put properties at the top level.
+- `tokens/color.yaml` → root key: `color`
+- `tokens/typography.yaml` → root key: `typography`
+- `tokens/spacing.yaml` → root key: `spacing`
+- `tokens/elevation.yaml` → root key: `elevation`
+- `tokens/motion.yaml` → root key: `motion`
+- `tokens/layout.yaml` → root key: `layout`
+- `tokens/themes.yaml` → root key: `themes`
+- `tokens/icons.yaml` → root key: `icons`
+
+## File formats and schemas — read before creating spec files
+Before creating or editing any spec file, read the corresponding JSON Schema. Do not guess the file format.
+
+| File | Schema (in `schema/` inside the installed package) | Root key |
+|------|--------|----------|
+| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` |
+| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` |
+| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` |
+| `platform/*.yaml` | `platform.schema.json` | `platform` |
+| `locales/*.json` | `locale.schema.json` | (object) |
+| `contracts/x_*.yaml` | `custom-contract.schema.json` | `contract` |
+| `tokens/color.yaml` | `tokens/color.schema.json` | `color` |
+| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` |
+| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` |
+| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` |
+| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` |
+| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` |
+| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` |
+| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` |
+
+Shared type definitions (actions, data-binding, adaptive, validation, common) are in `schema/defs/`.
+
+Workflow: read the schema → read an example from `examples/taskflow/` → create the YAML → run `openuispec validate`.
+
+## Spec format reference
+- 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback
+- Custom contracts: prefixed with `x_` (e.g., `x_media_player`)
+- Data binding: `$data:`, `$state:`, `$param:`, `$t:` prefixes
+- Actions: typed objects (navigate, api_call, set_state, confirm, sequence, feedback, etc.)
+- Adaptive layout: size classes (compact, regular, expanded) with per-section overrides
+
+## Output directories
+Drift tracks spec changes per target. By default state is stored in `generated/<target>/<project>/`.
+To map targets to actual code directories, set `generation.output_dir` in `openuispec.yaml`:
+```yaml
+generation:
+  output_dir:
+    web: "../web-ui/"
+    android: "../kmp-ui/"
+    ios: "../kmp-ui/iosApp/"
+```
+Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is stored inside each output directory.
+
+## CLI commands
+- `openuispec init` — scaffold a new spec project
+- `openuispec validate [group...]` — validate spec files against schemas
+- `openuispec drift --target <t>` — check for spec drift
+- `openuispec drift --snapshot --target <t>` — snapshot current state
+- `openuispec drift --all` — include stubs in drift check

package/examples/todo-orbit/README.md

@@ -0,0 +1,62 @@
+# Todo Orbit
+
+Todo Orbit is a multi-platform sample project for OpenUISpec. It combines a source spec with generated iOS, Android, and web outputs so the repository can demonstrate the full workflow from semantic UI definition to platform-native code.
+
+## What this sample covers
+
+- Task management screens with search, filtering, and detail views
+- Analytics and trend visualization
+- Settings with language and theme preferences
+- Create and edit task flows
+- Recurring-rule creation with conditional fields and validation
+- Bilingual localization with English and Russian
+- Custom contracts for schedule preview and task trend charts
+
+## Project layout
+
+| Path | Purpose |
+|------|---------|
+| [`openuispec/`](./openuispec/) | Source OpenUISpec project: manifest, tokens, screens, flows, contracts, locales |
+| [`generated/web/Todo Orbit/`](./generated/web/Todo%20Orbit/) | Generated React + Vite web app |
+| [`generated/ios/Todo Orbit/`](./generated/ios/Todo%20Orbit/) | Generated SwiftUI iOS target |
+| [`generated/android/Todo Orbit/`](./generated/android/Todo%20Orbit/) | Generated Jetpack Compose Android target |
+| [`artifacts/screenshots/`](./artifacts/screenshots/) | Reference screenshots from generated outputs |
+
+## Start here
+
+If you want to understand the sample at the spec level, open [`openuispec/openuispec.yaml`](./openuispec/openuispec.yaml). That manifest defines the project structure, data model, API surface, localization setup, and generation targets.
+
+For spec authoring details, see [`openuispec/README.md`](./openuispec/README.md).
+
+## Running the generated web app
+
+```bash
+cd examples/todo-orbit/generated/web/'Todo Orbit'
+npm install
+npm run dev
+```
+
+## Opening the native targets
+
+- iOS: open [`generated/ios/Todo Orbit/`](./generated/ios/Todo%20Orbit/) in Xcode using `TodoOrbit.xcodeproj`
+- Android: open [`generated/android/Todo Orbit/`](./generated/android/Todo%20Orbit/) in Android Studio
+
+Platform-specific notes are documented in:
+
+- [`generated/ios/Todo Orbit/README.md`](./generated/ios/Todo%20Orbit/README.md)
+- [`generated/android/Todo Orbit/README.md`](./generated/android/Todo%20Orbit/README.md)
+
+## Screenshots
+
+Examples of the generated output are available in [`artifacts/screenshots/`](./artifacts/screenshots/):
+
+- `web-home.png`
+- `web-analytics.png`
+- `web-settings.png`
+- `android-home.png`
+- `android-analytics.png`
+- `android-settings.png`
+
+## Why this sample exists
+
+TaskFlow is the compact reference example in this repository. Todo Orbit is the broader showcase: it exercises localization, custom contracts, richer flows, and generated outputs across all three supported targets.

package/examples/todo-orbit/generated/android/Todo Orbit/README.md

@@ -0,0 +1,14 @@
+# Todo Orbit Android
+
+Generated Android target for the OpenUISpec Todo Orbit project.
+
+## Structure
+
+- `app/` — Android application module
+- `app/src/main/java/uz/rsteam/todoorbit/MainActivity.kt` — Compose app scaffold
+- `app/src/main/java/uz/rsteam/todoorbit/ui/theme/TodoOrbitTheme.kt` — light/dark theme mapped from spec tokens
+
+## Notes
+
+- The project models the current OpenUISpec surface: tasks, analytics, settings, create/edit flows, recurring rule flow, bilingual strings, theme switching, and the two custom contracts (`x_task_trend_chart`, `x_schedule_preview`).
+- Build verification was limited by the local environment: `gradle`, `kotlinc`, and `sdkmanager` were not installed in the workspace session, so this target was generated as a credible Gradle/Compose project but not compiled here.

package/examples/todo-orbit/generated/android/Todo Orbit/app/build.gradle.kts

@@ -0,0 +1,58 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.plugin.compose")
+}
+
+android {
+    namespace = "uz.rsteam.todoorbit"
+    compileSdk = 36
+
+    defaultConfig {
+        applicationId = "uz.rsteam.todoorbit"
+        minSdk = 26
+        targetSdk = 35
+        versionCode = 1
+        versionName = "0.1.0"
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    buildFeatures {
+        compose = true
+    }
+
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+}
+
+dependencies {
+    implementation(platform("androidx.compose:compose-bom:2026.03.00"))
+    implementation("androidx.appcompat:appcompat:1.7.1")
+    implementation("androidx.core:core-ktx:1.16.0")
+    implementation("androidx.activity:activity-compose:1.11.0")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.9.4")
+    implementation("androidx.compose.ui:ui")
+    implementation("androidx.compose.ui:ui-tooling-preview")
+    implementation("androidx.compose.foundation:foundation")
+    implementation("androidx.compose.material3:material3")
+    implementation("androidx.compose.material:material-icons-extended")
+
+    debugImplementation("androidx.compose.ui:ui-tooling")
+    debugImplementation("androidx.compose.ui:ui-test-manifest")
+}

package/examples/todo-orbit/generated/android/Todo Orbit/app/proguard-rules.pro

@@ -0,0 +1 @@
+# Intentionally minimal for generated demo output.

package/examples/todo-orbit/generated/android/Todo Orbit/app/src/main/AndroidManifest.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application
+        android:allowBackup="true"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@android:style/Theme.Material.Light.NoActionBar">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>