aub-workspace 0.3.0

package/vendor/aub/schema/implementation-report.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aub.dev/schema/implementation-report/1.0.0",
+  "title": "AUB Implementation Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "format_version",
+    "blueprint",
+    "implementation",
+    "node_mappings",
+    "acceptance_results",
+    "unresolved"
+  ],
+  "properties": {
+    "format": { "const": "aub-implementation-report" },
+    "format_version": { "const": "1.0.0" },
+    "blueprint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["screen_id", "version"],
+      "properties": {
+        "screen_id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "implementation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["framework", "route", "files"],
+      "properties": {
+        "framework": { "type": "string" },
+        "route": { "type": "string" },
+        "files": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      }
+    },
+    "node_mappings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/nodeMapping" }
+    },
+    "acceptance_results": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/acceptanceResult" }
+    },
+    "unresolved": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "$defs": {
+    "nodeMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node_id", "status", "component"],
+      "properties": {
+        "node_id": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["mapped", "unmapped"] },
+        "component": { "type": "string" },
+        "file": { "type": "string" },
+        "selector": { "type": "string" },
+        "notes": { "type": "string" }
+      }
+    },
+    "acceptanceResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["acceptance_id", "status", "evidence"],
+      "properties": {
+        "acceptance_id": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["pass", "fail", "needs-review"] },
+        "evidence": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/evidence" }
+        },
+        "notes": { "type": "string" }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "reference"],
+      "properties": {
+        "type": { "enum": ["screenshot", "file", "dom", "command", "interaction", "note"] },
+        "reference": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/vendor/aub/schema/project-types.ts

@@ -0,0 +1,72 @@
+/**
+ * UI Blueprint Project TypeScript types.
+ *
+ * These types are the TypeScript surface of `ui-project.schema.json`.
+ * They are hand-maintained to match the schema field-for-field.
+ *
+ * Synchronization rule: when the JSON Schema changes, update these types in
+ * the same commit. A validation test in `tests/project.test.mjs` round-trips
+ * the example project through both surfaces to catch drift.
+ *
+ * Source of truth: `schema/ui-project.schema.json`
+ */
+
+import type { SemVer } from './types';
+
+/** Project schema version track. Independent from the Blueprint schema version. */
+export type ProjectVersion = '0.1.0';
+
+/** What causes a navigation between screens. */
+export type NavigationTrigger =
+  | 'click'
+  | 'submit'
+  | 'change'
+  | 'load'
+  | 'system'
+  | 'gesture';
+
+/** Reference to a member single-screen Blueprint file. */
+export interface ProjectScreenRef {
+  /** Screen identifier. MUST match the referenced Blueprint's screen.id. */
+  id: string;
+  /** Optional display name. Defaults to the referenced Blueprint's screen.name. */
+  name?: string;
+  /** Relative path (from the project file) to a .ui.json or .ui.yaml Blueprint. */
+  path: string;
+}
+
+/** Directed navigation edge between two screens. */
+export interface NavigationEdge {
+  /** Source screen id (must be a declared screen). */
+  from: string;
+  /** Destination screen id (must be a declared screen). */
+  to: string;
+  /** What causes the navigation. */
+  trigger?: NavigationTrigger;
+  /** Optional id of the source-screen interaction that triggers this navigation. */
+  interaction_id?: string;
+  /** Optional human-readable label for the edge. */
+  label?: string;
+}
+
+/** Top-level multi-screen project document. */
+export interface Project {
+  /** Semantic version of the project schema this document conforms to. */
+  version: ProjectVersion & SemVer;
+  /** Unique project identifier. */
+  id: string;
+  /** Human-readable project name. */
+  name: string;
+  /** Optional summary of the product or flow. */
+  description?: string;
+  /** Member screens. At least one required. */
+  screens: ProjectScreenRef[];
+  /** Screen id where the flow starts. MUST match a declared screen. */
+  entry_screen: string;
+  /** Directed navigation edges between screens. */
+  navigation?: NavigationEdge[];
+  /** Optional project-level shared design tokens; member screens may override. */
+  design_system?: Record<string, unknown>;
+  /** Optional metadata about how this project document was produced. */
+  provenance?: Record<string, unknown>;
+}

package/vendor/aub/schema/registry/components.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "../ui-blueprint.schema.json",
+  "version": "0.3.0",
+  "description": "Canonical registry of UI Blueprint component types. This file is the source of truth — the JSON Schema enum in ui-blueprint.schema.json must stay in sync. The editor (Phase 2) reads this file to render the component palette.",
+  "categories": [
+    {
+      "id": "layout",
+      "name": "Layout",
+      "description": "Containers and structural primitives. Arrange children in flex/grid. Never hold business content directly.",
+      "types": [
+        { "name": "app_shell", "displayName": "App Shell", "isContainer": true, "description": "Top-level layout container." },
+        { "name": "page", "displayName": "Page", "isContainer": true, "description": "A full-screen scrollable content area." },
+        { "name": "section", "displayName": "Section", "isContainer": true, "description": "Logical grouping of related nodes." },
+        { "name": "header", "displayName": "Header", "isContainer": true, "description": "Top region of a screen, usually with title and actions." },
+        { "name": "sidebar", "displayName": "Sidebar", "isContainer": true, "description": "Vertical navigation column." },
+        { "name": "top_bar", "displayName": "Top Bar", "isContainer": true, "description": "Horizontal header with logo, search, and user actions." },
+        { "name": "bottom_nav", "displayName": "Bottom Nav", "isContainer": true, "description": "Mobile-first horizontal nav at screen bottom." },
+        { "name": "stack", "displayName": "Stack", "isContainer": true, "description": "Generic flex container, defaults to column." },
+        { "name": "grid", "displayName": "Grid", "isContainer": true, "description": "CSS-grid container with declared columns." },
+        { "name": "split_pane", "displayName": "Split Pane", "isContainer": true, "description": "Master/detail two-pane layout." },
+        { "name": "scroll_area", "displayName": "Scroll Area", "isContainer": true, "description": "Scrollable region with fixed dimensions." }
+      ]
+    },
+    {
+      "id": "visual",
+      "name": "Visual",
+      "description": "Common visual building blocks used to reproduce hierarchy, branding, and content density.",
+      "types": [
+        { "name": "heading", "displayName": "Heading", "isContainer": false, "description": "Semantic heading with declared typography.", "typicalContent": ["text"] },
+        { "name": "text", "displayName": "Text", "isContainer": false, "description": "Paragraph, caption, or helper text.", "typicalContent": ["text"] },
+        { "name": "card", "displayName": "Card", "isContainer": true, "description": "Framed group of related content and actions." },
+        { "name": "image", "displayName": "Image", "isContainer": false, "description": "Image with source and alternative text.", "typicalContent": ["src", "alt"] },
+        { "name": "icon", "displayName": "Icon", "isContainer": false, "description": "Named interface icon.", "typicalContent": ["icon", "label"] },
+        { "name": "avatar", "displayName": "Avatar", "isContainer": false, "description": "User or entity avatar.", "typicalContent": ["src", "alt"] },
+        { "name": "badge", "displayName": "Badge", "isContainer": false, "description": "Status or count badge.", "typicalContent": ["text", "variant"] },
+        { "name": "tag", "displayName": "Tag", "isContainer": false, "description": "Compact categorical label.", "typicalContent": ["text"] },
+        { "name": "divider", "displayName": "Divider", "isContainer": false, "description": "Visual separator between content groups." },
+        { "name": "link", "displayName": "Link", "isContainer": false, "description": "Inline navigation action.", "typicalContent": ["text", "action"] }
+      ]
+    },
+    {
+      "id": "data",
+      "name": "Data",
+      "description": "Data display primitives. Bind to data sources, render collections and aggregates.",
+      "types": [
+        { "name": "metric_card", "displayName": "Metric Card", "isContainer": false, "description": "Single KPI with label, value, and delta.", "typicalContent": ["label", "data_binding"] },
+        { "name": "data_table", "displayName": "Data Table", "isContainer": false, "description": "Tabular data with declared columns, sort, filter.", "typicalContent": ["columns", "data_binding"] },
+        { "name": "list", "displayName": "List", "isContainer": true, "description": "Vertical collection of items." },
+        { "name": "detail_panel", "displayName": "Detail Panel", "isContainer": true, "description": "Right-side drawer or modal for row/record detail." },
+        { "name": "chart_placeholder", "displayName": "Chart Placeholder", "isContainer": false, "description": "Render slot for a chart library (recharts, visx, etc.)." },
+        { "name": "timeline", "displayName": "Timeline", "isContainer": true, "description": "Chronological event list." },
+        { "name": "activity_feed", "displayName": "Activity Feed", "isContainer": true, "description": "Reverse-chronological event stream." }
+        ,{ "name": "calendar", "displayName": "Calendar", "isContainer": false, "description": "Month, week, or agenda calendar." }
+        ,{ "name": "kanban_board", "displayName": "Kanban Board", "isContainer": true, "description": "Horizontal workflow board containing columns." }
+        ,{ "name": "kanban_column", "displayName": "Kanban Column", "isContainer": true, "description": "Workflow stage containing task cards." }
+      ]
+    },
+    {
+      "id": "form",
+      "name": "Form",
+      "description": "Form containers and inputs. Every input has a label and a value-binding path.",
+      "types": [
+        { "name": "form", "displayName": "Form", "isContainer": true, "description": "Form container with declared submit action.", "typicalContent": ["action"] },
+        { "name": "field_group", "displayName": "Field Group", "isContainer": true, "description": "Visually grouped fields with shared label/legend." },
+        { "name": "text_input", "displayName": "Text Input", "isContainer": false, "description": "Single-line text input.", "typicalContent": ["label", "placeholder"] },
+        { "name": "select", "displayName": "Select", "isContainer": false, "description": "Dropdown selector.", "typicalContent": ["label", "items"] },
+        { "name": "checkbox", "displayName": "Checkbox", "isContainer": false, "description": "Boolean toggle with label.", "typicalContent": ["label"] },
+        { "name": "radio_group", "displayName": "Radio Group", "isContainer": false, "description": "Single-choice from a set of options.", "typicalContent": ["label", "items"] },
+        { "name": "toggle", "displayName": "Toggle", "isContainer": false, "description": "On/off switch with label.", "typicalContent": ["label"] },
+        { "name": "slider", "displayName": "Slider", "isContainer": false, "description": "Numeric range input.", "typicalContent": ["label"] },
+        { "name": "date_picker", "displayName": "Date Picker", "isContainer": false, "description": "Calendar-based date input.", "typicalContent": ["label"] },
+        { "name": "file_upload", "displayName": "File Upload", "isContainer": false, "description": "Drag/drop or browse file input.", "typicalContent": ["label"] }
+        ,{ "name": "textarea", "displayName": "Textarea", "isContainer": false, "description": "Multi-line text input.", "typicalContent": ["label", "placeholder"] }
+        ,{ "name": "search_input", "displayName": "Search Input", "isContainer": false, "description": "Search field with query intent.", "typicalContent": ["label", "placeholder", "action"] }
+        ,{ "name": "rich_text_editor", "displayName": "Rich Text Editor", "isContainer": true, "description": "Document editing surface with toolbar and body." }
+      ]
+    },
+    {
+      "id": "action",
+      "name": "Action",
+      "description": "Triggers and actions. Always have an action intent and a target.",
+      "types": [
+        { "name": "button", "displayName": "Button", "isContainer": false, "description": "Primary action button. Must declare action intent.", "typicalContent": ["text", "action"] },
+        { "name": "icon_button", "displayName": "Icon Button", "isContainer": false, "description": "Icon-only button. Must have an accessible label.", "typicalContent": ["label", "action"] },
+        { "name": "button_group", "displayName": "Button Group", "isContainer": true, "description": "Cluster of related buttons." },
+        { "name": "menu", "displayName": "Menu", "isContainer": true, "description": "Dropdown menu of actions.", "typicalContent": ["label", "items"] },
+        { "name": "toolbar", "displayName": "Toolbar", "isContainer": true, "description": "Horizontal action bar." },
+        { "name": "command_palette", "displayName": "Command Palette", "isContainer": true, "description": "Cmd-K style searchable action list." }
+      ]
+    },
+    {
+      "id": "feedback",
+      "name": "Feedback",
+      "description": "User feedback surfaces — modals, toasts, alerts, and explicit state placeholders.",
+      "types": [
+        { "name": "modal", "displayName": "Modal", "isContainer": true, "description": "Centered blocking dialog." },
+        { "name": "drawer", "displayName": "Drawer", "isContainer": true, "description": "Side-sliding panel." },
+        { "name": "toast", "displayName": "Toast", "isContainer": false, "description": "Transient feedback message." },
+        { "name": "alert", "displayName": "Alert", "isContainer": false, "description": "Inline message (info/warn/error)." },
+        { "name": "empty_state", "displayName": "Empty State", "isContainer": false, "description": "Placeholder for empty collections. Must be wired via content.empty_state.", "typicalContent": ["text", "action"] },
+        { "name": "loading_state", "displayName": "Loading State", "isContainer": false, "description": "Placeholder for in-flight data." },
+        { "name": "error_state", "displayName": "Error State", "isContainer": false, "description": "Placeholder for fetch failure." }
+      ]
+    },
+    {
+      "id": "navigation",
+      "name": "Navigation",
+      "description": "Navigation primitives. Always link to a target screen or anchor.",
+      "types": [
+        { "name": "tabs", "displayName": "Tabs", "isContainer": true, "description": "Tabbed view selector." },
+        { "name": "breadcrumb", "displayName": "Breadcrumb", "isContainer": false, "description": "Hierarchical location indicator." },
+        { "name": "pagination", "displayName": "Pagination", "isContainer": false, "description": "Page navigation for collections." },
+        { "name": "stepper", "displayName": "Stepper", "isContainer": true, "description": "Multi-step flow indicator." },
+        { "name": "nav_item", "displayName": "Nav Item", "isContainer": false, "description": "Single link in a sidebar/top_nav. Must declare action.", "typicalContent": ["label", "action"] }
+      ]
+    }
+  ]
+}

package/vendor/aub/schema/types.js

@@ -0,0 +1,13 @@
+/**
+ * UI Blueprint TypeScript types.
+ *
+ * These types are the TypeScript surface of `ui-blueprint.schema.json`.
+ * They are hand-maintained to match the schema field-for-field.
+ *
+ * Synchronization rule: when the JSON Schema changes, update these types in
+ * the same commit. A validation test in `tests/types.test.ts` round-trips
+ * `examples/dashboard.ui.json` through both surfaces to catch drift.
+ *
+ * Source of truth: `schema/ui-blueprint.schema.json`
+ */
+export {};

package/vendor/aub/schema/types.ts

@@ -0,0 +1,348 @@
+/**
+ * UI Blueprint TypeScript types.
+ *
+ * These types are the TypeScript surface of `ui-blueprint.schema.json`.
+ * They are hand-maintained to match the schema field-for-field.
+ *
+ * Synchronization rule: when the JSON Schema changes, update these types in
+ * the same commit. A validation test in `tests/types.test.ts` round-trips
+ * `examples/dashboard.ui.json` through both surfaces to catch drift.
+ *
+ * Source of truth: `schema/ui-blueprint.schema.json`
+ */
+
+export type SemVer = `${number}.${number}.${number}`;
+
+/** Top-level document. */
+export interface Blueprint {
+  /** Semantic version of the schema this document conforms to. */
+  version: SemVer;
+  /** Screen metadata. */
+  screen: Screen;
+  /** At least one viewport. */
+  viewports: Viewport[];
+  /** Tree of semantic UI nodes. The first node MUST be the root. */
+  nodes: UINode[];
+  /** User-driven interactions. */
+  interactions: Interaction[];
+  /** Per-viewport rules that override or transform node layout. */
+  responsive: Responsive[];
+  /** Verifiable acceptance items. >=5 per screen. */
+  acceptance: Acceptance[];
+  /** Shared visual vocabulary used by nodes. */
+  design_system?: DesignSystem;
+  /** Optional origin metadata for imported Blueprints. */
+  provenance?: Provenance;
+}
+
+export interface Screen {
+  id: string;
+  name: string;
+  type: ScreenType;
+  platform: Platform;
+  primary_user_goal: string;
+  notes?: string;
+}
+
+export type ScreenType =
+  | 'dashboard'
+  | 'form'
+  | 'landing'
+  | 'settings'
+  | 'admin_table'
+  | 'detail'
+  | 'auth'
+  | 'error'
+  | 'empty'
+  | 'workspace'
+  | 'communication'
+  | 'content'
+  | 'commerce'
+  | 'calendar'
+  | 'files'
+  | 'onboarding';
+
+export type Platform = 'web' | 'mobile-web' | 'ios' | 'android' | 'desktop';
+
+export interface Viewport {
+  id: 'desktop' | 'tablet' | 'mobile' | 'wide';
+  width: number;
+  height: number;
+}
+
+// <generated:component-types>
+/** Semantic component type — agents read this to know WHAT a node is. */
+export type ComponentType =
+  | 'app_shell' | 'page' | 'section' | 'header' | 'sidebar' | 'top_bar' | 'bottom_nav' | 'stack' | 'grid' | 'split_pane' | 'scroll_area'
+  | 'heading' | 'text' | 'card' | 'image' | 'icon' | 'avatar' | 'badge' | 'tag' | 'divider' | 'link'
+  | 'metric_card' | 'data_table' | 'list' | 'detail_panel' | 'chart_placeholder' | 'timeline' | 'activity_feed' | 'calendar' | 'kanban_board' | 'kanban_column'
+  | 'form' | 'field_group' | 'text_input' | 'select' | 'checkbox' | 'radio_group' | 'toggle' | 'slider' | 'date_picker' | 'file_upload' | 'textarea' | 'search_input' | 'rich_text_editor'
+  | 'button' | 'icon_button' | 'button_group' | 'menu' | 'toolbar' | 'command_palette'
+  | 'modal' | 'drawer' | 'toast' | 'alert' | 'empty_state' | 'loading_state' | 'error_state'
+  | 'tabs' | 'breadcrumb' | 'pagination' | 'stepper' | 'nav_item';
+
+export type ContainerComponentType = Extract<
+  ComponentType,
+    | 'app_shell' | 'page' | 'section' | 'header' | 'sidebar' | 'top_bar' | 'bottom_nav' | 'stack' | 'grid' | 'split_pane' | 'scroll_area'
+    | 'card'
+    | 'list' | 'detail_panel' | 'timeline' | 'activity_feed' | 'kanban_board' | 'kanban_column'
+    | 'form' | 'field_group' | 'rich_text_editor'
+    | 'button_group' | 'menu' | 'toolbar' | 'command_palette'
+    | 'modal' | 'drawer'
+    | 'tabs' | 'stepper'
+>;
+
+export type LeafComponentType = Exclude<ComponentType, ContainerComponentType>;
+// </generated:component-types>
+
+/**
+ * A fully resolved component type: a core type or a namespaced project
+ * extension type (e.g. `acme:data_card`) declared in aub.registry.json.
+ */
+export type ResolvedComponentType = ComponentType | `${string}:${string}`;
+
+export type NodeState =
+  | 'default' | 'hover' | 'focus' | 'active' | 'disabled'
+  | 'loading' | 'empty' | 'error' | 'selected';
+
+export interface UINode {
+  id: string;
+  type: ComponentType;
+  name: string;
+  /** Agent-facing role/intent. WHY this node exists. */
+  role: string;
+  parent_id: string | null;
+  children?: string[];
+  layout?: Layout;
+  /** Exact geometry per viewport. Used when the parent layout mode is freeform. */
+  placements?: Partial<Record<ViewportId, Placement>>;
+  content?: Content;
+  style?: Style;
+  states?: NodeState[];
+  constraints?: NodeConstraints;
+  source?: SourceReference;
+  bindings?: Bindings;
+  validation?: NodeValidation;
+  initial_state?: InitialState;
+}
+
+export interface Provenance {
+  source_kind: 'native' | 'angular-component' | 'html' | 'figma' | 'penpot' | 'image' | 'other';
+  framework?: string;
+  importer_version: string;
+  entry_file?: string;
+  source_files: string[];
+}
+
+export interface SourceReference {
+  file: string;
+  line?: number;
+  column?: number;
+  selector?: string;
+}
+
+export interface Bindings {
+  value?: string;
+  options?: string;
+  visibility?: string;
+  enabled?: string;
+  repeat?: string;
+  selected?: string;
+}
+
+export interface NodeValidation {
+  required?: boolean;
+  pattern?: string;
+  min_length?: number;
+  max_length?: number;
+  min?: number;
+  max?: number;
+}
+
+export interface InitialState {
+  visibility?: 'visible' | 'hidden';
+  expanded?: boolean;
+  selected?: boolean;
+}
+
+export interface NodeConstraints {
+  min_width?: number;
+  max_width?: number;
+  min_height?: number;
+  max_height?: number;
+  /** Minimum interactive area in pixels (Apple HIG 44, Material 48). */
+  touch_target_min?: number;
+}
+
+export interface Layout {
+  mode?: 'auto' | 'freeform';
+  display?: 'flex' | 'grid' | 'block' | 'inline' | 'none';
+  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+  wrap?: boolean;
+  grid?: GridConfig;
+  align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+  justify?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+  gap?: Spacing;
+  padding?: PaddingBox;
+  width?: Size;
+  height?: Size;
+  min_width?: Size;
+  max_width?: Size;
+}
+
+export type ViewportId = Viewport['id'];
+
+export interface Placement {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  z_index?: number;
+  order?: number;
+  grow?: number;
+  basis?: number;
+  grid_column?: number;
+  grid_row?: number;
+  column_span?: number;
+  row_span?: number;
+}
+
+export interface GridConfig {
+  columns?: number;
+  rows?: number;
+  template?: string;
+}
+
+export interface Spacing {
+  x?: number;
+  y?: number;
+}
+
+export interface PaddingBox {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+export interface Size {
+  value: number;
+  unit: 'px' | '%' | 'rem' | 'vw' | 'vh';
+}
+
+export interface Content {
+  text?: string;
+  placeholder?: string;
+  /** Symbolic reference to a data source, e.g. 'metrics.revenue.current'. */
+  data_binding?: string;
+  columns?: TableColumn[];
+  items?: ListItem[];
+  /** Symbolic action intent, e.g. 'submit', 'navigate:/settings'. */
+  action?: string;
+  /** Accessible label for form inputs and icon buttons. */
+  label?: string;
+  empty_state?: string;
+  loading_state?: string;
+  error_state?: string;
+  src?: string;
+  alt?: string;
+  icon?: string;
+  value?: string;
+  helper_text?: string;
+  variant?: string;
+}
+
+export interface TableColumn {
+  id: string;
+  header: string;
+  data_binding?: string;
+  sortable?: boolean;
+  filterable?: boolean;
+  cell_kind?: 'text' | 'number' | 'date' | 'link' | 'icon' | 'action' | 'status' | 'checkbox';
+  icon?: string;
+  action?: string;
+  sticky?: boolean;
+  align?: 'start' | 'center' | 'end';
+  visible_when?: string;
+  width?: Size;
+}
+
+export interface ListItem {
+  id: string;
+  label?: string;
+  icon?: string;
+  action?: string;
+}
+
+export interface Style {
+  /** Design tokens applied to this node. */
+  tokens?: Record<string, string>;
+  elevation?: number;
+  background?: string;
+  foreground?: string;
+  border?: string;
+  typography?: string;
+  radius?: string;
+  shadow?: string;
+  opacity?: number;
+  variant?: string;
+}
+
+export interface DesignSystem {
+  name: string;
+  colors?: Record<string, string>;
+  typography?: Record<string, string>;
+  spacing?: Record<string, string>;
+  radii?: Record<string, string>;
+  shadows?: Record<string, string>;
+}
+
+export type InteractionTrigger =
+  | 'click' | 'double_click' | 'hover' | 'focus' | 'blur'
+  | 'change' | 'submit' | 'key_enter' | 'key_escape'
+  | 'swipe_left' | 'swipe_right' | 'load' | 'scroll';
+
+export interface Interaction {
+  id: string;
+  trigger: InteractionTrigger;
+  source_node_id: string;
+  /** Verb-noun form: 'navigate:/foo', 'open:bar', 'submit:form_x'. */
+  action: string;
+  /** Optional target node id or route. */
+  target?: string;
+  /** What changes as a result. Must be observable and verifiable. */
+  result_state: string;
+}
+
+export type ResponsiveViewport = 'desktop' | 'tablet' | 'mobile' | 'wide';
+
+export type ResponsiveRule =
+  | 'keep' | 'hide' | 'drawer' | 'bottom_nav' | 'stack' | 'scroll'
+  | 'card_list' | 'col_reduce' | 'collapse' | 'expand'
+  | 'icon_only' | 'label_only';
+
+export interface Responsive {
+  viewport: ResponsiveViewport;
+  rule: ResponsiveRule;
+  target_node_id: string;
+  /** Specific property overrides. Empty object means no change beyond the rule. */
+  changes: Record<string, unknown>;
+}
+
+export type AcceptanceType = 'layout' | 'interaction' | 'responsive' | 'a11y' | 'content' | 'performance';
+export type AcceptancePriority = 'blocker' | 'must' | 'should' | 'nice';
+export type VerificationMethod =
+  | 'manual_visual' | 'manual_ia_review'
+  | 'dom_query' | 'computed_style' | 'axe_audit'
+  | 'screenshot_diff' | 'interaction_replay' | 'code_diff';
+
+export interface Acceptance {
+  id: string;
+  type: AcceptanceType;
+  /** Verifiable assertion. Must be testable, not subjective. */
+  statement: string;
+  /** Node id, viewport id, or selector pattern. */
+  target: string;
+  priority: AcceptancePriority;
+  verification_method: VerificationMethod;
+}