openuispec 0.1.0

package/schema/screen.schema.json

@@ -0,0 +1,346 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/screen.schema.json",
+  "title": "OpenUISpec Screen",
+  "description": "Screen composition \u2014 a single root key (screen name) mapping to the screen definition",
+  "type": "object",
+  "minProperties": 1,
+  "maxProperties": 1,
+  "additionalProperties": {
+    "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/screen_def"
+  },
+  "$defs": {
+    "screen_def": {
+      "type": "object",
+      "description": "A screen definition with layout, data, state, navigation, and surfaces",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "stub",
+            "draft",
+            "ready"
+          ]
+        },
+        "params": {
+          "$ref": "https://openuispec.org/schema/defs/data-binding.schema.json#/$defs/params_map"
+        },
+        "data": {
+          "$ref": "https://openuispec.org/schema/defs/data-binding.schema.json#/$defs/data_map"
+        },
+        "state": {
+          "$ref": "https://openuispec.org/schema/defs/data-binding.schema.json#/$defs/state_map"
+        },
+        "navigation": {
+          "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/navigation_def"
+        },
+        "layout": {
+          "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/layout_def"
+        },
+        "surfaces": {
+          "type": "object",
+          "description": "Named surface definitions (sheets, modals, panels)",
+          "additionalProperties": {
+            "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/surface_def"
+          }
+        }
+      },
+      "required": [
+        "semantic",
+        "layout"
+      ],
+      "additionalProperties": false
+    },
+    "navigation_def": {
+      "type": "object",
+      "description": "Navigation shell definition",
+      "properties": {
+        "contract": {
+          "const": "nav_container"
+        },
+        "variant": {
+          "type": "string"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "type": "array",
+              "items": {
+                "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/nav_item"
+              }
+            },
+            "selected": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": true
+        },
+        "adaptive": {
+          "$ref": "https://openuispec.org/schema/defs/adaptive.schema.json"
+        }
+      },
+      "required": [
+        "contract",
+        "props"
+      ],
+      "additionalProperties": false
+    },
+    "nav_item": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "icon": {
+          "type": "string"
+        },
+        "icon_active": {
+          "type": "string"
+        },
+        "destination": {
+          "type": "string"
+        },
+        "badge": {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/badge_config"
+        }
+      },
+      "required": [
+        "id",
+        "label",
+        "icon",
+        "destination"
+      ],
+      "additionalProperties": false
+    },
+    "layout_def": {
+      "type": "object",
+      "description": "Screen layout \u2014 either direct type or adaptive",
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "adaptive": {
+          "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/layout_adaptive"
+        },
+        "safe_area": {
+          "type": "boolean"
+        },
+        "padding": {
+          "type": "string"
+        },
+        "sections": {
+          "type": "array",
+          "items": {
+            "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/section_item"
+          }
+        },
+        "on_submit": {
+          "$ref": "https://openuispec.org/schema/defs/action.schema.json"
+        }
+      },
+      "additionalProperties": true
+    },
+    "layout_adaptive": {
+      "type": "object",
+      "description": "Adaptive layout configuration per size class",
+      "properties": {
+        "compact": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "regular": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "expanded": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "section_item": {
+      "description": "A section item \u2014 either a contract instance or a section group with children",
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "contract": {
+          "type": "string"
+        },
+        "variant": {
+          "type": "string"
+        },
+        "input_type": {
+          "type": "string"
+        },
+        "size": {
+          "type": "string"
+        },
+        "interactive": {
+          "type": "boolean"
+        },
+        "full_width": {
+          "type": "boolean"
+        },
+        "props": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "action": {
+          "$ref": "https://openuispec.org/schema/defs/action.schema.json"
+        },
+        "tokens_override": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "adaptive": {
+          "$ref": "https://openuispec.org/schema/defs/adaptive.schema.json"
+        },
+        "condition": {
+          "type": "string"
+        },
+        "position": {
+          "type": "string"
+        },
+        "data_binding": {
+          "type": "string"
+        },
+        "state_binding": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "form_id": {
+          "type": "string"
+        },
+        "t_params": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "behavior": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "validate": {
+          "$ref": "https://openuispec.org/schema/defs/validation.schema.json#/$defs/validation_rules"
+        },
+        "required_when": {
+          "type": "string",
+          "description": "Condition expression — field becomes required when true"
+        },
+        "enabled_when": {
+          "type": "string",
+          "description": "Condition expression — field is enabled (editable) when true"
+        },
+        "validate_trigger": {
+          "$ref": "https://openuispec.org/schema/defs/validation.schema.json#/$defs/validate_trigger"
+        },
+        "layout": {
+          "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/inline_layout"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/section_item"
+          }
+        },
+        "padding": {
+          "type": "string"
+        },
+        "padding_h": {
+          "type": "string"
+        },
+        "padding_v": {
+          "type": "string"
+        },
+        "margin_top": {
+          "type": "string"
+        },
+        "max_width": {
+          "type": "integer"
+        }
+      },
+      "additionalProperties": true
+    },
+    "inline_layout": {
+      "type": "object",
+      "description": "Inline layout specification for section groups",
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "adaptive": {
+          "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/layout_adaptive"
+        },
+        "spacing": {
+          "type": "string"
+        },
+        "align": {
+          "type": "string"
+        },
+        "justify": {
+          "type": "string"
+        },
+        "wrap": {
+          "type": "boolean"
+        },
+        "columns": {
+          "type": [
+            "integer",
+            "object"
+          ]
+        },
+        "gap": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "surface_def": {
+      "type": "object",
+      "description": "A named surface (sheet, modal, panel)",
+      "properties": {
+        "contract": {
+          "const": "surface"
+        },
+        "variant": {
+          "type": "string"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string"
+            },
+            "size": {
+              "type": "string"
+            },
+            "content": {
+              "type": "array",
+              "items": {
+                "$ref": "https://openuispec.org/schema/screen.schema.json#/$defs/section_item"
+              }
+            }
+          },
+          "additionalProperties": true
+        },
+        "adaptive": {
+          "$ref": "https://openuispec.org/schema/defs/adaptive.schema.json"
+        }
+      },
+      "required": [
+        "contract",
+        "props"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

package/schema/tokens/color.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/tokens/color.schema.json",
+  "title": "OpenUISpec Color Tokens",
+  "description": "Color token definitions: brand, surface, text, semantic, border, and custom groups",
+  "type": "object",
+  "required": [
+    "color"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "color": {
+      "type": "object",
+      "properties": {
+        "brand": {
+          "type": "object",
+          "description": "Brand identity colors",
+          "additionalProperties": {
+            "$ref": "https://openuispec.org/schema/tokens/color.schema.json#/$defs/color_entry"
+          }
+        },
+        "surface": {
+          "type": "object",
+          "description": "Background/surface colors",
+          "additionalProperties": {
+            "$ref": "https://openuispec.org/schema/tokens/color.schema.json#/$defs/color_entry"
+          }
+        },
+        "text": {
+          "type": "object",
+          "description": "Text and foreground colors",
+          "additionalProperties": {
+            "$ref": "https://openuispec.org/schema/tokens/color.schema.json#/$defs/color_entry"
+          }
+        },
+        "semantic": {
+          "type": "object",
+          "description": "Semantic status colors (success, warning, danger, info)",
+          "additionalProperties": {
+            "$ref": "https://openuispec.org/schema/tokens/color.schema.json#/$defs/color_entry"
+          }
+        },
+        "border": {
+          "type": "object",
+          "description": "Border colors",
+          "additionalProperties": {
+            "$ref": "https://openuispec.org/schema/tokens/color.schema.json#/$defs/border_color_entry"
+          }
+        }
+      },
+      "additionalProperties": {
+        "type": "object",
+        "description": "Custom color group",
+        "additionalProperties": {
+          "$ref": "https://openuispec.org/schema/tokens/color.schema.json#/$defs/color_entry"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "color_entry": {
+      "type": "object",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "reference": {
+          "type": "string"
+        },
+        "range": {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/hsl_range"
+        },
+        "on_color": {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/on_color"
+        },
+        "contrast_min": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "reference"
+      ],
+      "additionalProperties": false
+    },
+    "border_color_entry": {
+      "type": "object",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "reference": {
+          "type": "string"
+        },
+        "opacity": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "reference"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

package/schema/tokens/elevation.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/tokens/elevation.schema.json",
+  "title": "OpenUISpec Elevation Tokens",
+  "description": "Elevation/shadow definitions with per-platform values",
+  "type": "object",
+  "required": [
+    "elevation"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "elevation": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "https://openuispec.org/schema/tokens/elevation.schema.json#/$defs/elevation_entry"
+      }
+    }
+  },
+  "$defs": {
+    "elevation_entry": {
+      "type": "object",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string"
+        },
+        "platform": {
+          "type": "object",
+          "properties": {
+            "ios": {
+              "type": "object",
+              "properties": {
+                "shadow": {
+                  "type": "object",
+                  "properties": {
+                    "color": {
+                      "type": "string"
+                    },
+                    "opacity": {
+                      "type": "number"
+                    },
+                    "radius": {
+                      "type": "number"
+                    },
+                    "x": {
+                      "type": "number"
+                    },
+                    "y": {
+                      "type": "number"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            },
+            "android": {
+              "type": "object",
+              "properties": {
+                "elevation": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            },
+            "web": {
+              "type": "object",
+              "properties": {
+                "box_shadow": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/tokens/icons.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/tokens/icons.schema.json",
+  "title": "OpenUISpec Icon Tokens",
+  "description": "Semantic icon registry with platform mappings, sizes, and variant conventions",
+  "type": "object",
+  "required": [
+    "icons"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "icons": {
+      "type": "object",
+      "properties": {
+        "sizes": {
+          "type": "object",
+          "description": "Named sizing scale for icons",
+          "additionalProperties": {
+            "$ref": "#/$defs/size_entry"
+          }
+        },
+        "variants": {
+          "$ref": "#/$defs/variant_config"
+        },
+        "fallback": {
+          "$ref": "#/$defs/fallback_config"
+        },
+        "registry": {
+          "type": "object",
+          "description": "Canonical icon set grouped by category",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/$defs/icon_entry"
+            }
+          }
+        },
+        "custom": {
+          "type": "object",
+          "description": "App-specific icon entries following the same shape as registry categories",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/$defs/icon_entry"
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "size_entry": {
+      "type": "object",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "value": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "semantic",
+        "value"
+      ],
+      "additionalProperties": false
+    },
+    "variant_config": {
+      "type": "object",
+      "description": "Icon variant conventions",
+      "properties": {
+        "default": {
+          "type": "string",
+          "description": "Default variant style when no suffix is present"
+        },
+        "suffixes": {
+          "type": "object",
+          "description": "Suffix conventions for icon style variants",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "fallback_config": {
+      "type": "object",
+      "description": "Strategy for icons not found in the registry",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": [
+            "name_passthrough",
+            "error"
+          ],
+          "description": "name_passthrough: pass unknown icon names directly to the native API. error: fail if icon is not in the registry."
+        },
+        "missing_icon": {
+          "type": "string",
+          "description": "Fallback icon to display when an icon cannot be resolved"
+        }
+      },
+      "required": [
+        "strategy"
+      ],
+      "additionalProperties": false
+    },
+    "icon_entry": {
+      "type": "object",
+      "properties": {
+        "semantic": {
+          "type": "string",
+          "description": "Human-readable description of what this icon represents"
+        },
+        "variants": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Available variant suffixes for this icon (e.g. ['fill'])"
+        },
+        "platform": {
+          "type": "object",
+          "properties": {
+            "ios": {
+              "type": "string",
+              "description": "SF Symbols name (dot-notation)"
+            },
+            "android": {
+              "type": "string",
+              "description": "Material Icons name"
+            },
+            "web": {
+              "type": "string",
+              "description": "Web icon library name (e.g. Lucide, Heroicons)"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "semantic",
+        "platform"
+      ],
+      "additionalProperties": false
+    }
+  }
+}