OpenUISpec

A single source of truth design language for AI-native, platform-native app development.

OpenUISpec is a semantic UI specification format that replaces cross-platform frameworks with a declarative design language. Instead of sharing runtime code across platforms, you share the spec — and AI generates native SwiftUI, Jetpack Compose, and React code from it.

Why

Cross-platform frameworks (Flutter, React Native, KMP/CMP) solve code duplication by sharing a runtime. OpenUISpec solves it by sharing intent:

Approach	Shares	Runs
Cross-platform framework	Runtime code	Abstraction layer
OpenUISpec	Semantic spec	Native per platform

The result: each platform feels native, but every app stays semantically consistent because it's generated from the same source of truth.

How it works

Workflows

Quick start

npm install -g openuispec
cd your-project
openuispec init

This scaffolds a spec directory, starter tokens, and configures the MCP server for your AI coding agent (Claude Code, VS Code/Copilot, Codex, Gemini CLI).

Key concepts

• Tokens — design values (color, typography, spacing, elevation, motion) with semantic names and constrained ranges
• Contracts — 7 reusable UI component families defined by role, props, interaction states, accessibility, and must_avoid anti-patterns for AI generators
• Components — reusable compositions of contracts with named slots, states, and variants
• Screens — compositions of contracts and components with data bindings, adaptive layout, and conditional rendering
• Flows — multi-screen navigation journeys, intent-based and platform-agnostic
• Actions — 13 typed action types with composition, error handling, and optimistic updates
• Data binding — reactive state, format expressions, caching, and loading/error/empty states
• Adaptive layout — size classes (compact/regular/expanded) with per-section overrides
• Platform adaptation — per-target overrides for iOS, Android, and Web behaviors
• Design intent — design section captures brand personality, complexity level (restrained/balanced/elaborate), quality tier (mvp/production/flagship), and audience — generators match visual elaborateness and polish level accordingly
• Anti-patterns — must_avoid in contracts and universal_anti_patterns in the manifest (9 domains: typography, color, spacing, motion, elevation, layout, visual, interaction, accessibility) steer AI away from generic design mistakes. Platform-scoped with [web]/[ios]/[android] tags
• Design quality audit — check --audit scores the spec against 18 heuristic checks across all token and contract domains, producing a numeric score with CI-gatable thresholds

The 7 contract families

Contract	Role	Maps to
action_trigger	Initiates actions	Button, FAB, link
data_display	Shows read-only info	Card, list item, stat
input_field	Captures user input	TextField, toggle, picker
nav_container	Persistent navigation	Tab bar, sidebar, drawer
feedback	System status messages	Toast, dialog, banner
surface	Contains other components	Sheet, modal, popover
collection	Repeating data sets	List, grid, table

AI integration (MCP)

OpenUISpec includes an MCP server that AI assistants call automatically during UI work — no manual prompting needed.

openuispec init → configures MCP for your agent → AI calls tools automatically

When you ask your AI to "add a settings page" or "update the home feed," the MCP server provides spec context before generation, feeds authoritative spec contents during generation, validates spec integrity after edits, and returns a spec-derived checklist — including must_avoid anti-patterns and design quality score — for the AI to review the generated code against.

16 tools are available as both MCP tools and CLI commands — see the full reference.

Using without MCP? You can provide spec context to any AI manually:

Generate a native iOS app from this OpenUISpec. Follow all contract UI states, apply token ranges for iOS, and implement navigation flows as defined.

Examples

Example	Targets	What it demonstrates
TaskFlow	iOS, Android, Web	Compact reference covering all 7 contract families
Todo Orbit	iOS, Android, Web	Bilingual task app with localization, custom contracts
Social App	Android, Web	Trilingual social app with feeds, messaging, profiles

Screenshots of the generated apps are in the artifacts directory.

Documentation

Doc	What's in it
CLI & MCP Tools	All CLI commands, MCP tools, screenshot params, target workflow
File Formats & Schemas	File types, JSON schemas, output directories, spec sections
Full Specification	Complete v0.2 spec (16 sections)
llms-full.txt	Spec + all schemas in one file (for AI consumption)

Status

v0.2 — Draft. The spec covers all foundational layers — including component composition — with three example apps demonstrating generation across iOS, Android, and Web.

Roadmap

• Token system, 7 contract families, adaptive layout, action system
• Data binding, i18n, form validation, custom contract extensions
• JSON Schema validation, CLI tool, MCP server
• Drift detection, visual verification (screenshots, preview)
• Example apps: TaskFlow, Todo Orbit, Social App
• More example apps (e-commerce, dashboard)

Contributing

OpenUISpec is in early development. If you're interested in contributing — especially around AI code generation, platform-specific expertise, or additional example apps — open an issue to start the conversation.

License

MIT