tmt-design-system git:20261104.d172209A

Immutable. This exact content never changes and is served at /api/v1/blob/ff02476abbc04e5c.

---
name: tmt-design-system
description: Use a TMT design system in a Colab page or UI mockup - find it, pin it so the page follows its draft (or lock one release), and write only its component tags.
---

# Design systems in Colab pages

A design system is a tree of Colab pages in the Design tab, with components that have their own
tags (`<prefix>-button`, ...). A page pins the system and follows its live draft: an edit in the
Design tab shows on the page. A published version is a release, a fixed bundle a page can lock to
instead. Make and edit the page itself with the tmt-colab skill.

## When to use one

Use a design system when the person names one, asks for a mockup of a product UI that has one, or
the page should look like a product screen. Plain notes, plans and reviews need none: Colab's
own page style already applies.

## Find the release

```sh
tmt colab design ls --json                       # systems, prefixes, released versions
tmt colab design show <system>[@version] --json  # pin, lock, components (default: latest)
```

`<system>` is the `system` from `ls`, the tag prefix or the name. `tmt-gui` is the built-in
tmt GUI system (tags `tmt-ui-*`): every install can pin it, and its `show` needs nothing running.
It is the default for TMT product mockups. For a structured page, its block tags are `tmt-ui-block-document` holding
`tmt-ui-block`s, each with one of `tmt-ui-heading-block`, `tmt-ui-text-block`, `tmt-ui-list-item`,
`tmt-ui-todo`, `tmt-ui-table-block`, `tmt-ui-card-block`, `tmt-ui-callout` or `tmt-ui-code-block`,
plus `tmt-ui-block-mention`, `tmt-ui-block-menu` and `tmt-ui-block-toast`. A space's own systems need a running
`tmt colab serve` for `show`. `show` prints `meta` (the pin line to copy), `lockMeta` (the line
that locks this release), `principles`, and every component's `tag`, `props` (enum values or type,
default), `slots` and `examples`. Read it once per page; there is no per-system skill.

A system whose `latest` is `none` has no release yet, so `show` cannot list its components. Tell
the person that publishing is their step in the Design tab.

## Write the page

1. Put the `meta` line from `show` first in the page, exactly as printed:
   `<meta name="tmt-ds" content="<system>">`. One system per page. Use `lockMeta` instead only when
   the person asks for a page that must not change, for example a signed-off mockup.
2. Put components directly in page flow. For a device-sized mockup stage, wrap them in an
   explicitly sized scope such as `<div data-tmt-ds-scope style="width:390px;height:844px">`.
   Each stage owns its overlays, focus and responsive size; controls outside it stay usable.
   Start overlays closed.
3. Build with the system's tags only. Start from its `examples`, keep their markup shape, and
   set only the listed props with listed values. Put content in the default slot, or in a named
   slot with `slot="<name>"`.
4. Follow the release's `principles`, for example one primary action per surface.
5. Plain HTML can sit around the components for layout and text. Do not restyle a component's
   inside with your own CSS; choose its props instead.

The page shows design-system problems inside its frame: a tag from another prefix, an unknown
component, an invalid prop value, a draft that does not compile, or a
pin that cannot be read. A page that follows the draft is checked against the draft, so a renamed
component or prop shows up there. Fix every one before handing the page over. The page checks custom prefixes after resolving the system.

## Versions

- A page that follows the draft sees every edit in the Design tab, published or not. The built-in
  `tmt-gui` draft is the release this TMT ships.
- A lock never moves by itself. A locked page stays on its release until someone changes the pin;
  it shows a notice when TMT no longer carries that release.
- To move a locked page, run `show` for the version (or use `meta` to follow the draft), replace
  the line, and check that every tag and prop still exists there. Do not do it without the
  person's ask.
- Never edit a system's own pages to make your page work. Comments and fixes on a system go
  through its Design pages (tmt-colab skill, editing: "A design-system example"). The built-in
  tmt GUI's pages are generated from `design/browser-ui`: a fix there is a code change through a
  PR, never a page edit.

## Limits

- One system per page. A lock is read-only: the bundle is verified by its hash, and a changed
  bundle does not render.
- Components render only inside Colab; a downloaded standalone page does not carry them.
- Interactive behaviour is what the component offers. For your own scripts use the page runtime
  (tmt-colab skill, runtime).