openuispec 0.1.44 → 0.1.46

package/examples/social-app/openuispec/screens/settings.yaml

@@ -0,0 +1,94 @@
+settings:
+  semantic: "App settings for theme, notifications, privacy, and account preferences"
+  status: draft
+
+  data:
+    preferences:
+      source: "api.preferences.get"
+
+  layout:
+    type: scroll_vertical
+    sections:
+      - id: appearance
+        header: "$t:settings.appearance"
+        children:
+          - contract: input_field
+            input_type: select
+            props:
+              label: "$t:settings.theme"
+              value: "{preferences.theme}"
+              options:
+                - { value: "system", label: "$t:settings.theme_system" }
+                - { value: "light", label: "$t:settings.theme_light" }
+                - { value: "dark", label: "$t:settings.theme_dark" }
+            action:
+              type: api_call
+              endpoint: "api.preferences.update"
+              body: { key: "theme", value: "{selected}" }
+
+      - id: notifications_section
+        header: "$t:settings.notifications"
+        children:
+          - contract: input_field
+            input_type: toggle
+            props:
+              label: "$t:settings.push_notifications"
+              value: "{preferences.push_notifications}"
+            action:
+              type: api_call
+              endpoint: "api.preferences.update"
+              body: { key: "push_notifications", value: "{toggled}" }
+
+          - contract: input_field
+            input_type: toggle
+            props:
+              label: "$t:settings.message_previews"
+              value: "{preferences.message_previews}"
+            action:
+              type: api_call
+              endpoint: "api.preferences.update"
+              body: { key: "message_previews", value: "{toggled}" }
+
+      - id: language
+        header: "$t:settings.language"
+        children:
+          - contract: input_field
+            input_type: toggle
+            props:
+              label: "$t:settings.auto_translate"
+              value: "{preferences.auto_translate}"
+            action:
+              type: api_call
+              endpoint: "api.preferences.update"
+              body: { key: "auto_translate", value: "{toggled}" }
+
+      - id: account
+        header: "$t:settings.account"
+        children:
+          - contract: action_trigger
+            variant: secondary
+            props:
+              label: "$t:settings.edit_profile"
+              icon: "edit"
+            action:
+              type: navigate
+              destination: "screens/edit_profile"
+
+          - contract: action_trigger
+            variant: destructive
+            props:
+              label: "$t:settings.logout"
+            action:
+              type: confirm
+              confirmation:
+                contract: feedback
+                variant: dialog
+                props:
+                  title: "$t:settings.logout"
+                  message: "$t:settings.logout_confirm"
+                  actions:
+                    - label: "$t:common.cancel"
+                      action: { type: dismiss }
+                    - label: "$t:settings.logout"
+                      variant: destructive
+                      action: { type: dismiss }

package/examples/social-app/openuispec/tokens/color.yaml

@@ -0,0 +1,76 @@
+color:
+  brand:
+    primary:
+      semantic: "Main brand identity — warm ink tone"
+      reference: "#1C1B1A"
+      range:
+        hue: [30, 40]
+        saturation: [5, 15]
+        lightness: [8, 14]
+      on_color:
+        reference: "#FFFFFF"
+        contrast_min: 7.0
+    accent:
+      semantic: "Accent highlights — muted indigo"
+      reference: "#5B52A3"
+      range:
+        hue: [250, 260]
+        saturation: [30, 45]
+        lightness: [45, 55]
+      on_color:
+        reference: "#FFFFFF"
+        contrast_min: 4.5
+
+  surface:
+    primary:
+      semantic: "Main content background — warm off-white"
+      reference: "#FAF8F5"
+    secondary:
+      semantic: "Card and grouped backgrounds — warm cream"
+      reference: "#F3F0EB"
+    tertiary:
+      semantic: "Elevated surfaces — soft beige"
+      reference: "#EBE7E0"
+
+  text:
+    primary:
+      semantic: "Headings, body text"
+      reference: "#1C1B1A"
+      contrast_min: 7.0
+    secondary:
+      semantic: "Supporting text, captions"
+      reference: "#6B6966"
+      contrast_min: 4.5
+    tertiary:
+      semantic: "Placeholder text, disabled labels"
+      reference: "#9E9A95"
+
+  semantic:
+    success:
+      reference: "#2D9D5E"
+      on_color:
+        reference: "#FFFFFF"
+        contrast_min: 4.5
+    warning:
+      reference: "#D4920E"
+      on_color:
+        reference: "#1C1B1A"
+        contrast_min: 4.5
+    danger:
+      reference: "#D43B3B"
+      on_color:
+        reference: "#FFFFFF"
+        contrast_min: 4.5
+    info:
+      reference: "#3B82D4"
+      on_color:
+        reference: "#FFFFFF"
+        contrast_min: 4.5
+
+  border:
+    default:
+      semantic: "Default borders and dividers"
+      reference: "#E0DCD6"
+    strong:
+      semantic: "Emphasized borders"
+      reference: "#C5C0B8"

package/examples/social-app/openuispec/tokens/elevation.yaml

@@ -0,0 +1,31 @@
+elevation:
+  sm:
+    semantic: "Cards, subtle lift"
+    value: "sm"
+    platform:
+      ios:
+        shadow: { color: "#1C1B1A", opacity: 0.08, radius: 3, x: 0, y: 1 }
+      android:
+        elevation: 2
+      web:
+        box_shadow: "0 1px 3px rgba(28,27,26,0.08)"
+  md:
+    semantic: "Floating elements, dropdowns"
+    value: "md"
+    platform:
+      ios:
+        shadow: { color: "#1C1B1A", opacity: 0.12, radius: 12, x: 0, y: 4 }
+      android:
+        elevation: 6
+      web:
+        box_shadow: "0 4px 12px rgba(28,27,26,0.12)"
+  lg:
+    semantic: "Modals, sheets"
+    value: "lg"
+    platform:
+      ios:
+        shadow: { color: "#1C1B1A", opacity: 0.16, radius: 24, x: 0, y: 8 }
+      android:
+        elevation: 12
+      web:
+        box_shadow: "0 8px 24px rgba(28,27,26,0.16)"

package/examples/social-app/openuispec/tokens/icons.yaml

@@ -0,0 +1,147 @@
+icons:
+  sizes:
+    sm:
+      semantic: "Small icons — tab bar, inline"
+      value: 20
+    md:
+      semantic: "Default icon size"
+      value: 24
+    lg:
+      semantic: "Large icons — hero, empty state"
+      value: 32
+
+  variants:
+    default: "outline"
+    suffixes:
+      _fill: "filled"
+
+  fallback:
+    strategy: "name_passthrough"
+    missing_icon: "questionmark.circle"
+
+  registry:
+    navigation:
+      home:
+        semantic: "Home feed tab"
+        platform:
+          ios: "house"
+          android: "home"
+          web: "home"
+      discover:
+        semantic: "Discover tab"
+        platform:
+          ios: "compass"
+          android: "explore"
+          web: "explore"
+      notifications:
+        semantic: "Notifications tab"
+        platform:
+          ios: "bell"
+          android: "notifications"
+          web: "notifications"
+      messages:
+        semantic: "Messages tab"
+        platform:
+          ios: "message"
+          android: "chat"
+          web: "chat"
+      profile:
+        semantic: "Profile tab"
+        platform:
+          ios: "person.circle"
+          android: "account_circle"
+          web: "account_circle"
+    actions:
+      search:
+        semantic: "Search action"
+        platform:
+          ios: "magnifyingglass"
+          android: "search"
+          web: "search"
+      create_post:
+        semantic: "Create new post"
+        platform:
+          ios: "plus.circle.fill"
+          android: "add_circle"
+          web: "add_circle"
+      like:
+        semantic: "Like action"
+        variants: [_fill]
+        platform:
+          ios: "heart"
+          android: "favorite_border"
+          web: "favorite_border"
+      comment:
+        semantic: "Comment action"
+        platform:
+          ios: "bubble.right"
+          android: "chat_bubble_outline"
+          web: "chat_bubble_outline"
+      share:
+        semantic: "Share action"
+        platform:
+          ios: "square.and.arrow.up"
+          android: "share"
+          web: "share"
+      bookmark:
+        semantic: "Save/bookmark"
+        variants: [_fill]
+        platform:
+          ios: "bookmark"
+          android: "bookmark_border"
+          web: "bookmark_border"
+      more:
+        semantic: "More options"
+        platform:
+          ios: "ellipsis"
+          android: "more_vert"
+          web: "more_vert"
+      send:
+        semantic: "Send message"
+        platform:
+          ios: "paperplane.fill"
+          android: "send"
+          web: "send"
+      camera:
+        semantic: "Camera/photo"
+        platform:
+          ios: "camera"
+          android: "photo_camera"
+          web: "photo_camera"
+      image:
+        semantic: "Image attachment"
+        platform:
+          ios: "photo"
+          android: "image"
+          web: "image"
+      edit:
+        semantic: "Edit action"
+        platform:
+          ios: "pencil"
+          android: "edit"
+          web: "edit"
+      check:
+        semantic: "Confirm/done"
+        platform:
+          ios: "checkmark"
+          android: "check"
+          web: "check"
+    chrome:
+      back:
+        semantic: "Navigate back"
+        platform:
+          ios: "chevron.left"
+          android: "arrow_back"
+          web: "arrow_back"
+      close:
+        semantic: "Close/dismiss"
+        platform:
+          ios: "xmark"
+          android: "close"
+          web: "close"
+      settings:
+        semantic: "Settings"
+        platform:
+          ios: "gearshape"
+          android: "settings"
+          web: "settings"

package/examples/social-app/openuispec/tokens/layout.yaml

@@ -0,0 +1,37 @@
+layout:
+  size_classes:
+    compact:
+      semantic: "Phones in portrait"
+      width:
+        max: 600
+      columns: 4
+      margin: "md"
+    regular:
+      semantic: "Tablets, phones in landscape"
+      width:
+        min: 601
+        max: 1024
+      columns: 8
+      margin: "lg"
+    expanded:
+      semantic: "Desktops, large tablets"
+      width:
+        min: 1025
+      columns: 12
+      margin: "xl"
+
+  platform_mapping:
+    ios:
+      uses: "UITraitCollection"
+      compact: "compact"
+      regular: "regular"
+    android:
+      uses: "WindowSizeClass"
+      compact: "Compact"
+      regular: "Medium"
+      expanded: "Expanded"
+    web:
+      uses: "media-query"
+      compact: "max-width: 600px"
+      regular: "min-width: 601px and max-width: 1024px"
+      expanded: "min-width: 1025px"

package/examples/social-app/openuispec/tokens/motion.yaml

@@ -0,0 +1,28 @@
+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: "respect-system"
+
+  patterns:
+    press_feedback:
+      duration: "instant"
+      easing: "default"
+      property: "transform"
+    slide_up:
+      duration: "normal"
+      easing: "enter"
+      property: "transform"
+    fade:
+      duration: "quick"
+      easing: "default"
+      property: "opacity"

package/examples/social-app/openuispec/tokens/spacing.yaml

@@ -0,0 +1,19 @@
+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
+
+  aliases:
+    page_margin: { horizontal: md, vertical: md }
+    card_padding: { all: md }
+    section_gap: lg
+    list_item_gap: sm

package/examples/social-app/openuispec/tokens/themes.yaml

@@ -0,0 +1,31 @@
+themes:
+  default: "light"
+
+  variants:
+    light:
+      color.surface.primary: { lightness: 98 }
+      color.surface.secondary: { lightness: 95 }
+      color.surface.tertiary: { lightness: 91 }
+      color.text.primary: { lightness: 10 }
+      color.text.secondary: { lightness: 42 }
+      color.text.tertiary: { lightness: 62 }
+
+    dark:
+      extends: "light"
+      color.surface.primary: { lightness: 10 }
+      color.surface.secondary: { lightness: 15 }
+      color.surface.tertiary: { lightness: 21 }
+      color.text.primary: { lightness: 98 }
+      color.text.secondary: { lightness: 65 }
+      color.text.tertiary: { lightness: 42 }
+
+  platform:
+    ios:
+      supports_dynamic: true
+      system_materials: true
+    android:
+      material_you: false
+      dynamic_color: false
+    web:
+      prefers_color_scheme: true
+      css_custom_properties: true

package/examples/social-app/openuispec/tokens/typography.yaml

@@ -0,0 +1,50 @@
+typography:
+  font_family:
+    primary:
+      semantic: "All UI text"
+      value: "DM Sans"
+      platform:
+        ios: { system_alternative: "SF Pro" }
+        android: { system_alternative: "Google Sans" }
+
+  scale:
+    display:
+      semantic: "Hero text, onboarding"
+      size: { base: 32, range: [28, 36] }
+      weight: 700
+      line_height: 1.2
+    heading_lg:
+      semantic: "Screen titles"
+      size: { base: 24, range: [22, 26] }
+      weight: 600
+      line_height: 1.3
+    heading_md:
+      semantic: "Section titles"
+      size: { base: 20, range: [18, 22] }
+      weight: 600
+      line_height: 1.3
+    heading_sm:
+      semantic: "Card titles, list headings"
+      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 body text"
+      size: { base: 14, range: [13, 15] }
+      weight: 400
+      line_height: 1.5
+    caption:
+      semantic: "Labels, timestamps, metadata"
+      size: { base: 12, range: [11, 13] }
+      weight: 400
+      line_height: 1.4
+    button:
+      semantic: "Button labels"
+      size: { base: 16, range: [14, 16] }
+      weight: 600
+      line_height: 1.0

package/examples/social-app/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "social-app",
+  "private": true,
+  "version": "0.0.0",
+  "description": "OpenUISpec test project wired to the local ../openuispec checkout",
+  "scripts": {
+    "openuispec": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts",
+    "validate": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts validate",
+    "validate:semantic": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts validate semantic",
+    "status": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts status"
+  }
+}

package/mcp-server/index.ts

@@ -91,6 +91,12 @@ POST-GENERATION (do this EVERY TIME after writing UI code):
    - Navigation targets match flow definitions
    Report any real gaps found and fix them before finishing.
 
+CREATING NEW SPEC FILES:
+When you need to create or edit spec files and are unsure of the format:
+1. Call openuispec_spec_types to discover available spec types.
+2. Call openuispec_spec_schema with the specific type to get the full JSON schema.
+3. Write the spec file following the schema exactly.
+
 Skip these tools ONLY when the request is purely non-UI (API logic, database, infrastructure, etc.)
 or explicitly platform-specific polish that doesn't affect shared UI semantics.`,
   }
@@ -363,6 +369,69 @@ server.registerTool(
   }
 );
 
+// ── schema type catalog ─────────────────────────────────────────
+
+const SCHEMA_CATALOG: Record<string, { file: string; title: string; description: string }> = {
+  manifest:         { file: "openuispec.schema.json",            title: "Root Manifest",    description: "Root manifest (openuispec.yaml): project info, includes, generation targets, data model, API endpoints, formatters, mappers" },
+  screen:           { file: "screen.schema.json",                title: "Screen",           description: "Screen composition: layout, sections, navigation, surfaces, data/state bindings, adaptive breakpoints" },
+  flow:             { file: "flow.schema.json",                  title: "Flow",             description: "Navigation flow definitions: steps, transitions, guards, and entry points" },
+  platform:         { file: "platform.schema.json",              title: "Platform",         description: "Platform-specific generation config: architecture, naming, CSS framework, component mapping" },
+  contract:         { file: "contract.schema.json",              title: "Contract",         description: "Built-in UI contract definitions: variants, props, must_handle states, generation hints" },
+  "custom-contract":{ file: "custom-contract.schema.json",       title: "Custom Contract",  description: "User-defined UI contract definitions (x_ prefixed)" },
+  locale:           { file: "locale.schema.json",                title: "Locale",           description: "Locale translation files: flat key-value string maps" },
+  "tokens/color":       { file: "tokens/color.schema.json",       title: "Color Tokens",       description: "Color tokens: brand, surface, text, semantic, border groups with HSL ranges and contrast" },
+  "tokens/typography":  { file: "tokens/typography.schema.json",   title: "Typography Tokens",  description: "Typography tokens: font families, sizes, weights, line heights, letter spacing" },
+  "tokens/spacing":     { file: "tokens/spacing.schema.json",     title: "Spacing Tokens",     description: "Spacing tokens: named spacing scale values" },
+  "tokens/elevation":   { file: "tokens/elevation.schema.json",   title: "Elevation Tokens",   description: "Elevation tokens: shadow definitions per level" },
+  "tokens/motion":      { file: "tokens/motion.schema.json",      title: "Motion Tokens",      description: "Motion tokens: animation duration and easing curves" },
+  "tokens/layout":      { file: "tokens/layout.schema.json",      title: "Layout Tokens",      description: "Layout tokens: radii, breakpoints, max widths, grid columns" },
+  "tokens/themes":      { file: "tokens/themes.schema.json",      title: "Theme Tokens",       description: "Theme definitions: token overrides per theme (e.g. dark mode)" },
+  "tokens/icons":       { file: "tokens/icons.schema.json",       title: "Icon Tokens",        description: "Icon tokens: icon set, size scale, default size" },
+};
+
+// ── tool: openuispec_spec_types ──────────────────────────────────
+
+server.registerTool(
+  "openuispec_spec_types",
+  {
+    description: "List all available OpenUISpec spec types with brief descriptions. Use this to discover what kinds of spec files can be created and what schema format each one follows. Call openuispec_spec_schema with a specific type to get the full JSON schema.",
+  },
+  async () => {
+    const types = Object.entries(SCHEMA_CATALOG).map(([type, info]) => ({
+      type,
+      title: info.title,
+      description: info.description,
+    }));
+    return toolResult(types);
+  }
+);
+
+// ── tool: openuispec_spec_schema ─────────────────────────────────
+
+server.registerTool(
+  "openuispec_spec_schema",
+  {
+    description: "Get the full JSON schema for a specific OpenUISpec spec type. Returns the complete schema definition so you know the exact format when creating or editing spec files. Call openuispec_spec_types first to see available types.",
+    inputSchema: {
+      type: z.string().describe("Spec type to get schema for (e.g. 'screen', 'tokens/color', 'contract'). Use openuispec_spec_types to list all available types."),
+    },
+  },
+  async ({ type }) => {
+    const entry = SCHEMA_CATALOG[type];
+    if (!entry) {
+      return toolError(`Unknown spec type "${type}". Call openuispec_spec_types to see available types.`);
+    }
+    try {
+      const __dirname = dirname(fileURLToPath(import.meta.url));
+      const schemaPath = join(__dirname, "..", "schema", entry.file);
+      const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+      return toolResult({ type, title: entry.title, schema });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── start server ─────────────────────────────────────────────────────
 
 export async function startMcpServer() {

package/package.json

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