Page History

...

• The theme-first mental model (no hex unless it carries process meaning)
• write_objects mechanics on DisplaysList (document objects, read-before-write)
• The build loop (write_objects → get_state → check errorList → fix → move on)
• Binding and compile-time gotchas that hit every display (UDT inheritance, system tag columns)syntax that hits every display
• Spacing, typography, and minimum sizing tokens shared between Canvas and Dashboard
• Symbol-writing rules (Wizard, Library, Solution prefixes)

...

Tools you use over and over

Section 1 — Theme-first mental model

...

Hex is reserved for things with domain meaning that shouldn't change across themes — heat = red, water = blue, alarm = red, batch progress = amber. Everything else should adapt to whichever of the 13 theme pairs the operator is running.

The 13 theme pairs

Theme is switched at runtime via @Client.Theme = "Dark". Every properly-themed display reflows automatically.

...

Call list_elements('ThemeColors') for the authoritative list. The 12 brushes you'll use 90% of the time:

Other brushes exist and are valid — ElementBlue, ElementGreen, AlarmHighPriority, ColorCyan, ColorSlate, ColorAmber, ColorTeal, ColorCoral, ColorPurple, ColorDimmed, PopupBackground, DefaultFill, DefaultStroke, DefaultBorder, and more. Check list_elements('ThemeColors').

?? Known issue (TDEV-1275)Note on Element*-family brushes: ElementRed, ElementOrange, ElementYellow are silently dropped at write time on Ellipse (and possibly other shape types). Prefer may not apply consistently on all shape types. If you don't see your intended color, prefer StateRed / ColorAmber / StateAlarm instead until resolved.

How theme properties work on the wire

...

Every newly created display gets "Background": "#FFFAFAFA" (light gray) baked in. If you're building for a dark theme, this shows through at every gap or transparent edge. Always set the root Background explicitly:

...

{
  "Name": "MyDisplay",
  "PanelType": "Canvas",
  "Size": "1600 x 900",
  "Width": 1600, "Height": 900,
  "Background": "theme:PageBackground",
  "Elements": [ /* ... */ ]
}

Or, for a full-bleed dark background on a dark-themed display, place a full-size Rectangle with FillTheme: "PageBackground" as the first element.

...

The canonical display envelope

...

{
  "Name": "MyDisplay",
  "PanelType": "Canvas",
  "DisplayMode": "Page",
  "Navigate": "true",
  "Size": "1600 x 900",
  "OnResize": "StretchFill",
  "Width": 1600,
  "Height": 900,
  "Background": "theme:PageBackground",
  "Elements": [ /* ... */ ]
}

Non-negotiable rules

• The identifier field is Name. Never ObjectName.
• PanelType is required. "Canvas" or "Dashboard". Omitting it silently defaults to Canvas.
• No JsonFormat wrapper. All properties at the top level.
• DisplayMode controls window style: "Page" (normal), "Dialog" (modal popup), "Popup" (floating non-modal), "PopupWindow" (separate window — not available on Web, avoid unless explicitly requested).
• OnResize: "StretchFill" is the sensible default. Use "NoAction" for fixed-pixel displays.
• DisplaysDraw is NOT a writable table. It is the Designer visual editor UI. Use DisplaysList for all display create/edit operations.

...

get_state on a display returns compile errors as a list:

...

...

{
  "errorList": [
    {
      "ID": 0,
      "ErrorCode": "BC30456",
      "IsWarning": false,
      "Line": 8,
      "Column": -1,
      "Location": "Uid_41_TTextBlock_LinkedValue_e1",
      "ErrorText": "error BC30456: 'Status' is not a member of 'UserType'."
    }
  ]
}

The Location string tells you which element (by Uid) and which property (LinkedValue, Expression, etc.) has the problem. Use it to find and fix the exact property.

...

write_objects success IS the confirmation. The errorList check covers compile correctness. Screenshots are only for sharing visual context with the user — not for the AI to confirm its own work.

Section 4 — Binding

...

syntax

@Tag. is the only binding prefix you'll use in displays

...

The single most important text pattern. Instead of two TextBlocks (value + unit) side by side, use ONE with composite LinkedValue:

...

{
  "Type": "TextBlock",
  "LinkedValue": "Temperature: {@Tag.Reactor/Temperature_C} °C",
  "FontFamily": "Inter",
  "FontSize": 14,
  "Width": 220, "Height": 22
}

Patterns:

• "Flow: {@Tag.X} GPM" — label + value + unit
• "{@Tag.X} NTU" — value + unit
• "pH: {@Tag.X}" — label + value
• "Operator: {@Tag.Shift/CurrentOperator}" — label + bound string

UDT inheritance limitation — TDEV-1272

When a tag is typed by a UDT with a BaseUserType, members defined on the base UDT DO NOT resolve in LinkedValue bindings.

Example: S88_Unit has BaseUserType = S88_Equipment. S88_Equipment declares Status, AssetTag, Location, Description.

• ? {@Tag.PharmaCo/Plant/CellA/Mixer_M101/Attr.Status} — fails with BC30456: 'Status' is not a member of 'UserType'
• ? {@Tag.PharmaCo/Plant/CellA/Mixer_M101/Attr.Running} — works (Running is defined directly on S88_Unit)

Workaround: bind only to members defined directly on the tag's UDT, not inherited members. Redeclare common members on each derived UDT if necessary (defeats the purpose of inheritance but it's the only fix until TDEV-1272 ships). The runtime object model DOES inherit correctly — this is purely a design-time binding compiler gap.

Tag-row system columns not bindable — TDEV-1273

Columns on the UnsTags row that aren't UDT members (like SourceIri) cannot be bound:

• ? {@Tag.<path>/Attr.SourceIri} — fails with BC30456: 'SourceIri' is not a member of 'UserType'

Workaround: use literal text. For ontology-aware displays, hardcode the SourceIri value from the UDT/tag definition into the display.

Polygon / Polyline / Gridline / Spline silently skip on missing Points

If you write a Polygon without Points, nothing renders and no error is produced — the element is simply invisible.

...

Polygon / Polyline / Gridline / Spline silently skip on missing Points

If you write a Polygon without Points, nothing renders and no error is produced — the element is simply invisible.

// 

...

Silently invisible
{ "Type": "Polygon", "Left": 100, "Top": 100, "Width": 50, "Height": 50 }

// 

...

Renders correctly
{ "Type": "Polygon", "Left": 100, "Top": 100, "Width": 50, "Height": 50, "Points": "25,0 50,50 0,50" }

Polygon auto-closes (last point connects back to first). Polyline doesn't. For pipe runs use Gridline (constrains to horizontal/vertical segments — the P&ID convention).

...

The writer normalizes several shapes on save. When you later read the display back, you get the normalized form:

Consequence: when round-tripping a display for edits, don't expect to see "Type": "Cylinder" — you'll see a "Path" with auto-generated Data. Edit the Path, or add new Cylinders alongside (they normalize too).

Section 5 — Spacing and typography tokens

Spacing scale

Typography ramp

Use FontFamily: "Inter" (or the solution's chosen font) universally.

Minimum sizes (hard floors)

Color hex fallbacks (for process meaning only)

Section 6 — Element types overview

This tells you what exists. Canvas and Dashboard skills cover how to use each category.

?? Avoid (phantom entries, TDEV-1274): Triangle, Octagon, Parallelogram, Hill, Curve, Senoid, Wave, T-Junction. Listed by list_elements() but cannot be created — neither Type: "X" alone nor with SymbolName: "Wizard/X" worksCall list_elements() for the authoritative, up-to-date catalog of every element type in the current release. When in doubt, always discover at runtime rather than relying on a static list.

Section 7 — Symbols (all three sources)

Every symbol uses Type: "Symbol". Not Type: "Pump", not Type: "Valve". One element type, many SymbolName values.

...

...

{
  "Type": "Symbol",
  "SymbolName": "Wizard/PUMP",
  "Left": 400, "Top": 300,
  "Width": 80, "Height": 80,
  "SymbolLabels": [
    { "Type": "SymbolLabel", "Key": "State", "LabelName": "State", "LabelValue": "@Tag.Pump1/Running", "FieldType": "Expression" },
    { "Type": "SymbolLabel", "Key": "RPM",   "LabelName": "RPM",   "LabelValue": "@Tag.Pump1/Speed",   "FieldType": "Expression" }
  ]
}

The 5 Wizard symbols

The complete Wizard catalog is 5 symbols:

Anything else you see in legacy docs (Wizard/Triangle, Wizard/Curve, etc.) does not exist — see TDEV-1274Always treat list_elements('Wizard') as the authoritative runtime catalog — if an entry does not appear there, do not attempt to use it.

Library symbols (~1600)

Call list_elements('Library/HMI') or specific subfolders (Library/HMI/Pumps, Library/HMI/Valves, etc.) to discover. Library symbols auto-import on first reference:

...

...

{ "Type": "Symbol", "SymbolName": "Library/HMI/Pumps/CentrifugalPump", "Left": 200, "Top": 200, "Width": 120, "Height": 80 }

Solution symbols (your own)

User-created symbols in the current solution use Solution/ prefix:

...

{ "Type": "Symbol", "SymbolName": "Solution/MyCustomTank", "Left": 100, "Top": 100, "Width": 80, "Height": 100 }

Sizing

All symbols scale to any proportional size. Default is 65×65 — use 40×40 for compact, 80×80 for medium, 120×120 for large. Maintain aspect ratio; don't stretch asymmetrically.

...

Layout regions: Header, Footer, Menu, Submenu, Content. The Startup layout defines which display loads into each region.

...

get_table_schema('DisplaysLayouts')
get_objects('DisplaysLayouts', names=['Startup'], detail='full')

Asset navigation

For plant-wide navigation with dynamic content:

...

Section 10 — Common pitfalls

Section 11 — Quick reference

...

# Session startup
get_table_schema('DisplaysList')
list_elements('ThemeColors')

# Before first use of a type this session
list_elements('<ElementName>')
list_dynamics('<DynamicName>')

# Read-modify-write an existing display
get_objects('DisplaysList', names=['X'], detail='full')
write_objects(table_type='DisplaysList', data=[...])
get_state(target='designer')  # verify errorList empty

Display envelope template:

...

{
  "Name": "MyDisplay",
  "PanelType": "Canvas",
  "DisplayMode": "Page",
  "Navigate": "true",
  "Size": "1600 x 900",
  "OnResize": "StretchFill",
  "Width": 1600,
  "Height": 900,
  "Background": "theme:PageBackground",
  "Elements": []
}

Next skills

After the basics are internalized, load the paradigm-specific skill:

...