openuispec 0.1.16 → 0.1.18

package/README.md

@@ -70,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
@@ -99,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
@@ -138,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/examples/taskflow/screens/profile_edit.yaml

@@ -23,6 +23,8 @@ profile_edit:
           - contract: data_display
             variant: inline
             props:
+              title: "user.name"
+              subtitle: "user.email"
               leading:
                 media: "user.avatar"
                 fallback: { initials: "user.name", background: "color.brand.primary" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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

@@ -23,6 +23,18 @@ const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const SCHEMA_DIR = resolve(__dirname);
 
 type AjvInstance = InstanceType<typeof Ajv2020>;
+type UnknownRecord = Record<string, unknown>;
+
+interface UsageLint {
+  path: string;
+  message: string;
+}
+
+interface StandardContractRule {
+  requiredProps?: string[];
+  nonEmptyStringProps?: string[];
+  validate?: (node: UnknownRecord, props: UnknownRecord, path: string) => UsageLint[];
+}
 
 // ── helpers ──────────────────────────────────────────────────────────
 
@@ -49,6 +61,255 @@ function listFiles(dir: string, ext: string): string[] {
   }
 }
 
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function getSingleRootValue(data: unknown): unknown {
+  if (!isRecord(data)) return undefined;
+  const values = Object.values(data);
+  return values.length === 1 ? values[0] : undefined;
+}
+
+const STANDARD_CONTRACT_RULES: Record<string, StandardContractRule> = {
+  action_trigger: {
+    requiredProps: ["label"],
+    nonEmptyStringProps: ["label"],
+  },
+  data_display: {
+    requiredProps: ["title"],
+    nonEmptyStringProps: ["title"],
+  },
+  input_field: {
+    requiredProps: ["label"],
+    nonEmptyStringProps: ["label"],
+    validate(node, props, path) {
+      const inputType = node.input_type;
+      if (inputType === "select" || inputType === "radio") {
+        return hasOwnProp(props, "options")
+          ? []
+          : [{
+              path,
+              message: `contract "input_field" with input_type="${String(inputType)}" requires props.options`,
+            }];
+      }
+      if (inputType === "slider") {
+        return hasOwnProp(props, "range")
+          ? []
+          : [{
+              path,
+              message: 'contract "input_field" with input_type="slider" requires props.range',
+            }];
+      }
+      return [];
+    },
+  },
+  nav_container: {
+    requiredProps: ["items"],
+    validate(_node, props, path) {
+      const items = props.items;
+      if (!Array.isArray(items)) {
+        return [];
+      }
+      const errors: UsageLint[] = [];
+      for (const [index, item] of items.entries()) {
+        const itemPath = `${path}/props/items/${index}`;
+        if (!isRecord(item)) {
+          errors.push({
+            path: itemPath,
+            message: "nav_container items must be objects",
+          });
+          continue;
+        }
+        for (const key of ["id", "label", "icon", "destination"]) {
+          if (!hasOwnProp(item, key)) {
+            errors.push({
+              path: itemPath,
+              message: `nav_container item requires "${key}"`,
+            });
+          }
+        }
+        if (hasOwnProp(item, "label") && !isNonEmptyString(item.label)) {
+          errors.push({
+            path: `${itemPath}/label`,
+            message: 'nav_container item "label" must be a non-empty string',
+          });
+        }
+      }
+      return errors;
+    },
+  },
+  feedback: {
+    requiredProps: ["message"],
+    nonEmptyStringProps: ["message"],
+  },
+  surface: {
+    requiredProps: ["content"],
+  },
+  collection: {
+    requiredProps: ["data", "item_contract", "item_props_map"],
+  },
+};
+
+function hasOwnProp(obj: UnknownRecord, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function validateStandardContractUsage(
+  node: UnknownRecord,
+  path: string,
+): UsageLint[] {
+  const contract = node.contract;
+  if (typeof contract !== "string") return [];
+
+  const rule = STANDARD_CONTRACT_RULES[contract];
+  if (!rule) return [];
+
+  const props = isRecord(node.props) ? node.props : {};
+  const errors: UsageLint[] = [];
+
+  for (const prop of rule.requiredProps ?? []) {
+    if (!hasOwnProp(props, prop)) {
+      errors.push({
+        path,
+        message: `contract "${contract}" requires props.${prop}`,
+      });
+    }
+  }
+
+  for (const prop of rule.nonEmptyStringProps ?? []) {
+    if (hasOwnProp(props, prop) && !isNonEmptyString(props[prop])) {
+      errors.push({
+        path: `${path}/props/${prop}`,
+        message: `props.${prop} for contract "${contract}" must be a non-empty string`,
+      });
+    }
+  }
+
+  errors.push(...(rule.validate?.(node, props, path) ?? []));
+  return errors;
+}
+
+function lintSectionItems(items: unknown, path: string): UsageLint[] {
+  if (!Array.isArray(items)) return [];
+  const errors: UsageLint[] = [];
+
+  for (const [index, item] of items.entries()) {
+    const itemPath = `${path}/${index}`;
+    if (!isRecord(item)) {
+      continue;
+    }
+
+    errors.push(...validateStandardContractUsage(item, itemPath));
+
+    if (Array.isArray(item.children)) {
+      errors.push(...lintSectionItems(item.children, `${itemPath}/children`));
+    }
+  }
+
+  return errors;
+}
+
+function lintScreenLikeDefinition(screenDef: unknown, path: string): UsageLint[] {
+  if (!isRecord(screenDef)) return [];
+  const errors: UsageLint[] = [];
+
+  if (isRecord(screenDef.layout)) {
+    errors.push(
+      ...lintSectionItems(screenDef.layout.sections, `${path}/layout/sections`),
+    );
+  }
+
+  if (isRecord(screenDef.navigation)) {
+    errors.push(
+      ...validateStandardContractUsage(
+        screenDef.navigation,
+        `${path}/navigation`,
+      ),
+    );
+  }
+
+  if (isRecord(screenDef.surfaces)) {
+    for (const [surfaceId, surfaceDef] of Object.entries(screenDef.surfaces)) {
+      const surfacePath = `${path}/surfaces/${surfaceId}`;
+      if (!isRecord(surfaceDef)) {
+        continue;
+      }
+
+      errors.push(...validateStandardContractUsage(surfaceDef, surfacePath));
+
+      const props = isRecord(surfaceDef.props) ? surfaceDef.props : {};
+      if (Array.isArray(props.content)) {
+        errors.push(
+          ...lintSectionItems(props.content, `${surfacePath}/props/content`),
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+function lintScreenFile(dataPath: string): number {
+  const root = getSingleRootValue(loadData(dataPath));
+  const errors = lintScreenLikeDefinition(root, basename(dataPath));
+  if (errors.length === 0) {
+    return 0;
+  }
+
+  console.log(`  FAIL  ${basename(dataPath)} (${errors.length} contract usage error(s))`);
+  for (const error of errors.slice(0, 5)) {
+    console.log(`        [${error.path}] ${error.message}`);
+  }
+  if (errors.length > 5) {
+    console.log(`        ... and ${errors.length - 5} more`);
+  }
+  console.log(
+    "        Hint: built-in contract instances inherit required props from the spec even when contracts/<name>.yaml does not restate them.",
+  );
+  return errors.length;
+}
+
+function lintFlowFile(dataPath: string): number {
+  const root = getSingleRootValue(loadData(dataPath));
+  if (!isRecord(root) || !isRecord(root.screens)) {
+    return 0;
+  }
+
+  const errors: UsageLint[] = [];
+  for (const [screenId, screenEntry] of Object.entries(root.screens)) {
+    if (!isRecord(screenEntry) || !isRecord(screenEntry.screen_inline)) {
+      continue;
+    }
+    errors.push(
+      ...lintScreenLikeDefinition(
+        screenEntry.screen_inline,
+        `${basename(dataPath)}/screens/${screenId}/screen_inline`,
+      ),
+    );
+  }
+
+  if (errors.length === 0) {
+    return 0;
+  }
+
+  console.log(`  FAIL  ${basename(dataPath)} (${errors.length} contract usage error(s))`);
+  for (const error of errors.slice(0, 5)) {
+    console.log(`        [${error.path}] ${error.message}`);
+  }
+  if (errors.length > 5) {
+    console.log(`        ... and ${errors.length - 5} more`);
+  }
+  console.log(
+    "        Hint: flow screen_inline sections follow the same built-in contract requirements as screens/*.yaml.",
+  );
+  return errors.length;
+}
+
 // ── build Ajv instance with all schemas ──────────────────────────────
 
 function buildAjv(): AjvInstance {
@@ -233,7 +494,11 @@ const GROUPS: Record<string, ValidationGroup> = {
       let errors = 0;
       const dir = resolveInclude(projectDir, includes.screens);
       for (const f of listFiles(dir, ".yaml")) {
-        errors += validateFile(ajv, f, `${BASE}screen.schema.json`);
+        const schemaErrors = validateFile(ajv, f, `${BASE}screen.schema.json`);
+        errors += schemaErrors;
+        if (schemaErrors === 0) {
+          errors += lintScreenFile(f);
+        }
       }
       return errors;
     },
@@ -245,7 +510,11 @@ const GROUPS: Record<string, ValidationGroup> = {
       let errors = 0;
       const dir = resolveInclude(projectDir, includes.flows);
       for (const f of listFiles(dir, ".yaml")) {
-        errors += validateFile(ajv, f, `${BASE}flow.schema.json`);
+        const schemaErrors = validateFile(ajv, f, `${BASE}flow.schema.json`);
+        errors += schemaErrors;
+        if (schemaErrors === 0) {
+          errors += lintFlowFile(f);
+        }
       }
       return errors;
     },
@@ -275,18 +544,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;

package/spec/openuispec-v0.1.md

@@ -1392,6 +1392,7 @@ collection:
       grid: "grid"
       table: "table"
       carousel: "region"
+    label: "Derived from visible header text or surrounding section heading; bind with aria-labelledby or platform equivalent rather than a dedicated prop when possible"
     item_role:
       list: "listitem"
       grid: "gridcell"
@@ -1469,6 +1470,8 @@ collection:
       - "Item recycling / virtualization for large datasets"
 ```
 
+Collection containers still need an accessible name, but unlike controls such as buttons or fields, that name usually comes from visible context rather than a dedicated `label` prop. Generators SHOULD connect the collection to a visible heading or header component via `aria-labelledby` or the platform equivalent, and only fall back to an explicit synthesized label when no visible label source exists.
+
 ---
 
 ## 5. Screen composition
@@ -2022,7 +2025,7 @@ Every AI generator, regardless of platform target, MUST:
 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.
+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.
@@ -2039,7 +2042,7 @@ A valid OpenUISpec document:
 - Contains a root `openuispec.yaml` manifest with `spec_version`
 - References only defined tokens, contracts, screens, and flows
 - Has no circular `flow` transitions
-- Has every `required: true` prop satisfied in screen compositions
+- Has every `required: true` prop satisfied in screen compositions, including required props inherited from built-in standard contract families even when `contracts/<name>.yaml` does not restate them
 - Has every `screen.params` satisfied by its callers
 
 ### 8.4 Drift detection