# OpenUISpec

> OpenUISpec is a semantic UI specification format for AI-native, platform-native app development. It replaces cross-platform frameworks by sharing intent (YAML spec) instead of runtime code — AI generates native SwiftUI, Jetpack Compose, and React from the same source of truth.

## Core Docs

- [Full Specification + Schemas](https://openuispec.rsteam.uz/llms-full.txt): Complete OpenUISpec v0.1 specification with all JSON Schema definitions in a single file
- [GitHub Repository](https://github.com/rsktash/openuispec): Source code, CLI tool, and examples
- [Specification Document](https://github.com/rsktash/openuispec/blob/main/spec/openuispec-v0.1.md): Full spec in markdown

## File formats at a glance

Every file type has a required root key and a JSON Schema that defines its structure. Read the schema before creating files — do not guess.

### Root manifest (`openuispec.yaml`)
```yaml
spec_version: "0.1"
project:
  name: "MyApp"
includes:
  tokens: "./tokens/"
  screens: "./screens/"
  flows: "./flows/"
```

### Screen (`screens/<name>.yaml`) — root key is the screen id
```yaml
home:
  semantic: "Main task list"
  data:
    tasks: { source: "api.tasks.list" }
  state:
    filter: { type: enum, default: "all", options: [all, active, done] }
  sections:
    - id: task_list
      contract: collection
      # ...
```

### Flow (`flows/<name>.yaml`) — root key is the flow id
```yaml
create_task:
  semantic: "Task creation flow"
  entry: "task_form"
  screens:
    task_form:
      screen_inline:
        semantic: "Task form"
        sections: [...]
```

### Token file (`tokens/<type>.yaml`) — root key matches the token type
```yaml
# tokens/color.yaml
color:
  brand:
    primary:
      semantic: "Main brand color"
      reference: "#5B4FE8"
      range: { hue: [240, 250], saturation: [65, 80], lightness: [50, 60] }

# tokens/spacing.yaml
spacing:
  base_unit: 4
  scale:
    sm: 8
    md: { base: 16, range: [12, 16] }
```

### Platform override (`platform/<target>.yaml`)
```yaml
platform:
  target: ios
  overrides: [...]
```

## Schemas

Each schema validates a specific file type. Read the schema before creating or editing the corresponding file.

- [Root Manifest Schema](https://openuispec.rsteam.uz/schema/openuispec.schema.json): validates `openuispec.yaml`
- [Screen Schema](https://openuispec.rsteam.uz/schema/screen.schema.json): validates `screens/*.yaml`
- [Flow Schema](https://openuispec.rsteam.uz/schema/flow.schema.json): validates `flows/*.yaml`
- [Platform Schema](https://openuispec.rsteam.uz/schema/platform.schema.json): validates `platform/*.yaml`
- [Locale Schema](https://openuispec.rsteam.uz/schema/locale.schema.json): validates `locales/*.json`
- [Custom Contract Schema](https://openuispec.rsteam.uz/schema/custom-contract.schema.json): validates `contracts/x_*.yaml`

## Token Schemas

Every token file requires a root wrapper key matching its type (e.g. `tokens/typography.yaml` must start with `typography:`).

- [Color Schema](https://openuispec.rsteam.uz/schema/tokens/color.schema.json): `tokens/color.yaml` — root key: `color`
- [Typography Schema](https://openuispec.rsteam.uz/schema/tokens/typography.schema.json): `tokens/typography.yaml` — root key: `typography`
- [Spacing Schema](https://openuispec.rsteam.uz/schema/tokens/spacing.schema.json): `tokens/spacing.yaml` — root key: `spacing`
- [Elevation Schema](https://openuispec.rsteam.uz/schema/tokens/elevation.schema.json): `tokens/elevation.yaml` — root key: `elevation`
- [Motion Schema](https://openuispec.rsteam.uz/schema/tokens/motion.schema.json): `tokens/motion.yaml` — root key: `motion`
- [Layout Schema](https://openuispec.rsteam.uz/schema/tokens/layout.schema.json): `tokens/layout.yaml` — root key: `layout`
- [Themes Schema](https://openuispec.rsteam.uz/schema/tokens/themes.schema.json): `tokens/themes.yaml` — root key: `themes`
- [Icons Schema](https://openuispec.rsteam.uz/schema/tokens/icons.schema.json): `tokens/icons.yaml` — root key: `icons`

## Shared Definition Schemas

- [Action Schema](https://openuispec.rsteam.uz/schema/defs/action.schema.json): 13 action types as discriminated union
- [Data Binding Schema](https://openuispec.rsteam.uz/schema/defs/data-binding.schema.json): Data sources, state, params, format expressions
- [Common Schema](https://openuispec.rsteam.uz/schema/defs/common.schema.json): Shared types (icons, badges, conditions)
- [Adaptive Schema](https://openuispec.rsteam.uz/schema/defs/adaptive.schema.json): Adaptive override pattern for size classes
- [Validation Schema](https://openuispec.rsteam.uz/schema/defs/validation.schema.json): Form validation rule definitions

## Examples

If the package is installed locally, all examples are in `node_modules/openuispec/examples/` — read from disk instead of fetching from GitHub.

- [TaskFlow Example App](https://github.com/rsktash/openuispec/tree/main/examples/taskflow): Complete example spec covering all 7 contract families, tokens, screens, flows, platform overrides, and localization

## Optional

- [npm Package](https://www.npmjs.com/package/openuispec): Install via `npm install -g openuispec` for CLI tools (init, validate, drift)