UI Spec

This page describes the structure of a UI Spec document. For methodology and workflows, see How It Works. For advanced techniques, see Patterns & Practices.

Public format file: ui-spec-format-0-0-3.yaml

Document Root

A UI Spec document is a YAML file with the following top-level fields.

Metadata

The metadata object describes the application and its visual style.

Templates

Templates define reusable page layouts with named regions. Define templates when multiple screens share the same structure (e.g., header + sidebar + content).

Each template is defined under templates with a unique ID (snake_case).

Region

Navigation

The navigation object defines links between screens.

Navigation Item

Screen Groups

Optional grouping for specs with many screens. Recommended when a spec has more than 15 screens.

Each group is an object in the screen_groups array.

Screens not assigned to any group appear in an "Other" section.

Screens

Screens are defined under the screens object. Each key is a unique screen_id (snake_case).

Blocks

Blocks are the core building units of a screen. Each block describes a logical piece of the interface through its purpose.

Purpose

The purpose field is the most important field in the format. It describes intent, not implementation — what the block should show, what data it displays, and how it behaves. This includes interactions (click opens a modal, hover reveals actions), state variations (empty state, loading state, error state), and relationships between blocks (selecting an item in one block updates another). AI agents both generate and interpret these descriptions semantically.

Always use double quotes for purpose values in YAML.

# Good — describes intent and appearance:
purpose: "Four metric cards showing total, completed, in progress, and overdue tasks"

# Good — describes behavior:
purpose: "Button 'New Task', onClick opens modal_create_task"

# Good — describes state variations:
purpose: "Task list with status filters. Empty state: 'No tasks yet' with create button"

# Too implementation-specific:
purpose: "div with display:grid, grid-template-columns: repeat(4, 1fr), gap: 16px"

For detailed guidance on writing purposes — progressive precision levels, behavioral patterns, and nested structure strategies — see Patterns & Practices.

Nesting

Blocks can be nested to any depth. Child blocks inherit the visible property from their parent.

blocks:
  - id: user_profile
    purpose: "User profile card"
    blocks:
      - id: avatar
        purpose: "Circular user photo, clickable"
      - id: info
        purpose: "Name and bio"
        blocks:
          - id: name
            purpose: "User name, bold"
          - id: bio
            purpose: "Short bio, max 3 lines"

Grid Layout

Blocks use a 12-column grid system (similar to Bootstrap). The columns field defines how many columns a block occupies.

When the sum of columns in a row exceeds 12, blocks wrap to the next row. On mobile, blocks typically become full-width unless adaptive columns are specified.

Detailing Levels

The format supports progressive precision. You choose how much detail to include based on your needs.

Exploration (L0). Screens with titles and purposes. No blocks, no theme. Enough to discover what screens the app needs.

screens:
  dashboard:
    title: Dashboard
    purpose: "Overview of user tasks and productivity"

Structure (L1). Add blocks with purposes and basic columns. Optionally add theme.

screens:
  dashboard:
    title: Dashboard
    purpose: "Overview of user tasks and productivity"
    blocks:
      - id: stats
        columns: 12
        purpose: "Key metrics: total notes, active drafts, archived"

Detailed (L2). Add palette, templates, navigation, detailed purposes, nested blocks.

Full Control (L3). Add exact sizes, spacing, animations, transitions in purpose text. Implementation-ready.

Different screens in the same spec can use different detail levels. For examples and guidance, see Patterns & Practices.

Common Patterns

Typical screen structures used in specs.

Overlay Patterns

Overlays are described as blocks with specific purpose patterns.

Validation Rules

Key rules that a valid UI Spec must follow.

Structure: Each template must have at least one region and exactly one with type: content. Block IDs must be unique within their screen. Region IDs must be unique within their template.

References: default_template, screen.template, navigation.items[].target, and screen_groups[].screens[] must reference existing IDs. Missing references are errors.

Layout: Column values must be 1–12. Sum exceeding 12 wraps to a new row.

Responsive: template can be a string or an object with default (required) and optional mobile, tablet, desktop. Same for columns. The visible field accepts a string, array, or object with show/hide arrays.

Formatting: Always use double quotes for string values containing special characters (: { } [ ] , & * # ? | - < > = ! % @ \).