openuispec 0.1.15 → 0.1.17

package/README.md

@@ -17,11 +17,19 @@ The result: each platform feels native, but every app stays consistent because i
 
 ## How it works
 
-![How OpenUISpec works](https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/how-it-works.jpg)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/how-it-works-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/how-it-works-light.png">
+  <img alt="How OpenUISpec works" src="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/how-it-works-light.png">
+</picture>
 
 ## Workflows
 
-![OpenUISpec workflows](https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/workflows.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/workflows-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/workflows-light.png">
+  <img alt="OpenUISpec workflows" src="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/workflows-light.png">
+</picture>
 
 ## Key concepts
 
@@ -62,7 +70,8 @@ openuispec/
 │   ├── flow.schema.json                # Navigation flow schema
 │   ├── platform.schema.json            # Platform adaptation schema
 │   ├── locale.schema.json              # Locale file schema
-│   ├── custom-contract.schema.json    # Custom contract extension schema
+│   ├── contract.schema.json            # Standard contract extension schema
+│   ├── custom-contract.schema.json    # Custom contract extension schema (x_ prefixed)
 │   ├── tokens/
 │   │   ├── color.schema.json           # Color token schema
 │   │   ├── typography.schema.json      # Typography token schema
@@ -91,7 +100,8 @@ openuispec/
 │       │   ├── layout.yaml              # Size classes, primitives, reflow rules
 │       │   ├── themes.yaml              # Light, dark, warm variants
 │       │   └── icons.yaml              # Icon registry with platform mappings
-│       ├── contracts/                   # 7 contract family stubs + custom contracts
+│       ├── 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
@@ -130,7 +140,8 @@ Every file type has a corresponding JSON Schema in `schema/`. **Read the schema
 | `flows/*.yaml` | `flow.schema.json` | `<flow_id>` | [create_task.yaml](./examples/taskflow/flows/create_task.yaml) |
 | `platform/*.yaml` | `platform.schema.json` | `platform` | [ios.yaml](./examples/taskflow/platform/ios.yaml) |
 | `locales/*.json` | `locale.schema.json` | (object) | [en.json](./examples/taskflow/locales/en.json) |
-| `contracts/x_*.yaml` | `custom-contract.schema.json` | `contract` | [x_media_player.yaml](./examples/taskflow/contracts/x_media_player.yaml) |
+| `contracts/<name>.yaml` | `contract.schema.json` | `<contract_name>` | [input_field.yaml](./examples/taskflow/contracts/input_field.yaml) |
+| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` | [x_media_player.yaml](./examples/taskflow/contracts/x_media_player.yaml) |
 | `tokens/color.yaml` | `tokens/color.schema.json` | `color` | [color.yaml](./examples/taskflow/tokens/color.yaml) |
 | `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` | [typography.yaml](./examples/taskflow/tokens/typography.yaml) |
 | `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` | [spacing.yaml](./examples/taskflow/tokens/spacing.yaml) |

package/cli/init.ts

@@ -137,7 +137,7 @@ OpenUISpec is a YAML-based format that describes your app's UI semantically —
 | \`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) |
+| \`contracts/\` | Component contracts — standard extensions (variants, tokens) and custom (\`x_\` prefixed) |
 | \`platform/\` | Platform overrides — per-target (iOS, Android, Web) behaviors |
 | \`locales/\` | Localization — i18n strings (JSON, ICU MessageFormat) |
 
@@ -222,7 +222,8 @@ Root keys: \`color\`, \`typography\`, \`spacing\`, \`elevation\`, \`motion\`, \`
 | \`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\` |
+| \`contracts/<name>.yaml\` | \`contract.schema.json\` | \`<contract_name>\` |
+| \`contracts/x_*.yaml\` | \`custom-contract.schema.json\` | \`<x_name>\` |
 | \`tokens/color.yaml\` | \`tokens/color.schema.json\` | \`color\` |
 | \`tokens/typography.yaml\` | \`tokens/typography.schema.json\` | \`typography\` |
 | \`tokens/spacing.yaml\` | \`tokens/spacing.schema.json\` | \`spacing\` |
@@ -300,7 +301,7 @@ OpenUISpec is a YAML-based spec format that describes an app's UI semantically
 - 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
+- Contracts: \`${specDir}/contracts/\` — standard extensions (variants, tokens) and custom (\`x_\` prefixed)
 - Platform: \`${specDir}/platform/\` — per-target overrides (iOS, Android, Web)
 - Locales: \`${specDir}/locales/\` — i18n strings (JSON, ICU MessageFormat)
 
@@ -373,7 +374,8 @@ Before creating or editing any spec file, read the corresponding JSON Schema. Do
 | \`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\` |
+| \`contracts/<name>.yaml\` | \`contract.schema.json\` | \`<contract_name>\` |
+| \`contracts/x_*.yaml\` | \`custom-contract.schema.json\` | \`<x_name>\` |
 | \`tokens/color.yaml\` | \`tokens/color.schema.json\` | \`color\` |
 | \`tokens/typography.yaml\` | \`tokens/typography.schema.json\` | \`typography\` |
 | \`tokens/spacing.yaml\` | \`tokens/spacing.schema.json\` | \`spacing\` |

package/examples/taskflow/contracts/action_trigger.yaml

@@ -1,7 +1,4 @@
-# action_trigger contract — see spec Section 4 for full definition
-# This file serves as a machine-readable reference for AI generators.
-# The canonical definition lives in spec/openuispec-v0.1.md.
+# action_trigger contract extension
+# Base definition: spec Section 4.1
 
-contract: action_trigger
-spec_section: "4"
-source: "spec/openuispec-v0.1.md"
+action_trigger: {}

package/examples/taskflow/contracts/collection.yaml

@@ -1,7 +1,4 @@
-# collection contract — see spec Section 4 for full definition
-# This file serves as a machine-readable reference for AI generators.
-# The canonical definition lives in spec/openuispec-v0.1.md.
+# collection contract extension
+# Base definition: spec Section 4.7
 
-contract: collection
-spec_section: "4"
-source: "spec/openuispec-v0.1.md"
+collection: {}

package/examples/taskflow/contracts/data_display.yaml

@@ -1,7 +1,4 @@
-# data_display contract — see spec Section 4 for full definition
-# This file serves as a machine-readable reference for AI generators.
-# The canonical definition lives in spec/openuispec-v0.1.md.
+# data_display contract extension
+# Base definition: spec Section 4.2
 
-contract: data_display
-spec_section: "4"
-source: "spec/openuispec-v0.1.md"
+data_display: {}

package/examples/taskflow/contracts/feedback.yaml

@@ -1,7 +1,4 @@
-# feedback contract — see spec Section 4 for full definition
-# This file serves as a machine-readable reference for AI generators.
-# The canonical definition lives in spec/openuispec-v0.1.md.
+# feedback contract extension
+# Base definition: spec Section 4.5
 
-contract: feedback
-spec_section: "4"
-source: "spec/openuispec-v0.1.md"
+feedback: {}

package/examples/taskflow/contracts/input_field.yaml

@@ -1,7 +1,23 @@
-# input_field contract — see spec Section 4 for full definition
-# This file serves as a machine-readable reference for AI generators.
-# The canonical definition lives in spec/openuispec-v0.1.md.
+# input_field contract extension
+# Base definition: spec Section 4.3
+# Add project-specific variants, token overrides, and generation hints.
 
-contract: input_field
-spec_section: "4"
-source: "spec/openuispec-v0.1.md"
+input_field:
+  variants:
+    cut_corner:
+      semantic: "Angled corner input for branded forms"
+      tokens:
+        cut_size: "spacing.sm"
+        border: { color: "color.semantic.border", width: 1 }
+        background: "color.semantic.surface"
+      platform_mapping:
+        ios: { shape: "CutCornerShape", clip: true }
+        android: { shape: "CutCornerShape" }
+        web: { style: "clip-path" }
+      generation:
+        must_handle:
+          - "Cut top-right and bottom-left corners by cut_size"
+          - "Maintain focus ring that follows the cut shape"
+          - "Placeholder text must remain readable against background"
+        should_handle:
+          - "Animate corner cut on focus"

package/examples/taskflow/contracts/nav_container.yaml

@@ -1,7 +1,4 @@
-# nav_container contract — see spec Section 4 for full definition
-# This file serves as a machine-readable reference for AI generators.
-# The canonical definition lives in spec/openuispec-v0.1.md.
+# nav_container contract extension
+# Base definition: spec Section 4.4
 
-contract: nav_container
-spec_section: "4"
-source: "spec/openuispec-v0.1.md"
+nav_container: {}

package/examples/taskflow/contracts/surface.yaml

@@ -1,7 +1,4 @@
-# surface contract — see spec Section 4 for full definition
-# This file serves as a machine-readable reference for AI generators.
-# The canonical definition lives in spec/openuispec-v0.1.md.
+# surface contract extension
+# Base definition: spec Section 4.6
 
-contract: surface
-spec_section: "4"
-source: "spec/openuispec-v0.1.md"
+surface: {}

package/package.json

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

package/schema/contract.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/contract.schema.json",
+  "title": "OpenUISpec Standard Contract Extension",
+  "description": "Extension file for a standard contract — add variants, override tokens, platform mapping, and generation hints",
+  "type": "object",
+  "minProperties": 1,
+  "maxProperties": 1,
+  "propertyNames": {
+    "enum": [
+      "action_trigger",
+      "data_display",
+      "input_field",
+      "nav_container",
+      "feedback",
+      "surface",
+      "collection"
+    ]
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/contract_extension"
+  },
+  "$defs": {
+    "contract_extension": {
+      "type": "object",
+      "description": "Extension definition — all fields are optional, they add to or override the spec-defined contract",
+      "properties": {
+        "variants": {
+          "type": "object",
+          "description": "Named style/behavior variants (e.g. cut_corner, branded, minimal)",
+          "additionalProperties": {
+            "$ref": "#/$defs/variant_def"
+          }
+        },
+        "additional_props": {
+          "type": "object",
+          "description": "Additional props beyond the spec definition",
+          "additionalProperties": {
+            "$ref": "https://openuispec.org/schema/custom-contract.schema.json#/$defs/prop_def"
+          }
+        },
+        "tokens": {
+          "type": "object",
+          "description": "Token overrides at the contract level",
+          "additionalProperties": true
+        },
+        "platform_mapping": {
+          "type": "object",
+          "description": "Platform mapping overrides",
+          "properties": {
+            "ios": { "type": "object", "additionalProperties": true },
+            "android": { "type": "object", "additionalProperties": true },
+            "web": { "type": "object", "additionalProperties": true }
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "generation": {
+          "type": "object",
+          "description": "AI generation compliance hints (merged with spec defaults)",
+          "properties": {
+            "must_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "should_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "may_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "test_cases": {
+          "type": "array",
+          "description": "Additional behavioral test cases",
+          "items": {
+            "$ref": "https://openuispec.org/schema/custom-contract.schema.json#/$defs/test_case"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "variant_def": {
+      "type": "object",
+      "description": "A named variant with semantic description, tokens, platform mapping, and generation hints",
+      "properties": {
+        "semantic": {
+          "type": "string",
+          "description": "Human-readable description of this variant"
+        },
+        "tokens": {
+          "type": "object",
+          "description": "Visual token bindings for this variant",
+          "additionalProperties": true
+        },
+        "platform_mapping": {
+          "type": "object",
+          "description": "Per-platform implementation hints for this variant",
+          "properties": {
+            "ios": { "type": "object", "additionalProperties": true },
+            "android": { "type": "object", "additionalProperties": true },
+            "web": { "type": "object", "additionalProperties": true }
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "generation": {
+          "type": "object",
+          "description": "Generation hints specific to this variant",
+          "properties": {
+            "must_handle": { "type": "array", "items": { "type": "string" } },
+            "should_handle": { "type": "array", "items": { "type": "string" } },
+            "may_handle": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/validate.ts

@@ -275,18 +275,17 @@ const GROUPS: Record<string, ValidationGroup> = {
     },
   },
 
-  custom_contracts: {
-    label: "Custom contracts",
+  contracts: {
+    label: "Contracts",
     run(ajv, projectDir, includes) {
       let errors = 0;
       const dir = resolveInclude(projectDir, includes.contracts);
       for (const f of listFiles(dir, ".yaml")) {
-        if (basename(f).startsWith("x_")) {
-          errors += validateFile(
-            ajv,
-            f,
-            `${BASE}custom-contract.schema.json`,
-          );
+        const name = basename(f);
+        if (name.startsWith("x_")) {
+          errors += validateFile(ajv, f, `${BASE}custom-contract.schema.json`);
+        } else {
+          errors += validateFile(ajv, f, `${BASE}contract.schema.json`);
         }
       }
       return errors;