Widgets

Widgets

Widgets are Topogram reusable semantic UI contracts, not framework component trees.

Status: current Audience: UI authors, generator authors, and agents Use when: you need semantic widget, display-field, behavior, or design-token guidance.

widget is Topogram’s reusable semantic UI contract. It is not a React, Svelte, SwiftUI, or Android component. Generators map widget contracts to their stack.

Authoring

widget widget_data_grid {
  name "Data Grid"
  description "Reusable tabular display"
  category collection
  props {
    rows array required
    selected_ids array optional default []
  }
  events {
    row_select shape_output_item_card
  }
  patterns [resource_table data_grid_view]
  regions [results toolbar]
  status active
}

Place widgets through widget_bindings on a ui_contract projection. Prefer a reusable layout_contract for screen structure, then bind widgets to inherited layout regions:

region_contract region_collection_results {
  name "Collection Results"
  description "Primary result area for collection screens."
  kind results
  pattern resource_table
  placement primary
  status active
}

layout_contract layout_collection_list {
  name "Collection List Layout"
  description "Collection screen with result content."
  region {
    id results
    uses region_collection_results
  }
  status active
}

projection proj_ui_contract {
  type ui_contract
  screens {
    screen item_list title "Items" kind list layout layout_collection_list
  }
  widget_bindings {
    screen item_list region results widget widget_data_grid data rows from cap_list_items event row_select navigate item_detail
  }
  status active
}

Concrete web_surface, ios_surface, and android_surface projections realize the shared UI contract. They own routes and surface hints, not widget placement.

screen_regions remains available for one-off regions and screen-specific overrides. It should not be the default way to repeat the same toolbar, filters, results, content, or footer regions on every screen.

Display Fields

Topogram beta UI proof uses derived display fields instead of a new display DSL. ui-surface-contract derives fields from screen shapes, capability output shapes, and widget data bindings. A widget usage includes the data prop, source capability/shape, source shape, field names, human labels, roles, type, and requiredness.

Generators must render supported collection widgets from those fields. A table or board should not guess columns at runtime with Object.keys(...). If Topogram cannot derive display intent, reports emit diagnostics instead of silently inventing UI.

Behavior

Widgets can declare only the canonical behavior vocabulary: selection, sorting, filtering, search, pagination, grouping, drag_drop, inline_edit, bulk_action, optimistic_update, realtime_update, and keyboard_navigation. Projection bindings realize those behaviors by connecting data, events, navigation, and capabilities.

Design Contracts

ui_contract records define the semantic UI. design_contract records own design-system scope, platforms, package identity, and token mappings. design_realization_set records map semantic widgets to platform component refs and behavior support.

The graph is not a render tree. It is a work map: layouts compose semantic regions, screens choose a layout, widgets bind into those regions, and realization sets show how those widgets are rendered, contract-only, implementation-owned, or unsupported on each platform.

design_contract design_company_web {
  name "Company Web Design Contract"
  description "Defines company web design-system scope and token names."
  platforms [web]
  surfaces [proj_web_surface]
  library company_web
  package "@company/ui"

  token_mappings {
    color_role danger token "company.color.danger"
    typography_role body token "company.typography.body"
  }

  status active
}

design_realization_set realization_set_company_web_widgets {
  name "Company Web Widget Realizations"
  description "Maps shared widgets to company web component refs."
  design_contract design_company_web
  status active

  widget_realization {
    id review_queue_grid_wide
    widget widget_review_queue
    platform web
    viewport wide
    component_ref "company.reviewQueueGrid"
    pattern resource_table
    density compact
    state_coverage [loading empty error]
    role_contexts [reviewer]
    theme_contexts [light dark]
    locale_contexts [default_locale]
    status rendered
    behaviors_rendered [selection]
    behaviors_contract_only [sorting]
  }

  widget_realization {
    id review_queue_cards_narrow
    widget widget_review_queue
    platform web
    viewport narrow
    component_ref "company.reviewQueueCards"
    pattern card_list
    status contract_only
  }
}

Use stable component refs, not local source import paths. A source path may be evidence in a report or maintained app, but it is not canonical contract identity. If a widget has no mapping, or if a behavior is contract_only or unsupported, ui-realization-report and focused UI slices show that as developer/agent review work.

Use ui-design-coverage before claiming design parity. It groups coverage by platform, surface, and widget, then emits a design matrix for designers and agents. The matrix includes component refs, viewport, density, state coverage, token status, accessibility status, i18n status, and review rows for unmapped widgets, missing platforms, missing states, and contract_only or unsupported behavior. For the end-to-end mapping workflow, see Map A Design System.

Required checks

These command shapes are covered by regression tests:

topogram emit ui-widget-contract ./topo --widget widget_data_grid
topogram emit widget-conformance-report ./topo --projection proj_web_surface --json
topogram emit ui-realization-report ./topo --projection proj_web_surface --json
topogram query ui-design-coverage ./topo --projection proj_web_surface --json
topogram query ui-design-coverage ./topo --projection proj_web_surface --format markdown
topogram widget check ./topo --projection proj_web_surface
topogram widget behavior ./topo --projection proj_web_surface --widget widget_data_grid --json
topogram query widget-behavior ./topo --projection proj_web_surface --widget widget_data_grid --json
topogram query slice ./topo --widget widget_data_grid
topogram query slice ./topo --projection proj_web_surface --screen item_list --json

Use --json for agent packets and --write --out-dir <dir> when a report or contract should be written to disk.

Migration review

When a widget contract changes against a baseline, use context-diff to review the migration plan:

topogram emit context-diff ./topo --from-topogram ./baseline/topo --json

The widget_contract_migration_plan section lists changed widget contract sections, affected projections, and the exact widget contract, conformance, behavior, and surface-contract commands to run before regenerating or updating maintained UI code.

Generator rule

If a generator accepts a widget pattern, tests should prove it appears in the normalized contract, ui-realization-report, generated coverage, or generated app output. Generated web wrappers preserve data-topogram-widget, data-topogram-region, data-topogram-screen, and data-topogram-display-field markers. Generated web output also preserves message and accessibility intent with data-topogram-message-key, data-topogram-accessibility-target, keyboard/focus markers, and locale policy coverage.

Unsupported widget, component, or platform realization is developer/agent review work. It must be shown as contract_only, unsupported, or explicit implementation work in reports and focused slices; it must not silently disappear or be replaced by an unmarked generic fallback.

Web UI beta proof

Topogram’s beta UI proof is web-first and semantic. React and SvelteKit generation must preserve the same screens, routes, regions, widget usages, display fields, behavior coverage, and design-token intent from one ui_contract.

Use these proof commands when UI contracts or generator support change:

topogram emit ui-surface-contract ./topo --projection proj_web_surface --json
topogram emit ui-realization-report ./topo --projection proj_web_surface --json
topogram query ui-design-coverage ./topo --projection proj_web_surface --json
topogram emit widget-conformance-report ./topo --projection proj_web_surface --json
topogram query slice ./topo --projection proj_web_surface --screen <screen-id> --json

The current beta bar is compile plus deterministic contract/coverage assertions. Semantic i18n and accessibility obligations are part of that contract now. Screenshot comparison, visual diffing, locale catalog completeness, and automated accessibility audits are future proof layers.

See Beta Readiness for the release-level UI proof bar and what remains preview-only.