openuispec 0.1.18 → 0.1.19

package/examples/todo-orbit/openuispec/tokens/icons.yaml

@@ -0,0 +1,92 @@
+icons:
+  sizes:
+    sm:
+      semantic: "Small inline icon size"
+      value: 16
+    md:
+      semantic: "Default icon size for actions and list items"
+      value: 20
+    lg:
+      semantic: "Prominent icon size for empty states and hero elements"
+      value: 24
+
+  variants:
+    default: "outline"
+    suffixes:
+      _fill: "Filled variant for active or completed states"
+
+  fallback:
+    strategy: "name_passthrough"
+    missing_icon: "questionmark_circle"
+
+  registry:
+    actions:
+      plus:
+        semantic: "Create a new task or item"
+        platform:
+          ios: "plus"
+          android: "add"
+          web: "plus"
+      search:
+        semantic: "Search tasks"
+        platform:
+          ios: "magnifyingglass"
+          android: "search"
+          web: "search"
+      trash:
+        semantic: "Delete a task"
+        platform:
+          ios: "trash"
+          android: "delete"
+          web: "trash-2"
+      checkmark:
+        semantic: "Confirm completion"
+        variants: ["circle", "circle_fill", "list"]
+        platform:
+          ios: "checkmark"
+          android: "check"
+          web: "check"
+
+    objects:
+      calendar:
+        semantic: "Date and scheduling"
+        platform:
+          ios: "calendar"
+          android: "calendar_today"
+          web: "calendar"
+      gear:
+        semantic: "Settings and preferences"
+        variants: ["fill"]
+        platform:
+          ios: "gear"
+          android: "settings"
+          web: "settings"
+      globe:
+        semantic: "Language and locale selection"
+        platform:
+          ios: "globe"
+          android: "language"
+          web: "languages"
+      flag:
+        semantic: "Priority marker"
+        variants: ["fill"]
+        platform:
+          ios: "flag"
+          android: "flag"
+          web: "flag"
+
+  custom:
+    todo_orbit:
+      checkmark_list:
+        semantic: "Todo list navigation icon"
+        platform:
+          ios: "checklist"
+          android: "checklist"
+          web: "list-checks"
+      chart_line:
+        semantic: "Analytics and trend visualization icon"
+        variants: ["fill"]
+        platform:
+          ios: "chart.line.uptrend.xyaxis"
+          android: "insert_chart"
+          web: "chart-line"

package/examples/todo-orbit/openuispec/tokens/layout.yaml

@@ -0,0 +1,107 @@
+layout:
+  size_classes:
+    compact:
+      semantic: "Phone-first single-column layouts"
+      width: { max: 640 }
+      columns: 4
+      margin: "spacing.md"
+      content_max_width: null
+      examples: "Phones in portrait, narrow browser windows"
+    regular:
+      semantic: "Tablet portrait and large phone landscape layouts"
+      width: { min: 641, max: 1024 }
+      columns: 8
+      margin: "spacing.lg"
+      content_max_width: 860
+      examples: "Tablets in portrait, wide phones in landscape"
+    expanded:
+      semantic: "Desktop and large-tablet multi-column layouts"
+      width: { min: 1025 }
+      columns: 12
+      margin: "spacing.xl"
+      content_max_width: 1240
+      examples: "Desktop browsers, tablets in landscape"
+
+  platform_mapping:
+    ios:
+      uses: "UIUserInterfaceSizeClass"
+      compact: ".compact horizontal"
+      regular: ".regular horizontal"
+      expanded: ".regular horizontal + width > 1024"
+    android:
+      uses: "WindowSizeClass"
+      compact: "WindowWidthSizeClass.Compact"
+      regular: "WindowWidthSizeClass.Medium"
+      expanded: "WindowWidthSizeClass.Expanded"
+    web:
+      uses: "media queries"
+      compact: "@media (max-width: 640px)"
+      regular: "@media (min-width: 641px) and (max-width: 1024px)"
+      expanded: "@media (min-width: 1025px)"
+
+  primitives:
+    stack:
+      semantic: "Vertical content flow"
+      props:
+        spacing: { type: token_ref, default: "spacing.md" }
+        align: { type: enum, values: [leading, center, trailing, stretch], default: stretch }
+        padding: { type: token_ref, required: false }
+      platform_mapping:
+        ios: "VStack"
+        android: "Column"
+        web: "flex-direction: column"
+    row:
+      semantic: "Horizontal content flow"
+      props:
+        spacing: { type: token_ref, default: "spacing.sm" }
+        align: { type: enum, values: [top, center, bottom, baseline, stretch], default: center }
+        justify: { type: enum, values: [start, center, end, space-between, space-around], default: start }
+        wrap: { type: bool, default: false }
+      platform_mapping:
+        ios: "HStack"
+        android: "Row"
+        web: "flex-direction: row"
+    grid:
+      semantic: "Responsive 2D arrangement"
+      props:
+        columns: { type: "int or adaptive_map", default: 2 }
+        gap: { type: token_ref, default: "spacing.md" }
+      platform_mapping:
+        ios: "LazyVGrid"
+        android: "LazyVerticalGrid"
+        web: "display: grid"
+    scroll_vertical:
+      semantic: "Scrollable vertical canvas"
+      props:
+        safe_area: { type: bool, default: true }
+        padding: { type: token_ref, required: false }
+      platform_mapping:
+        ios: "ScrollView(.vertical)"
+        android: "LazyColumn or verticalScroll"
+        web: "overflow-y: auto"
+    split_view:
+      semantic: "Master-detail two-pane layout"
+      props:
+        primary_width: { type: "fraction or token_ref", default: 0.36 }
+        divider: { type: bool, default: true }
+        collapse_at: { type: size_class, default: "compact" }
+      platform_mapping:
+        ios: "NavigationSplitView"
+        android: "ListDetailPaneScaffold"
+        web: "CSS Grid with two columns"
+
+  reflow_rules:
+    action_trigger:
+      compact: { full_width: true }
+      regular: { full_width: false }
+    nav_container:
+      compact: { variant: "tab_bar" }
+      regular: { variant: "rail" }
+      expanded: { variant: "sidebar" }
+    task_actions:
+      compact: { layout: stack }
+      regular: { layout: row }
+    stat_group:
+      compact: { layout: grid, columns: 2 }
+      regular: { layout: row }
+      expanded: { layout: row }

package/examples/todo-orbit/openuispec/tokens/motion.yaml

@@ -0,0 +1,39 @@
+motion:
+  duration:
+    instant: 100
+    quick: 180
+    normal: 280
+    slow: 420
+
+  easing:
+    default: "ease-out"
+    enter: "ease-out"
+    exit: "ease-in"
+    emphasis: "cubic-bezier(0.2, 0, 0, 1)"
+
+  reduced_motion: "remove-animation"
+
+  patterns:
+    press_feedback:
+      duration: "instant"
+      property: "scale"
+      value: 0.98
+    state_change:
+      duration: "quick"
+      property: "opacity, border-color, background"
+    screen_enter:
+      duration: "normal"
+      easing: "enter"
+      pattern: "slide-from-trailing"
+    screen_exit:
+      duration: "quick"
+      easing: "exit"
+      pattern: "slide-to-leading"
+    checkbox_check:
+      duration: "quick"
+      easing: "emphasis"
+      pattern: "scale-bounce"
+    modal_present:
+      duration: "normal"
+      easing: "enter"
+      pattern: "fade-and-lift"

package/examples/todo-orbit/openuispec/tokens/spacing.yaml

@@ -0,0 +1,18 @@
+spacing:
+  base_unit: 4
+  platform_flex: 0.15
+
+  scale:
+    none: 0
+    xs: 4
+    sm: 8
+    md: { base: 16, range: [12, 16] }
+    lg: { base: 24, range: [20, 24] }
+    xl: 32
+    xxl: 40
+
+  aliases:
+    page_margin: { horizontal: md, vertical: md }
+    card_padding: { all: md }
+    section_gap: lg
+    inline_gap: sm

package/examples/todo-orbit/openuispec/tokens/themes.yaml

@@ -0,0 +1,23 @@
+themes:
+  default: "light"
+
+  variants:
+    light:
+      surface.primary: { lightness: [97, 100] }
+      surface.secondary: { lightness: [93, 97] }
+      surface.tertiary: { lightness: [89, 94] }
+      text.primary: { lightness: [8, 14] }
+      text.secondary: { lightness: [36, 46] }
+      border.default: { opacity: 0.22 }
+    dark:
+      surface.primary: { lightness: [10, 14] }
+      surface.secondary: { lightness: [14, 18] }
+      surface.tertiary: { lightness: [18, 24] }
+      text.primary: { lightness: [90, 95] }
+      text.secondary: { lightness: [62, 70] }
+      border.default: { opacity: 0.18 }
+
+  platform:
+    ios: { supports_dynamic: true }
+    android: { dynamic_color: true }
+    web: { prefers_color_scheme: true, css_custom_properties: true }

package/examples/todo-orbit/openuispec/tokens/typography.yaml

@@ -0,0 +1,52 @@
+typography:
+  font_family:
+    primary:
+      semantic: "Main UI typeface for the todo app"
+      value: "Manrope"
+      fallback_strategy: "modern-sans"
+      platform:
+        ios: { system_alternative: "SF Pro" }
+        android: { system_alternative: "Google Sans" }
+        web: { load_strategy: "swap", source: "google_fonts" }
+
+  scale:
+    display:
+      semantic: "Large empty-state and hero copy"
+      size: { base: 30, range: [28, 34] }
+      weight: 700
+      tracking: -0.02
+      line_height: 1.15
+    heading_lg:
+      semantic: "Primary screen titles"
+      size: { base: 24, range: [22, 28] }
+      weight: 700
+      tracking: -0.02
+      line_height: 1.2
+    heading:
+      semantic: "Section headings and modal titles"
+      size: { base: 18, range: [17, 20] }
+      weight: 600
+      tracking: -0.01
+      line_height: 1.3
+    heading_sm:
+      semantic: "Compact emphasized labels"
+      size: { base: 15, range: [14, 17] }
+      weight: 600
+      line_height: 1.35
+    body:
+      semantic: "Primary body copy"
+      size: { base: 16, range: [15, 17] }
+      weight: 400
+      line_height: 1.5
+    body_sm:
+      semantic: "Supporting text and subtitles"
+      size: { base: 14, range: [13, 15] }
+      weight: 400
+      tracking: 0.004
+      line_height: 1.45
+    caption:
+      semantic: "Tiny labels and metadata"
+      size: { base: 12, range: [11, 13] }
+      weight: 500
+      tracking: 0.015
+      line_height: 1.35

package/package.json

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

package/schema/validate.ts

@@ -407,8 +407,6 @@ function validateFile(
   return errors.length;
 }
 
-// ── validation groups ────────────────────────────────────────────────
-
 // ── includes resolution ──────────────────────────────────────────────
 
 interface Includes {

package/spec/openuispec-v0.1.md

@@ -13,6 +13,8 @@
 
 OpenUISpec is not a cross-platform framework. It is a **semantic design language specification** from which AI generates native platform code. The spec describes *what* UI does and *how it should feel* — never *which widget to use*.
 
+OpenUISpec is a shared UI sync language for native products, optimized for solo developers but also intended for teams that need a durable synchronization layer between product intent and platform code. It is not a pixel-perfect design description and it does not aim to erase platform differences. Its goal is semantic consistency with bounded native variation.
+
 ### Core principles
 
 1. **Semantic over visual.** The spec defines behavioral intent, not pixel layouts. A "primary action trigger" maps to `Button` in SwiftUI, `Button` in Compose, and `<button>` in HTML — the spec never says "button."
@@ -1720,6 +1722,8 @@ Layout primitives are the building blocks for arranging content. They replace th
 | `split_view` | Side-by-side master-detail | `NavigationSplitView` | `ListDetailPaneScaffold` | CSS Grid |
 | `adaptive` | Changes layout per size class | — | — | — |
 
+Layout primitives must remain usable across the size classes they are generated for. Multi-pane or master-detail patterns require an explicit compact fallback rather than assuming large-screen behavior will degrade correctly.
+
 Each primitive has typed props:
 
 ```yaml
@@ -2022,17 +2026,21 @@ This section defines the rules any AI code generator must follow when producing
 Every AI generator, regardless of platform target, MUST:
 
 1. Produce **compilable code** that builds without errors on the target platform.
-2. Map every `contract` reference to the correct native widget per `platform_mapping`.
-3. Apply all `tokens` values within their declared `range` constraints.
-4. Implement every `state` declared in each used contract, including transitions.
-5. Set correct `a11y.role` and `a11y.label` for every component instance. For contextual containers such as `collection`, derive the label from the visible heading/header via `aria-labelledby` or the platform equivalent when possible instead of requiring a dedicated prop.
-6. Respect `themes` by generating light/dark mode support.
-7. Handle `empty`, `loading`, and `error` states for `collection` contracts.
-8. Wire all `action.navigate` declarations to the platform's navigation system.
-9. Apply `motion.reduced_motion` preferences globally.
-10. Implement all three size classes (`compact`, `regular`, `expanded`) and apply `adaptive` overrides from screen files.
-11. Validate all `props` types and report spec errors before generating code.
-12. Generate platform-native localization resources from JSON locale files when `i18n` config is present (see Section 11).
+2. Refresh its knowledge of the current target platform implementation model before generation when the output depends on toolchain-specific conventions, project formats, packaging rules, resource wiring, or fast-moving framework APIs.
+3. Map every `contract` reference to the correct native widget per `platform_mapping`.
+4. Apply all `tokens` values within their declared `range` constraints.
+5. Implement every `state` declared in each used contract, including transitions.
+6. Set correct `a11y.role` and `a11y.label` for every component instance. For contextual containers such as `collection`, derive the label from the visible heading/header via `aria-labelledby` or the platform equivalent when possible instead of requiring a dedicated prop.
+7. Respect `themes` by generating light/dark mode support.
+8. Handle `empty`, `loading`, and `error` states for `collection` contracts.
+9. Wire all `action.navigate` declarations to the platform's navigation system.
+10. Apply `motion.reduced_motion` preferences globally.
+11. Implement all three size classes (`compact`, `regular`, `expanded`) and apply `adaptive` overrides from screen files.
+12. Validate all `props` types and report spec errors before generating code.
+13. Generate platform-native localization resources from JSON locale files when `i18n` config is present (see Section 11).
+14. Emit a valid native project or target configuration that bundles every generated runtime resource, including localization files, assets, and generated metadata. A generated resource file that is not connected to the runnable target is non-compliant.
+15. Adapt navigation and container patterns for every supported size class and form factor. A generator may not assume that a large-screen or multi-pane layout will remain usable on compact layouts without an explicit fallback.
+16. Preserve required contract semantics when mapping to native widgets. A platform-native substitution may change the implementation primitive, but it may not drop required token-driven shapes, borders, visual states, or interaction semantics declared by the contract.
 
 ### 8.3 Validation
 
@@ -2975,7 +2983,7 @@ Generators produce platform-native localization resources from the JSON source:
 
 | Platform | Output format | Plurals | Notes |
 |----------|--------------|---------|-------|
-| **iOS** | `.xcstrings` (Xcode 15+) | Built-in plural rules | ICU plurals map to `.stringsdict` entries within `.xcstrings` |
+| **iOS** | `.xcstrings` (Xcode 15+) or correctly bundled `.strings` resources | Built-in plural rules | ICU plurals map to `.stringsdict` entries within `.xcstrings`; generated locale resources must be attached to the runnable target and resolvable at runtime |
 | **Android** | `res/values-{locale}/strings.xml` + `plurals.xml` | `<plurals>` element | ICU selects map to conditional logic in generated code |
 | **Web** | JSON bundles per locale | `react-intl` / `i18next` ICU plugin | Direct ICU MessageFormat — no conversion needed |
 
@@ -2993,6 +3001,7 @@ i18n:
 **MUST:**
 - Resolve every `$t:key` reference to the corresponding locale string
 - Generate platform-native locale files from JSON sources for each supported locale
+- Ensure generated locale files are actually bundled by the runnable platform target and available at runtime
 - Pass `t_params` data paths to ICU placeholders at runtime
 - Apply `$direction` from the active locale to layout direction
 - Use the `fallback_strategy` for missing keys (default: fall back to `default_locale`)
@@ -3201,6 +3210,61 @@ ios:
 - Generate test code based on `test_cases`
 - Add platform-specific enhancements beyond what the contract specifies
 
+### 12.8 Extending standard contracts
+
+The 7 built-in contract families (Section 4) can be extended per-project using `contracts/<name>.yaml` files. Extensions add project-specific **variants**, **token overrides**, **platform mapping**, and **generation hints** without redefining the base contract. The base definition (props, states, a11y) remains authoritative from the spec.
+
+```yaml
+# contracts/input_field.yaml
+input_field:
+  variants:
+    cut_corner:
+      semantic: "Angled corner input for branded forms"
+      tokens:
+        cut_size: "spacing.sm"
+        border: { color: "color.semantic.border", width: 1 }
+      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"
+        should_handle:
+          - "Animate corner cut on focus"
+```
+
+**Root key:** The contract family name (e.g. `input_field`, `action_trigger`). Not `x_` prefixed — that is reserved for fully custom contracts.
+
+**Available extension fields** (all optional):
+
+| Field | Purpose |
+|-------|---------|
+| `variants` | Named style/behavior presets with their own tokens, platform_mapping, and generation hints |
+| `additional_props` | Props beyond what the spec defines for this contract |
+| `tokens` | Contract-level token overrides |
+| `platform_mapping` | Per-platform implementation hints |
+| `generation` | AI generation hints (must_handle, should_handle, may_handle) |
+| `test_cases` | Behavioral verification scenarios |
+
+**Usage in screens:** Reference a variant by name in the `variant` field of a contract instance:
+
+```yaml
+- contract: input_field
+  variant: cut_corner
+  props:
+    label: "Email"
+    input_type: email
+```
+
+**Key differences from custom contracts (Section 12.1–12.7):**
+
+- Standard extensions do **not** redefine `semantic`, `props`, `states`, or `a11y` — these come from the spec
+- Required props from the base contract still apply (e.g. `input_field` always requires `props.label`)
+- An empty extension (`input_field: {}`) is valid and means "use the spec definition as-is"
+- Validated against `contract.schema.json`, not `custom-contract.schema.json`
+
 ---
 
 ## 13. Form validation and field dependencies