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 → visual checkpoint → fix → move onrespond)
• Binding 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

Call list_elements('ThemeNames') for the authoritative list at runtime. The typical usage map:

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').

...

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

Section

...

1.5 — The visual quality bar

The first 5 seconds an operator looks at the display decide whether the build is good. Compile cleanliness is necessary but not sufficient — errorList is blind to whether anyone would actually want to use the screen. Before responding as finished, three things must be true within five seconds of imagining the operator opening the display:

1. The page is not empty. Every display, especially a landing display like MainPage, has at least one piece of content visible above the fold. An empty MainPage is a UX failure even when errorList is clean.
2. The largest text is readable from operator working distance. Hero numbers 26–32, body text never below 14, meta text never below 10 (see §5 typography ramp). A page where every label is 9 pt is a fail regardless of layout.
3. The layout has obvious top-to-bottom or left-to-right rhythm. Zones, cells, or sections — never a free-floating cluster of small elements with no spatial story. The viewer's eye should know where to start.

If any of the three fails, the build is not finished. Pair this with the errorList-blind list in §3 below: errorList handles compile correctness, the visual quality bar handles operator-perceived correctness. The two together — not errorList alone — gate "done."

Closing self-check before respond. Ask: "Would I be embarrassed to show this to an operator?" If the answer is "maybe" or "a little", run the visual checkpoint in §3 again before responding.

Section 2 — Write mechanics

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.

Displays are document objects — read before write

Displays, Symbols, Scripts, Queries, and Reports are document objects: write_objects replaces the entire document on save. Omitted content is deleted.

When modifying an existing display:

1. Read the full document: get_objects('DisplaysList', names=['MyDisplay'], detail='full')
2. Modify your working copy (add/change/remove elements)
3. Write the complete merged document back

Never send a partial update — you'll silently delete everything you didn't include.

Keep the element list in working memory. During a session that adds, modifies, or removes elements across multiple turns, track what the display holds — same discipline a programmer uses to keep the state of the code they're editing in their head. When you write, every element you intend to keep must be in the payload, and elements you removed must be absent. errorList will not tell you about an element you forgot to drop; only the user will notice it's still on screen.

MainPage is predefined in new solutions. Write main content directly into it — no need to create a new display for the landing screen.

Category and MCP-label guard

AI-created objects are automatically tagged with the MCP category, which makes them editable / overwritable by subsequent AI writes. Objects without this label are "owned" by the user and produce Skipping existing on write attempts. This is the user-protection mechanism — respect it. When you see Skipping existing, the user can add the MCP label in Designer if they want to allow AI edits.

Exception: Description fields are always writable, even on user-owned objects without the MCP label. If the user asks you to update a description on an object you otherwise can't edit, that specific field will still save.

solution_id on every write

Every write_objects, delete_objects, rename_objects, and designer_action call should include the solution_id from the most recent open_solution or create_solution response. This verifies the session is still connected to the expected solution.

Section 3 — The build loop

This cadence catches errors within the same turn they were introduced, before they accumulate.

1. PLAN — what am I adding/changing? What tags does it bind to?
2. READ — get_objects(detail='full') if modifying an existing display
3. WRITE — write_objects(data=[...])
4. COMPILE CHECK — get_state(target='designer'), look at errorList
5. FIX — if errorList non-empty, fix and go back to step 3
6. VISUAL CHECKPOINT — see "What errorList covers, and what it doesn't" below
7. RESPOND — summarize what was built to the user and move to the next request

Reading errorList and readOnly from get_state

get_state on a display returns compile errors as a list, and also reports whether the Designer is currently read-only:

{
  "readOnly": false,
  "readOnlyReason": null,
  "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.

If errorList is absent or empty, the display compiled clean.

Also check readOnly. If it is true, a subsequent write_objects will fail — check readOnlyReason and surface it to the user before retrying. Common causes: runtime is running, another client has the display open for edit.

What errorList covers, and what it doesn't

errorList is ground truth for compile correctness: bindings resolve, required fields are present, the display will render without crashing. A clean errorList is necessary before you respond as finished.

errorList is blind to visual correctness. None of the following produce an error:

• Two elements overlapping at the same Left/Top
• A TextBlock whose LinkedValue clips because its rendered length exceeds Width
• An element placed outside its intended zone but still inside the display
• A pipe endpoint 15 px off the tank nozzle it was supposed to connect to
• A RadialGauge with YMaxValue below the tag's engineering-range maximum (pegs at max forever)
• Three 48 pt "hero" numbers on the same display, all screaming for attention
• A Polygon with valid Points but Fill equal to the background (invisible)
• A MainPage (or any landing display) that opens empty
• A detail panel that opens empty when no master row is selected (no empty-state placeholder)
• A page where every visible element is below the fold or off in a corner — nothing in the top half of the canvas

All of those compile clean. All are operator-rejected.

Visible-on-open scan (both paradigms)

Before any paradigm-specific procedure, mentally open the display from the operator's seat, top edge first. If there is nothing in the top half of the canvas — or if the only thing there is a placeholder waiting for a master selection that never came — that is a failure even on a clean errorList. Go back and add content, restructure, or wire an empty-state placeholder before continuing to the paradigm-specific checkpoint below. This catches the empty-MainPage failure and the empty-detail-panel failure before any screenshot or pixel-tweak

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.

Displays are document objects — read before write

Displays, Symbols, Scripts, Queries, and Reports are document objects: write_objects replaces the entire document on save. Omitted content is deleted.

When modifying an existing display:

1. Read the full document: get_objects('DisplaysList', names=['MyDisplay'], detail='full')
2. Modify your working copy (add/change/remove elements)
3. Write the complete merged document back

Never send a partial update — you'll silently delete everything you didn't include.

MainPage is predefined in new solutions. Write main content directly into it — no need to create a new display for the landing screen.

Category and MCP-label guard

AI-created objects are automatically tagged with the MCP category, which makes them editable / overwritable by subsequent AI writes. Objects without this label are "owned" by the user and produce Skipping existing on write attempts. This is the user-protection mechanism — respect it. When you see Skipping existing, the user can add the MCP label in Designer if they want to allow AI edits.

solution_id on every write

Every write_objects, delete_objects, rename_objects, and designer_action call should include the solution_id from the most recent open_solution or create_solution response. This verifies the session is still connected to the expected solution.

Section 3 — The build loop

This cadence catches errors within the same turn they were introduced, before they accumulate.

1. PLAN — what am I adding/changing? What tags does it bind to?
2. READ — get_objects(detail='full') if modifying an existing display
3. WRITE — write_objects(data=[...])
4. COMPILE CHECK — get_state(target='designer'), look at errorList
5. FIX — if errorList non-empty, fix and go back to step 3
6. VISUAL CHECKPOINT — see "What errorList covers, and what it doesn't" below
7. DONE — move to next display or next task

Reading errorList from get_state

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.

If errorList is absent or empty, the display compiled clean.

What errorList covers, and what it doesn't

errorList is ground truth for compile correctness: bindings resolve, required fields are present, the display will render without crashing. A clean errorList is necessary before you declare the display done.

errorList is blind to visual correctness. None of the following produce an error:

• Two elements overlapping at the same Left/Top
• A TextBlock whose LinkedValue clips because its rendered length exceeds Width
• An element placed outside its intended zone but still inside the display
• A pipe endpoint 15 px off the tank nozzle it was supposed to connect to
• A RadialGauge with YMaxValue below the tag's engineering-range maximum (pegs at max forever)
• Three 48 pt "hero" numbers on the same display, all screaming for attention
• A Polygon with valid Points but Fill equal to the background (invisible)

All of those compile clean. All are operator-rejected.

Visual checkpoint — paradigm-specific

...

Canvas: spatial correctness is the whole point. Coordinate-based composition of pipes, vessels, zone layouts, and P&ID flow is the class of work where authoring blind gets it wrong the most. Take get_screenshot(target='display', element='X') at authoring checkpoints:

1. After zone scaffolding lands (background rectangles + zone titles) — verify the zones divide the canvas as planned.
2. After main equipment is placed (symbols, vessels, pipes) — verify elements landed inside their zones and pipes connect where they should.
3. Before declaring done responding as finished — final sanity check of the composed display.

...

Dashboard: grid reflow is resolved at render time against a specific window size, and most Dashboard mistakes (wrong control choice for the cell purpose, missing Cell.HeaderLink, broken DataGrid → detail wiring) are visible in the structure, not the pixels. Take one get_screenshot at the end, before declaring done, to confirm cells populated and content did not collapse unexpectedly. If that one screenshot reveals a problem, fix and screenshot again; beyond the second screenshot, hand back to the userScreenshots are generally unnecessary for Dashboard — rely on a clean errorList and a clear written summary to the user. If something looks wrong after the user previews it, fix and iterate; don't screenshot speculatively.

Not for iterative self-soothing. Do not take a screenshot after every write just to feel certain. The cost is real and the behavior encourages re-work spirals over clean planning. Screenshots go at checkpoints, not at every turn.

Write a one-paragraph summary when you declare donerespond, regardless of paradigm: which zones or cells exist, what lives in each, which tags drive what. The summary is what the user reads before they look at the display themselves — and it forces you to notice gaps ("I reserved a zone for alarms but never put an AlarmViewer in it") that errorList cannot.

...

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.

Color hex fallbacks (for process meaning only)

Section 6 — Element types: discover at runtime

There are many element types — Shapes, Container, Interaction, Gauges, Charts, Viewer, Editors, IndustrialIcons, and the Dashboard-specific Cell. The catalogue also evolves between releases.

Rather than rely on a static list that drifts, always discover at runtime:

• list_elements() — every element type, grouped by category
• list_elements('<ElementName>') — the schema for one specific element (valid properties, defaults, notes)
• list_elements('Wizard') — the 5 Wizard symbols
• list_elements('Library/HMI') or subpath — Library symbols (see §7)
• list_elements('ThemeColors') — brush catalogue
• list_elements('ThemeNames') — theme-pair catalogue

Canvas and Dashboard skills cover which element types fit each paradigm and how to use them in contextCall 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)

...

{
"Type": "Symbol",
"SymbolName": "Wizard/PUMP",
"Left": 400, "Top": 300,
"Width": 80, "Height": 80,
"SymbolLabels": [
"SymbolLabels": [{ "Type": "SymbolLabel", "Key": "State", "LabelName": "State", "LabelValue": "@Tag.Pump1/Running", "FieldType": "Expression" },
{ "Type": "SymbolLabel", "Key": "StateRPM",   "LabelName": "StateRPM",   "LabelValue": "@Tag.Pump1/RunningSpeed",   "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:

...

]
}

The 5 Wizard symbols

The complete Wizard catalog is 5 symbols:

When to reach for a Wizard. When the equipment in the spec is a fan/blower, a rotating drive, a liquid mover, a vessel with level dynamics, or a flow-control element, the corresponding Wizard is almost always the right first move — they ship with state dynamics already wired and avoid the cost of composing the same shape from primitives. The Wizard catalog stops at five canonical types on purpose; for anything outside (compressor, heat exchanger, conveyor, sensor, instrument), fall through to Solution / Library/HPG / Library/HMI in that order. Wizard styling variants (orientation, foot detail, port direction) are user-controlled in Designer via the symbol's configuration button, not by editing the placed element's geometry.

...

Always treat list_elements('Wizard') as the authoritative runtime catalog — if an entry does not appear there, do not attempt to use it.

...

Call list_elements('Library/HMI') or specific subfolders (Library/HMI/Pumps, Library/HMI/Valves, etc.) to discover. Results are limited to 50 per call — when you see truncated: true, drill into specific subfolders to see complete listings. Library symbols auto-import on first reference:

...

Section 10 — Common pitfalls

Section 11 — Quick reference

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

// 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 AND readOnly false

// Visual checkpoint (

...

see Section 3) // Canvas: up to 3 per display (after zones, after equipment, before done)

...

// Dashboard:

...

generally unnecessary get_screenshot(target='display', nameelement='X')

Display envelope template:

...