Skill Display Construction — Basics

Purpose

This skill is the common ground for every FrameworX display build, regardless of paradigm. Load it whenever you do display work. Pair with Skill Display Construction — Canvas for pixel-positioned HMI/P&ID displays or with Skill Display Construction — Dashboard for grid-based data displays.

What this skill covers:

• 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 syntax that hits every display
• Spacing, typography, and minimum sizing tokens shared between Canvas and Dashboard
• Symbol-writing rules (Wizard, Library, Solution prefixes)

What this skill does NOT cover: the equipment cookbook, controls reference, or grid-cell layout — those live in Canvas and Dashboard.

Prerequisites

• Solution open with at least a minimal UNS (tags created). Displays reference tags; without tags there is nothing meaningful to bind.
• You know which theme family you are targeting. If you don't, pick Steel (light office) or Onyx (dark control room).

Tools you use over and over

Section 1 — Theme-first mental model

The one-sentence rule

Do not hardcode hex colors unless the hex carries process meaning. Use FillTheme, StrokeTheme, ForegroundTheme, BackgroundTheme, BorderBrushTheme properties with semantic brush names from list_elements('ThemeColors').

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.

Pick a theme at the start of the build

Before placing any element, decide which theme family this solution is for:

• Control room (dark, dim) → Onyx or Graphite
• Office dashboard (bright, air-conditioned) → Steel or Platinum
• Outdoor tablet (sunlight) → ContrastLight
• OEM branded kiosk → Pearl/Indigo or Gold/Coffee
• Unknown / default → Steel (light default) or Onyx (dark default)

Then use *Theme properties throughout — the displays render correctly under any theme, but look best under the one you designed for.

The brush catalogue

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

Note on Element*-family brushes: ElementRed, ElementOrange, ElementYellow may not apply consistently on all shape types. If you don't see your intended color, prefer StateRed / ColorAmber / StateAlarm.

How theme properties work on the wire

When you write {"FillTheme": "ElementBlue"} the writer stores it as {"Fill": "theme:ElementBlue"}. Both input forms are equivalent:

• {"FillTheme": "StateGreen"} → stored as {"Fill": "theme:StateGreen"}
• {"Fill": "theme:StateGreen"} → stored as {"Fill": "theme:StateGreen"}
• {"Fill": "#FFEF4444"} → stored as {"Fill": "#FFEF4444"} (hex)
• {"Fill": "#FF000000", "FillTheme": "ElementBlue"} → stored as {"Fill": "#FF000000"} (hex wins)

Use FillTheme / StrokeTheme / ForegroundTheme / BackgroundTheme / BorderBrushTheme for readability — it documents your intent. The writer collapses to the prefixed form. If you mean a hardcoded color, use Fill/Stroke/Foreground etc. directly.

The display-root Background footgun

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.

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.

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. CHECK — get_state(target='designer'), look at errorList
5. FIX — if errorList non-empty, fix and go back to step 3
6. 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.

Never use screenshots to self-validate

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

• @Tag.<path> — the tag's Value. Do NOT append .Value; it's implicit (@Tag.X == @Tag.X.Value).
• @Tag.<path>/Attr.<member> — a UDT member on the tag.
• @Tag.<path>.<udt_member> — alternate dot syntax for UDT members.
• @Dataset.Query.<QueryName> — dataset query result (for DataGrid, ComboBox DataTable source).
• @Client.Context.<property> — session-scoped client context (AssetName, AssetPath, Theme).
• @Client.<property> — general client-scoped tags (@Client.Theme, @Client.AlarmPage.Filter).
• @Now — current time.

Never use @Label. in display-element bindings. @Label. is only for symbol-definition internals.

Tag paths must be FULL paths

Include asset folders in every tag reference: Area1/Line1/Motor1.Speed, not Motor1.Speed.

Inline interpolation — the composite LinkedValue pattern

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

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

Writer normalizations — what you write ≠ what you read back

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.

Call 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:

Always 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.

Binding via SymbolLabels — never via direct properties

SymbolLabels is the ONLY way to push data into a symbol:

• Key must match a label key defined inside the symbol (case-sensitive).
• LabelValue uses @Tag.X / @Client.Context.X / @Now / composite strings.
• FieldType: "Expression" is the default and handles tag paths and expressions.
• Never use @Label.X in display-element SymbolLabels. @Label. is a symbol-definition internal only.

Section 8 — Layouts and asset navigation (brief)

Layouts

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:

• Layout with Header + AssetTree (left menu) + Content region
• User selects an asset → Client.Context updates → content displays react
• Static binding: @Tag.Area1/Line1/State
• Dynamic binding: Asset(Client.Context.AssetPath + "State1")

A single display template can show data for whichever asset the operator selects. See the Dashboard skill for the AssetsTree + ChildDisplay master-detail pattern.

Section 9 — CodeBehind (brief pointer)

CodeBehind is client-side C# or VB.NET code embedded in each display. Lifecycle methods: DisplayOpening(), DisplayIsOpen(), DisplayClosing(), DialogOnOK().

The Contents field format starts with CSharp\r\n or VBdotNet\r\n before the code. Full CodeBehind guidance lives in the Skill Scripts Expressions skill.

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:

• Skill Display Construction — Canvas — absolute-positioned displays for HMI, P&ID, process overviews, equipment layouts
• Skill Display Construction — Dashboard — grid-based displays for data monitoring, KPI walls, operator consoles

Both assume this Basics skill is loaded.