DSL Reference

DSL Reference

Topogram files use .tg statements:

Status: current Audience: Topogram authors and tooling implementers Use when: you need DSL statement and field reference material.

Topogram files use .tg statements:

kind identifier {
  field value
  block_field {
    entry values
  }
}

The parser accepts generic statement syntax. The validator defines the public grammar.

Statement kinds

• term
• actor
• role
• enum
• entity
• shape
• rule
• capability
• widget
• region_contract
• layout_contract
• design_contract
• design_realization_set
• journey
• workflow
• decision
• projection
• orchestration
• verification
• operation
• domain
• pitch
• requirement
• acceptance_criterion
• task
• plan
• bug

Documents are markdown files with frontmatter under topo/docs/**.

Rule status

Rules use a rule-specific lifecycle: draft, proposed, enforced, and deprecated. Use status enforced for rules that currently apply. Other graph kinds may still use status active where their lifecycle allows it.

Terms and Glossary

term records define project vocabulary. They are graph-native, can be grouped with category, and can be tied to a domain with domain. Other records can reference slice-relevant vocabulary through related_terms; entities also keep uses_terms for business/domain language.

term term_context_slice {
  name "Context Slice"
  description "A focused graph packet for one implementation target."
  category agent_workflow
  domain dom_sdlc_query_agent_context
  aliases [slice focused_packet]
  status active
}

capability cap_query_context {
  name "Query Focused Context"
  description "List and show focused query packets."
  related_terms [term_context_slice]
  status active
}

Emit the human glossary from term records:

topogram emit glossary ./topo --write --out-dir docs/concepts
topogram emit glossary ./topo --check docs/concepts/glossary.md

Projection types

• ui_contract
• web_surface
• ios_surface
• android_surface
• api_contract
• db_contract
• cli_surface

UI ownership

ui_contract owns semantic UI blocks:

• screens
• screen_regions
• navigation
• app_shell
• collection_views
• screen_actions
• visibility_rules
• field_lookups
• widget_bindings
• design_tokens
• messages
• accessibility

Screens may reference reusable semantic layouts with layout <layout_contract>. Those layouts inherit reusable regions from region_contract records. screen_regions remains available for one-off regions and per-screen overrides.

Concrete surfaces own routes and hints:

• screen_routes
• web_hints
• ios_hints

messages models translation intent, not locale catalogs:

messages {
  locale default "en-US" fallback "en-US" direction ltr supported ["en-US"]
  message msg_item_list_title key "items.list.title" default "Items" context screen_title screen item_list
  message msg_items_table_label key "items.table.label" default "Items table" context widget_label widget widget_data_grid
}

accessibility models obligations, not raw aria-* attributes:

accessibility {
  screen item_list role main name_from message msg_item_list_title keyboard standard focus visible live off
  widget widget_data_grid role grid name_from message msg_items_table_label keyboard data_grid focus roving_tabindex live off
}

region_contract defines a reusable semantic work area. It is not a DOM node, component, or CSS class.

region_contract region_collection_results {
  name "Collection Results"
  description "Primary result collection area for list, board, and calendar screens."
  kind results
  pattern resource_table
  placement primary
  states [loading empty error]
  density comfortable
  style_intent [surface scannable]
  accessibility_obligations [region_label keyboard_reachable]
  i18n_obligations [empty_state_copy]
  allowed_widget_patterns [resource_table card_list calendar]
  status active
}

layout_contract composes region contracts into a reusable semantic template. Layouts are semantic templates, not framework templates.

layout_contract layout_collection_list {
  name "Collection List Layout"
  description "Standard collection screen with toolbar, filters, and results."
  parent layout_standard_app_shell
  fills content

  region {
    id toolbar
    uses region_action_toolbar
    placement top
  }

  region {
    id filters
    uses region_filter_panel
    placement secondary
  }

  region {
    id results
    uses region_collection_results
    placement primary
  }

  status active
}

ui_contract screens reference the layout. Widget bindings may target inherited layout regions or explicit screen_regions overrides:

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
}

design_contract owns design-system scope, supported platforms, optional surface bindings, package identity, and design-token mappings. Real projects should keep widget/component mappings in design_realization_set records so the contract header stays small at scale.

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 maps semantic widgets to platform component refs and behavior support. The graph is not a render tree; it is a work map that shows where design/platform realization work belongs and what still needs review.

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 data_grid_wide
    widget widget_data_grid
    platform web
    viewport wide
    component_ref "company.dataGrid"
    pattern data_grid_view
    density compact
    state_coverage [loading empty error]
    role_contexts [reviewer]
    theme_contexts [light dark]
    locale_contexts [default_locale]
    review_notes "Sorting is still contract-only until the adapter proves it."
    status rendered
    behaviors_rendered [selection]
    behaviors_contract_only [sorting]
  }
}

Supported design-contract platforms are web, ios, and android. Widget realization statuses are rendered, contract_only, implementation_owned, and unsupported. Realization entries may also carry review metadata: density, state_coverage, role_contexts, theme_contexts, locale_contexts, and review_notes. Realization entries must use component_ref; import_path, source_path, and path are rejected as canonical identity. Component and behavior mappings belong in design_realization_set, not in design_contract.

Use topogram query ui-design-coverage ./topo --projection <surface> --json to review the JSON design matrix, or --format markdown for a designer-readable table. The matrix surfaces unmapped widgets, missing platforms, missing states, missing token mappings, missing accessibility obligations, missing i18n messages, and contract-only or unsupported behavior from authored design contracts and realization sets.

API blocks

api_contract projections use blocks such as endpoints, wire_fields, responses, error_responses, preconditions, idempotency, cache, delete_semantics, async_jobs, async_status, downloads, authorization, and callbacks.

DB blocks

db_contract projections use tables, columns, keys, indexes, relations, and lifecycle.

CLI surface blocks

cli_surface projections use commands, command_options, command_outputs, command_effects, and command_examples.

Allowed command effects are read_only, writes_workspace, writes_app, network, package_install, git, and filesystem.

Journeys

journey statements model ordered user, maintainer, or agent workflows as graph source. Canonical journeys live in .tg files, usually under topo/journeys/. Markdown journey documents are transitional/supporting drafts produced by import or reconcile workflows; promote durable journeys into graph-native journey records.

Required fields:

• name
• description
• status
• actors
• goal
• at least one step { ... }

Allowed statuses are draft, canonical, active, and deprecated.

Relationship fields may include domain, roles, related_capabilities, related_rules, related_projections, related_widgets, related_verifications, related_decisions, and related_docs.

Journey steps and alternates use repeated ordered record blocks. The parser syntax is the normal block syntax; validators preserve source order and enforce known record fields.

journey journey_greenfield_start_from_template {
  name "Greenfield Start From Template"
  description "A developer starts a new app from a template."
  status canonical
  domain dom_catalog_templates
  actors [actor_consumer_developer]
  goal "Create a valid generated app from a copied Topogram starter."

  step {
    id inspect_templates
    intent "Find available templates."
    commands ["topogram template list --json"]
    expects ["Template aliases and package-backed entries are visible."]
  }

  step {
    id create_project
    intent "Copy the selected template into a project."
    after [inspect_templates]
    commands ["topogram copy hello-web ./my-app"]
    expects ["Project contains topo/, topogram.project.json, README.md, and AGENTS.md."]
  }

  alternate {
    id use_package_spec
    from inspect_templates
    condition "The desired template is not in the catalog."
    commands ["topogram copy @topogram/template-hello-web ./my-app"]
  }
}

step records support id, intent, after, commands, expects, and notes. alternate records support id, from, condition, commands, expects, and notes. Step IDs must be unique, after must reference existing steps, and alternate.from must reference an existing step.

Workflows

workflow statements model application state machines or process flows as graph source. Use them when the app itself has states and transitions, such as review lifecycles, approval flows, XState machines, BPMN processes, or other workflow-native sources.

Required fields:

• name
• description
• status
• at least one state { ... }

Allowed statuses use the normal graph lifecycle: draft, proposed, active, and deprecated.

Relationship fields may include domain, actors, roles, related_capabilities, related_rules, related_entities, related_journeys, related_verifications, related_decisions, and related_docs.

Workflow states and transitions use repeated ordered record blocks. Validators preserve source order, require unique IDs, and check transition state and capability references.

workflow workflow_review {
  name "Review Workflow"
  description "Tracks an item from draft through review and approval."
  status active
  actors [actor_reviewer]
  related_capabilities [cap_submit_item cap_approve_item]

  state {
    id draft
    name "Draft"
    type initial
  }

  state {
    id submitted
    name "Submitted"
  }

  state {
    id approved
    name "Approved"
    type terminal
  }

  transition {
    id submit
    from draft
    to submitted
    event "SUBMIT"
    capability cap_submit_item
  }

  transition {
    id approve
    from submitted
    to approved
    event "APPROVE"
    capability cap_approve_item
  }
}

state records support id, name, description, and type. State types are normal, initial, terminal, final, and error. transition records support id, from, to, event, capability, guard, actors, roles, and description. to is required; from may be omitted for entry or start transitions.

Workflow slices are available through:

topogram query slice ./topo --workflow workflow_review --detail compact --json
topogram emit context-slice ./topo --workflow workflow_review --detail compact --json