openuispec 0.1.18 → 0.1.20

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,75 @@
+# 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"
+
+## IMPORTANT — Read the specification before working with spec files
+
+The spec format, file schemas, and generation rules are defined in the installed `openuispec` package.
+You MUST read the reference files listed below before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+
+**Find the package in this order:**
+1. `node_modules/openuispec/` (project dependency)
+2. Run `npm root -g` → `<prefix>/openuispec/` (global install)
+3. Online: `https://openuispec.rsteam.uz/llms-full.txt` (if not installed)
+
+**Reference files inside the package (read in this order):**
+1. `README.md` — schema tables, file format reference, root wrapper keys
+2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
+3. `examples/taskflow/` — complete working example with all file types
+4. `schema/` — JSON Schemas for every file type
+
+These files are updated with each package version. Always read from the installed package,
+not from cached or memorized content, to ensure you use the latest spec.
+
+## 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/`
+- Screens: `openuispec/screens/`
+- Flows: `openuispec/flows/`
+- Contracts: `openuispec/contracts/`
+- Platform: `openuispec/platform/`
+- Locales: `openuispec/locales/`
+
+**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths. 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. **Read the spec first** — find and read `spec/openuispec-v0.1.md` from the installed package.
+2. **Find existing screens** — scan the codebase for UI screen files.
+3. **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
+   ```
+4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
+5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+
+## 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.
+
+## 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>

package/examples/todo-orbit/generated/android/Todo Orbit/app/src/main/java/uz/rsteam/todoorbit/MainActivity.kt

@@ -0,0 +1,14 @@
+package uz.rsteam.todoorbit
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            TodoOrbitGeneratedApp()
+        }
+    }
+}