openuispec 0.1.0

package/examples/taskflow/tokens/color.yaml

@@ -0,0 +1,88 @@
+# TaskFlow — Color Tokens
+# Brand: warm indigo + coral accent, neutral warm grays
+
+color:
+  brand:
+    primary:
+      semantic: "Main brand identity — actions, selected states, key UI"
+      reference: "#5B4FE8"
+      range:
+        hue: [240, 250]
+        saturation: [65, 80]
+        lightness: [50, 60]
+      on_color:
+        reference: "#FFFFFF"
+        contrast_min: 4.5
+
+    secondary:
+      semantic: "Accent for highlights, badges, urgency"
+      reference: "#E8634F"
+      range:
+        hue: [10, 18]
+        saturation: [70, 85]
+        lightness: [50, 60]
+      on_color:
+        reference: "#FFFFFF"
+        contrast_min: 4.5
+
+  surface:
+    primary:
+      semantic: "Main content background"
+      reference: "#FFFFFF"
+    secondary:
+      semantic: "Card and grouped backgrounds"
+      reference: "#F7F6F3"
+    tertiary:
+      semantic: "Page canvas behind content"
+      reference: "#EFEEE8"
+
+  text:
+    primary:
+      semantic: "Headings, body text, high emphasis"
+      reference: "#1C1B1A"
+      contrast_min: 7.0
+    secondary:
+      semantic: "Supporting text, descriptions"
+      reference: "#6B6966"
+      contrast_min: 4.5
+    tertiary:
+      semantic: "Placeholders, hints, timestamps"
+      reference: "#9C9A94"
+      contrast_min: 3.0
+    disabled:
+      semantic: "Non-interactive labels"
+      reference: "#C8C6C1"
+
+  semantic:
+    success:
+      reference: "#2D9D5E"
+      range: { hue: [145, 155], saturation: [55, 70], lightness: [35, 45] }
+      on_color: { reference: "#FFFFFF", contrast_min: 4.5 }
+    warning:
+      reference: "#D4920E"
+      range: { hue: [38, 45], saturation: [85, 95], lightness: [40, 50] }
+      on_color: { reference: "#FFFFFF", contrast_min: 3.0 }
+    danger:
+      reference: "#D43B3B"
+      range: { hue: [0, 8], saturation: [65, 80], lightness: [45, 55] }
+      on_color: { reference: "#FFFFFF", contrast_min: 4.5 }
+    info:
+      reference: "#3B82D4"
+      range: { hue: [210, 220], saturation: [60, 75], lightness: [45, 55] }
+      on_color: { reference: "#FFFFFF", contrast_min: 4.5 }
+
+  border:
+    default: { reference: "#E5E3DE", opacity: 0.15 }
+    emphasis: { reference: "#D1CFCA", opacity: 0.3 }
+
+  # App-specific semantic colors
+  priority:
+    low: { reference: "#9CA3AF", semantic: "Low priority indicator" }
+    medium: { reference: "#3B82D4", semantic: "Medium priority indicator" }
+    high: { reference: "#D4920E", semantic: "High priority indicator" }
+    urgent: { reference: "#D43B3B", semantic: "Urgent priority indicator" }
+
+  status:
+    todo: { reference: "#9CA3AF", semantic: "Not started" }
+    in_progress: { reference: "#5B4FE8", semantic: "Currently active" }
+    done: { reference: "#2D9D5E", semantic: "Completed" }

package/examples/taskflow/tokens/elevation.yaml

@@ -0,0 +1,27 @@
+# TaskFlow — Elevation Tokens
+
+elevation:
+  none:
+    semantic: "Flat, no shadow"
+    value: "none"
+
+  sm:
+    semantic: "Subtle lift for hover states, input focus"
+    platform:
+      ios: { shadow: { color: "black", opacity: 0.04, radius: 2, y: 1 } }
+      android: { elevation: 1 }
+      web: { box_shadow: "0 1px 2px rgba(0,0,0,0.04)" }
+
+  md:
+    semantic: "Cards, toasts, popovers"
+    platform:
+      ios: { shadow: { color: "black", opacity: 0.08, radius: 8, y: 2 } }
+      android: { elevation: 3 }
+      web: { box_shadow: "0 2px 8px rgba(0,0,0,0.08)" }
+
+  lg:
+    semantic: "FABs, modals, sheets"
+    platform:
+      ios: { shadow: { color: "black", opacity: 0.12, radius: 16, y: 4 } }
+      android: { elevation: 6 }
+      web: { box_shadow: "0 4px 16px rgba(0,0,0,0.12)" }

package/examples/taskflow/tokens/icons.yaml

@@ -0,0 +1,189 @@
+# TaskFlow — Icon Tokens
+
+icons:
+  sizes:
+    sm:
+      semantic: "Inline indicators, badge icons"
+      value: 16
+    md:
+      semantic: "Default icon size for actions and list items"
+      value: 20
+    lg:
+      semantic: "Prominent icons, empty states, section headers"
+      value: 24
+    xl:
+      semantic: "Hero icons, onboarding illustrations"
+      value: 32
+
+  variants:
+    default: "outline"
+    suffixes:
+      _fill: "Filled/solid variant — used for selected or active states"
+
+  fallback:
+    strategy: "name_passthrough"
+    missing_icon: "questionmark_circle"
+
+  registry:
+    navigation:
+      chevron_right:
+        semantic: "Navigate forward, disclosure indicator"
+        platform:
+          ios: "chevron.right"
+          android: "chevron_right"
+          web: "chevron-right"
+      chevron_left:
+        semantic: "Navigate back"
+        platform:
+          ios: "chevron.left"
+          android: "chevron_left"
+          web: "chevron-left"
+      arrow_uturn_left:
+        semantic: "Undo, revert to previous state"
+        platform:
+          ios: "arrow.uturn.left"
+          android: "undo"
+          web: "undo-2"
+
+    actions:
+      plus:
+        semantic: "Create new item"
+        variants: ["circle"]
+        platform:
+          ios: "plus"
+          android: "add"
+          web: "plus"
+      pencil:
+        semantic: "Edit, modify content"
+        platform:
+          ios: "pencil"
+          android: "edit"
+          web: "pencil"
+      trash:
+        semantic: "Delete, remove item"
+        platform:
+          ios: "trash"
+          android: "delete"
+          web: "trash-2"
+      search:
+        semantic: "Search, find content"
+        platform:
+          ios: "magnifyingglass"
+          android: "search"
+          web: "search"
+      checkmark:
+        semantic: "Confirm, complete, done"
+        variants: ["circle", "circle_fill", "list"]
+        platform:
+          ios: "checkmark"
+          android: "check"
+          web: "check"
+      square_arrow_up:
+        semantic: "Share, export content"
+        platform:
+          ios: "square.and.arrow.up"
+          android: "share"
+          web: "share"
+
+    status:
+      flag:
+        semantic: "Priority indicator, flagged item"
+        variants: ["fill"]
+        platform:
+          ios: "flag"
+          android: "flag"
+          web: "flag"
+      circle_fill:
+        semantic: "Status dot, filled indicator"
+        platform:
+          ios: "circle.fill"
+          android: "circle"
+          web: "circle"
+      exclamationmark_triangle:
+        semantic: "Warning, caution, attention needed"
+        platform:
+          ios: "exclamationmark.triangle"
+          android: "warning"
+          web: "alert-triangle"
+
+    objects:
+      folder:
+        semantic: "Project, collection, file group"
+        variants: ["fill"]
+        platform:
+          ios: "folder"
+          android: "folder"
+          web: "folder"
+      calendar:
+        semantic: "Date, schedule, due date"
+        variants: ["fill"]
+        platform:
+          ios: "calendar"
+          android: "calendar_today"
+          web: "calendar"
+      clock:
+        semantic: "Time, duration, recent"
+        platform:
+          ios: "clock"
+          android: "schedule"
+          web: "clock"
+      tag:
+        semantic: "Label, category, classification"
+        platform:
+          ios: "tag"
+          android: "label"
+          web: "tag"
+      gear:
+        semantic: "Settings, configuration, preferences"
+        variants: ["fill"]
+        platform:
+          ios: "gear"
+          android: "settings"
+          web: "settings"
+      person:
+        semantic: "User, profile, assignee"
+        platform:
+          ios: "person"
+          android: "person"
+          web: "user"
+
+    content:
+      briefcase:
+        semantic: "Work, professional context"
+        platform:
+          ios: "briefcase"
+          android: "work"
+          web: "briefcase"
+      rocket:
+        semantic: "Launch, progress, momentum"
+        platform:
+          ios: "rocket"
+          android: "rocket_launch"
+          web: "rocket"
+      star:
+        semantic: "Favorite, important, featured"
+        platform:
+          ios: "star"
+          android: "star"
+          web: "star"
+      heart:
+        semantic: "Like, love, health"
+        platform:
+          ios: "heart"
+          android: "favorite"
+          web: "heart"
+      lightbulb:
+        semantic: "Idea, tip, suggestion"
+        platform:
+          ios: "lightbulb"
+          android: "lightbulb"
+          web: "lightbulb"
+
+  custom:
+    taskflow:
+      checkmark_list:
+        semantic: "Task list, todo checklist"
+        platform:
+          ios: "checklist"
+          android: "checklist"
+          web: "list-checks"

package/examples/taskflow/tokens/layout.yaml

@@ -0,0 +1,156 @@
+# TaskFlow — Layout Tokens
+# Defines size classes, layout primitives, and adaptive rules
+
+layout:
+  # ============================================================
+  # Size classes — the universal breakpoint vocabulary
+  # ============================================================
+  # Every platform maps to these same semantic classes.
+  # Screens and sections reference size classes by name,
+  # never by pixel value.
+  # ============================================================
+  size_classes:
+    compact:
+      semantic: "Single-column, phone-first layout"
+      width: { max: 600 }
+      columns: 4
+      margin: "spacing.md"
+      content_max_width: null           # full width
+      examples: "iPhone portrait, small Android phones"
+
+    regular:
+      semantic: "Two-column capable, tablet and large phone layouts"
+      width: { min: 601, max: 1024 }
+      columns: 8
+      margin: "spacing.lg"
+      content_max_width: 840
+      examples: "iPad portrait, large phones landscape, small tablets"
+
+    expanded:
+      semantic: "Multi-column, desktop and large tablet layouts"
+      width: { min: 1025 }
+      columns: 12
+      margin: "spacing.xl"
+      content_max_width: 1200
+      examples: "iPad landscape, desktop browsers, large tablets"
+
+  # How each platform resolves size classes
+  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: 600px)"
+      regular: "@media (min-width: 601px) and (max-width: 1024px)"
+      expanded: "@media (min-width: 1025px)"
+
+  # ============================================================
+  # Layout primitives — the building blocks
+  # ============================================================
+  primitives:
+    stack:
+      semantic: "Vertical arrangement, items flow top to bottom"
+      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 arrangement, items flow leading to trailing"
+      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: "2D grid with defined columns"
+      props:
+        columns: { type: "int or adaptive_map", default: 2 }
+        gap: { type: token_ref, default: "spacing.md" }
+        item_min_width: { type: int, required: false }
+      platform_mapping:
+        ios: "LazyVGrid"
+        android: "LazyVerticalGrid"
+        web: "display: grid"
+
+    scroll_vertical:
+      semantic: "Vertically scrollable content area"
+      props:
+        safe_area: { type: bool, default: true }
+        padding: { type: token_ref, required: false }
+        refresh: { type: bool, default: false }
+      platform_mapping:
+        ios: "ScrollView(.vertical)"
+        android: "LazyColumn or verticalScroll"
+        web: "overflow-y: auto"
+
+    split_view:
+      semantic: "Side-by-side panes for master-detail layouts"
+      props:
+        primary_width: { type: "fraction or token_ref", default: 0.35 }
+        divider: { type: bool, default: true }
+        collapse_at: { type: size_class, default: "compact" }
+      platform_mapping:
+        ios: "NavigationSplitView"
+        android: "ListDetailPaneScaffold"
+        web: "CSS Grid with two columns"
+
+    adaptive:
+      semantic: "Changes arrangement based on size class"
+      props:
+        compact: { type: layout_ref, required: true }
+        regular: { type: layout_ref, required: false }
+        expanded: { type: layout_ref, required: false }
+      behavior: "Falls back to nearest smaller class if not specified"
+
+  # ============================================================
+  # Content reflow rules
+  # ============================================================
+  # These define how content behaves when crossing size class
+  # boundaries. AI generators should apply these automatically.
+  # ============================================================
+  reflow_rules:
+    # Full-width buttons become inline on larger screens
+    action_trigger:
+      compact: { full_width: true }
+      regular: { full_width: false }
+
+    # Single column becomes multi-column
+    collection_grid:
+      compact: { columns: 1 }
+      regular: { columns: 2 }
+      expanded: { columns: 3 }
+
+    # Stacked stat cards become horizontal row
+    stat_group:
+      compact: { layout: stack, max_per_row: 2 }
+      regular: { layout: row }
+      expanded: { layout: row }
+
+    # Navigation adapts
+    nav_container:
+      compact: { variant: "tab_bar" }
+      regular: { variant: "rail" }
+      expanded: { variant: "sidebar" }
+
+    # Sheets become side panels on larger screens
+    surface_sheet:
+      compact: { variant: "sheet" }
+      expanded: { variant: "panel" }

package/examples/taskflow/tokens/motion.yaml

@@ -0,0 +1,41 @@
+# TaskFlow — Motion Tokens
+
+motion:
+  duration:
+    instant: 100
+    quick: 200
+    normal: 300
+    slow: 500
+
+  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.97
+    state_change:
+      duration: "quick"
+      property: "opacity, 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"
+    list_reorder:
+      duration: "normal"
+      easing: "emphasis"
+      pattern: "layout-shift"

package/examples/taskflow/tokens/spacing.yaml

@@ -0,0 +1,23 @@
+# TaskFlow — Spacing Tokens
+
+spacing:
+  base_unit: 4
+  platform_flex: 0.15
+
+  scale:
+    none: 0
+    xxs: 2
+    xs: 4
+    sm: 8
+    md: { base: 16, range: [12, 16] }
+    lg: { base: 24, range: [20, 24] }
+    xl: 32
+    xxl: 48
+    xxxl: 64
+
+  aliases:
+    page_margin: { horizontal: md, vertical: md }
+    card_padding: { all: md }
+    section_gap: lg
+    inline_gap: sm
+    stack_gap: md

package/examples/taskflow/tokens/themes.yaml

@@ -0,0 +1,34 @@
+# TaskFlow — Themes
+
+themes:
+  default: "light"
+
+  variants:
+    light:
+      surface.primary: { lightness: [98, 100] }
+      surface.secondary: { lightness: [94, 97] }
+      surface.tertiary: { lightness: [90, 93] }
+      text.primary: { lightness: [5, 12] }
+      text.secondary: { lightness: [38, 45] }
+      text.tertiary: { lightness: [58, 64] }
+      border.default: { opacity: 0.12 }
+
+    dark:
+      surface.primary: { lightness: [10, 14] }
+      surface.secondary: { lightness: [14, 19] }
+      surface.tertiary: { lightness: [7, 11] }
+      text.primary: { lightness: [88, 95] }
+      text.secondary: { lightness: [58, 66] }
+      text.tertiary: { lightness: [42, 50] }
+      border.default: { opacity: 0.18 }
+
+    # Warm-tinted brand variant
+    warm:
+      extends: "light"
+      surface.primary: { hue: 38, saturation: [4, 8], lightness: [96, 99] }
+      surface.secondary: { hue: 38, saturation: [4, 8], lightness: [92, 96] }
+
+  platform:
+    ios: { supports_dynamic: true, system_materials: true }
+    android: { material_you: true, dynamic_color: true }
+    web: { prefers_color_scheme: true, css_custom_properties: true }

package/examples/taskflow/tokens/typography.yaml

@@ -0,0 +1,61 @@
+# TaskFlow — Typography Tokens
+
+typography:
+  font_family:
+    primary:
+      semantic: "All UI text"
+      value: "DM Sans"
+      fallback_strategy: "geometric-sans"
+      platform:
+        ios: { system_alternative: "SF Pro" }
+        android: { system_alternative: "Google Sans" }
+        web: { load_strategy: "swap", source: "google_fonts" }
+
+  scale:
+    display:
+      semantic: "Onboarding hero, empty states"
+      size: { base: 32, range: [28, 36] }
+      weight: 700
+      tracking: -0.02
+      line_height: 1.2
+    heading_lg:
+      semantic: "Screen titles"
+      size: { base: 24, range: [22, 26] }
+      weight: 600
+      tracking: -0.015
+      line_height: 1.3
+    heading:
+      semantic: "Section headers"
+      size: { base: 20, range: [18, 22] }
+      weight: 600
+      tracking: -0.01
+      line_height: 1.35
+    heading_sm:
+      semantic: "Card titles, list group headers"
+      size: { base: 16, range: [15, 17] }
+      weight: 600
+      line_height: 1.4
+    body:
+      semantic: "Primary readable text"
+      size: { base: 16, range: [14, 16] }
+      weight: 400
+      line_height: 1.5
+    body_sm:
+      semantic: "Secondary text, descriptions"
+      size: { base: 14, range: [13, 15] }
+      weight: 400
+      tracking: 0.005
+      line_height: 1.45
+    caption:
+      semantic: "Labels, timestamps, metadata"
+      size: { base: 12, range: [11, 13] }
+      weight: 400
+      tracking: 0.02
+      line_height: 1.35
+    overline:
+      semantic: "Section tags, category labels"
+      size: { base: 11, range: [10, 12] }
+      weight: 600
+      tracking: 0.08
+      transform: uppercase
+      line_height: 1.3

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "openuispec",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A semantic UI specification format for AI-native, platform-native app development",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rsktash/openuispec.git"
+  },
+  "files": [
+    "cli/",
+    "drift/",
+    "schema/",
+    "spec/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "openuispec": "./cli/index.ts"
+  },
+  "scripts": {
+    "validate": "tsx schema/validate.ts",
+    "validate:manifest": "tsx schema/validate.ts manifest",
+    "validate:tokens": "tsx schema/validate.ts tokens",
+    "validate:screens": "tsx schema/validate.ts screens",
+    "validate:flows": "tsx schema/validate.ts flows",
+    "validate:platform": "tsx schema/validate.ts platform",
+    "validate:locales": "tsx schema/validate.ts locales",
+    "drift": "tsx drift/index.ts",
+    "drift:snapshot": "tsx drift/index.ts --snapshot --target"
+  },
+  "dependencies": {
+    "tsx": "^4.19.4",
+    "yaml": "^2.7.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "typescript": "^5.8.3"
+  }
+}