openuispec 0.1.17 → 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.17",
+  "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

@@ -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 {
@@ -146,8 +407,6 @@ function validateFile(
   return errors.length;
 }
 
-// ── validation groups ────────────────────────────────────────────────
-
 // ── includes resolution ──────────────────────────────────────────────
 
 interface Includes {
@@ -233,7 +492,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 +508,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;
     },