openuispec 0.1.5 → 0.1.7

package/cli/init.ts

@@ -118,6 +118,121 @@ 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.
+
+## JSON Schemas (validation & file structure)
+
+**IMPORTANT:** Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure. Schemas are located in the installed package:
+
+\`\`\`
+node_modules/openuispec/schema/
+├── openuispec.schema.json        ← root manifest (openuispec.yaml)
+├── screen.schema.json            ← screen files (screens/*.yaml)
+├── flow.schema.json              ← flow files (flows/*.yaml)
+├── platform.schema.json          ← platform overrides (platform/*.yaml)
+├── locale.schema.json            ← locale files (locales/*.json)
+├── custom-contract.schema.json   ← custom contracts (contracts/*.yaml)
+├── tokens/
+│   ├── color.schema.json         ← tokens/color.yaml
+│   ├── typography.schema.json    ← tokens/typography.yaml
+│   ├── spacing.schema.json       ← tokens/spacing.yaml
+│   ├── elevation.schema.json     ← tokens/elevation.yaml
+│   ├── motion.schema.json        ← tokens/motion.yaml
+│   ├── layout.schema.json        ← tokens/layout.yaml
+│   ├── themes.schema.json        ← tokens/themes.yaml
+│   └── icons.schema.json         ← tokens/icons.yaml
+└── defs/
+    ├── common.schema.json        ← shared types (icons, badges, etc.)
+    ├── action.schema.json        ← 13 action types (discriminated union)
+    ├── data-binding.schema.json  ← data sources, state, params
+    ├── adaptive.schema.json      ← adaptive override pattern
+    └── validation.schema.json    ← validation rule definitions
+\`\`\`
+
+**Workflow:** read the schema → create the YAML file → run \`openuispec validate\` to verify.
+
+**Example spec files:** \`node_modules/openuispec/examples/taskflow/\` — a complete app demonstrating all file types. Read these for real-world examples of screens, flows, tokens, and platform overrides.
+
+## 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 `
@@ -173,6 +288,20 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 2. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
 3. Run \`openuispec drift\` to verify no untracked drift remains.
 
+## JSON Schemas — read before creating spec files
+Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure. Schemas are in the installed package:
+- \`node_modules/openuispec/schema/openuispec.schema.json\` — root manifest
+- \`node_modules/openuispec/schema/screen.schema.json\` — screens
+- \`node_modules/openuispec/schema/flow.schema.json\` — flows
+- \`node_modules/openuispec/schema/platform.schema.json\` — platform overrides
+- \`node_modules/openuispec/schema/locale.schema.json\` — locales
+- \`node_modules/openuispec/schema/custom-contract.schema.json\` — custom contracts
+- \`node_modules/openuispec/schema/tokens/*.schema.json\` — token files (color, typography, spacing, elevation, motion, layout, themes, icons)
+- \`node_modules/openuispec/schema/defs/*.schema.json\` — shared types (actions, data-binding, adaptive, validation, common)
+
+Workflow: read the schema → create the YAML → run \`openuispec validate\`.
+Example spec files: \`node_modules/openuispec/examples/taskflow/\` — a complete app with all file types.
+
 ## 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\`)
@@ -247,6 +376,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.5",
+  "version": "0.1.7",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",