Page History

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

...

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:

...

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:

...

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.

...

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:

...

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:

...

• "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.

...

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:

...

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

...

{
  "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:

...