openuispec 0.1.4 → 0.1.6

package/cli/init.ts

@@ -118,6 +118,88 @@ api:
 `;
 }
 
+function specReadmeTemplate(name: string, targets: string[]): string {
+  const targetList = targets.join(", ");
+  return `# ${name} — OpenUISpec
+
+This directory contains the **OpenUISpec** semantic UI specification for **${name}**.
+
+OpenUISpec is a YAML-based format that describes your app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). The spec is the single source of truth across all platforms.
+
+## Directory structure
+
+| Directory | Contents |
+|-----------|----------|
+| \`tokens/\` | Design tokens — colors, typography, spacing, elevation, motion, icons, themes |
+| \`screens/\` | Screen definitions — one YAML file per screen |
+| \`flows/\` | Navigation flows — multi-step user journeys |
+| \`contracts/\` | Component contracts — custom UI component definitions (\`x_\` prefixed) |
+| \`platform/\` | Platform overrides — per-target (iOS, Android, Web) behaviors |
+| \`locales/\` | Localization — i18n strings (JSON, ICU MessageFormat) |
+
+## Getting started
+
+**Start here:** read \`openuispec.yaml\` — it's the root manifest that defines the project structure, data model, API endpoints, and generation targets.
+
+### New project (no existing UI code)
+
+1. Define your data model and API endpoints in \`openuispec.yaml\`
+2. Create token files in \`tokens/\` (colors, typography, spacing)
+3. Create screen specs in \`screens/\` (one YAML per screen)
+4. Create navigation flows in \`flows/\`
+5. Ask AI to generate native code from the spec
+
+### Existing project (adopting OpenUISpec)
+
+1. Scan the codebase for existing UI screens
+2. Create a stub for each screen in \`screens/\`:
+   \`\`\`yaml
+   screen_name:
+     semantic: "Brief description of what this screen does"
+     status: stub
+     layout:
+       type: scroll_vertical
+   \`\`\`
+3. Extract design tokens (colors, fonts, spacing) into \`tokens/\`
+4. Fill in \`data_model\` and \`api.endpoints\` in \`openuispec.yaml\`
+5. Spec screens incrementally: \`stub\` → \`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.
+
+## Spec format quick 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
+
+## CLI commands
+
+\`\`\`bash
+openuispec validate             # Validate spec files against schemas
+openuispec validate screens     # Validate only screens
+openuispec drift --target ${targets[0]}    # Check for spec drift
+openuispec drift --snapshot --target ${targets[0]}  # Snapshot current state
+openuispec drift --all          # Include stubs in drift check
+\`\`\`
+
+## Targets
+
+This project generates native code for: **${targetList}**
+
+## Learn more
+
+- Full spec: https://github.com/rsktash/openuispec/blob/main/spec/openuispec-v0.1.md
+- Example app: https://github.com/rsktash/openuispec/tree/main/examples/taskflow
+- Repository: https://github.com/rsktash/openuispec
+`;
+}
+
 function aiRulesBlock(specDir: string, targets: string[]): string {
   const targetList = targets.map((t) => `"${t}"`).join(", ");
   return `
@@ -125,49 +207,67 @@ function aiRulesBlock(specDir: string, targets: string[]): string {
 # ================================
 # 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: ${targetList}
+
+## 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: \`${specDir}/\`
-- Manifest: \`${specDir}/openuispec.yaml\`
-- Always read \`openuispec.yaml\` first to understand the project structure.
-
-## Before making UI changes
-1. Read the relevant spec files (screens, tokens, flows) before modifying any UI code.
-2. If the change requires a spec update, modify the spec files FIRST, then update generated code.
-3. Never modify generated code directly — change the spec and regenerate.
-
-## After modifying spec files
-1. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
-2. Targets in this project: ${targetList}.
-3. Run \`openuispec drift\` to verify no untracked drift remains.
+- Manifest: \`${specDir}/openuispec.yaml\` — always read this first.
+- Tokens: \`${specDir}/tokens/\` — colors, typography, spacing, motion, icons, themes
+- Screens: \`${specDir}/screens/\` — one YAML file per screen
+- Flows: \`${specDir}/flows/\` — multi-step navigation journeys
+- Contracts: \`${specDir}/contracts/\` — UI component definitions
+- Platform: \`${specDir}/platform/\` — per-target overrides (iOS, Android, Web)
+- Locales: \`${specDir}/locales/\` — i18n strings (JSON, ICU MessageFormat)
+
+## 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 \`${specDir}/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 \`${specDir}/tokens/\`.
+4. **Update the manifest** — fill in \`data_model\` and \`api.endpoints\` in \`${specDir}/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
-Screens and flows have a \`status\` field that controls drift tracking:
 - \`stub\` — placeholder, not yet specced. Drift detection skips these.
-- \`draft\` — in progress, actively being specced. Tracked by drift.
+- \`draft\` — actively being specced. Tracked by drift.
 - \`ready\` — fully specified (default if omitted). Tracked by drift.
 
-When adopting OpenUISpec in an existing project:
-1. Create spec files for existing screens as \`status: stub\` initially.
-2. When speccing a screen from existing code, change status to \`draft\`.
-3. Once the spec is complete and reviewed, change to \`ready\` (or remove the field).
-4. Only \`draft\` and \`ready\` screens trigger drift failures in CI.
-
-## Spec file conventions
-- Tokens (colors, typography, spacing, motion, icons) live in \`${specDir}/tokens/\`.
-- Contracts (UI component definitions) live in \`${specDir}/contracts/\`.
-- Screens live in \`${specDir}/screens/\`. One screen per file.
-- Navigation flows live in \`${specDir}/flows/\`.
-- Platform overrides live in \`${specDir}/platform/\`.
-- Localization strings live in \`${specDir}/locales/\`.
-
-## Key rules
-- The spec uses 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback.
-- Custom contracts are prefixed with \`x_\` (e.g., \`x_media_player\`).
-- Data binding uses \`$data:\`, \`$state:\`, \`$param:\`, \`$t:\` prefixes.
-- Actions use typed action objects (navigate, api_call, set_state, confirm, etc.).
-- When adding a new screen, also create the corresponding spec file.
-- When renaming or removing a screen, update the spec and all flow references.
+## 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.
+
+## 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
+
+## 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
 `;
 }
 
@@ -229,6 +329,13 @@ export async function init(): Promise<void> {
       manifestTemplate(name, targets, specDir)
     );
 
+    // ── spec README ──────────────────────────────────────────────
+
+    writeIfMissing(
+      join(root, "README.md"),
+      specReadmeTemplate(name, targets)
+    );
+
     // ── .gitkeep for empty dirs ────────────────────────────────────
 
     for (const d of dirs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",