Create Pages and Components

A Page is an HMI screen that an operator ultimately uses, with the .qp extension. A Component is a reusable visual module inside an App, with the .qpc extension. Both can switch between Design / Preview / Source.

Which one to use

Need	Use
Home Page after sign-in, equipment overview, alarm, or process-parameter screen	Page (.qp)
Status card, button group, or station area reused by several Pages	Component (.qpc)
General visual capability already supplied by a package	Package Component
A small layout used on only one Page	Keep it directly in that Page

A Component is not a standalone runtime entry. A Page can be set as home or opened through navigation.

Where to start

1. Open the context menu under Resources → Pages and select New Page.
2. Enter a clear, stable, unique name such as overview or station-detail.
3. For reusable content, create a Component under Components.
4. Compose visual elements in Design and use Source for precise logic and styling.
5. Save, check the Page in Design, then run Build and complete runtime acceptance.

When creating a Page, you can choose both its canvas size and background color. The background defaults to white. Enabling Follow theme omits the background style so the Page uses the active theme or host surface.

Select Set as Home Page from a Page context menu to choose what the Runtime root and Player open by default.

Find Components faster

The Design Palette combines App-defined Components with Components from every installed package and groups them by purpose by default. Each row shows its source. Use the filter button to combine category, source, and tag filters. Search also covers descriptions, categories, tags, package ids, and directories, so queries such as “form”, “date”, “grid”, or “Fluent UI” work without knowing an exact Component name. Entering a query or enabling a filter switches the Palette to one flat result list instead of another nested tree.

Categories and tags come from each Component declaration; they are not guessed from its name. An App Component without a category appears explicitly under Uncategorized. To classify an App Component, see Advanced: Page source development.

Use the complete Siemens iX component set

Install the main package for the complete industrial application shell, navigation, forms, date/time controls, feedback, data display, Chat, Upload, and Grid. Add the separate charts package when charts are required:

theseus package add theseus.ix@1.0.0
theseus package add theseus.ix-charts@1.0.1

theseus.ix exposes all 121 Web Components from iX 5.2.1, the complete iX icon set, and an iX-themed AG Grid Community wrapper. theseus.ix-charts provides a generic ECharts entry plus line, area, trend, bar, pie, donut, gauge, and scatter charts. Both packages compile their browser dependencies into the feature-package release; an App does not need npm or node_modules.

<script lang="ts">
  import IxApplication from "@theseus/ix/IxApplication";
  import IxApplicationHeader from "@theseus/ix/IxApplicationHeader";
  import IxContent from "@theseus/ix/IxContent";
  import IxDatePicker from "@theseus/ix/IxDatePicker";
  import IxMenu from "@theseus/ix/IxMenu";
  import IxTheme from "@theseus/ix/IxTheme";
</script>

<IxTheme colorSchema="light">
  <IxApplication theme="classic" colorSchema="light">
    <IxApplicationHeader slot="application-header" name="Production" />
    <IxMenu slot="menu" />
    <IxContent><IxDatePicker singleSelection /></IxContent>
  </IxApplication>
</IxTheme>

Each iX tag uses its PascalCase export, for example ix-date-picker becomes IxDatePicker. Default text, nested elements, and named-slot children can be written directly in the Inspector's Content section; pass a named slot with the child element's slot attribute. Use bind:element={reference} when you need an iX element's public method. element is an underlying element instance handle, not a string property. The releases contain the upstream iX Classic light/dark styles and their embedded assets, but no separate Siemens Corporate Brand Theme or proprietary font files; use of Siemens names and trademarks remains subject to the applicable rights.

Use Fluent UI Web Components

Install the Fluent UI package when you need Fluent 2 foundation controls:

theseus package add theseus.fluent-ui@1.0.0

theseus.fluent-ui covers all 42 Custom Elements actually published by @fluentui/web-components 3.1.3 and adds FluentTheme for light, dark, system, and custom-token themes. All browser runtime dependencies are compiled into the feature package, so an App does not need npm or node_modules. The package does not include React components, the separate Fluent icon library, or Combobox and SplitButton, which are not published by this upstream version.

<script lang="ts">
  import FluentButton from "@theseus/fluent-ui/FluentButton";
  import FluentTextInput from "@theseus/fluent-ui/FluentTextInput";
  import FluentTheme from "@theseus/fluent-ui/FluentTheme";

  let name = $state("");
</script>

<FluentTheme appearance="system">
  <FluentTextInput bind:value={name} placeholder="Name" />
  <FluentButton appearance="primary" onclick={() => console.log(name)}>
    Submit
  </FluentButton>
</FluentTheme>

Each Fluent tag uses its PascalCase export, for example fluent-text-input becomes FluentTextInput. Compose default content and named slots directly, using the child element's slot attribute for a named slot. Common input events are available through properties such as oninput, onchange, and onclick. Use bind:element={reference} to call public methods on the underlying Custom Element.

Design, Preview, and Source

Mode	Purpose
Design	Edit geometry, properties, styles, and events; hold Alt to interact with local controls
Preview	Interact directly; real calls require Run / Debug and failures appear in Console
Source	Edit structure, styles, local state, and event logic

Design never executes Runtime Object or Query calls. Object methods return explicit typed design values; Queries return status 0 (not executed). Design does not log skipped calls. Preview supports direct page interaction: Object / Query calls reject in Stopped and log errors to Console; real calls require completed Run / Debug initialization. Preview never implicitly Builds, Deploys, or starts Runtime. Complete device acceptance still uses the runtime Page.

App Hub Design supports local controls directly, with zoom, pan, and Fit View. Editor Design keeps selection and editing as its default. Both use local source assets and remain independent of target deployment. Content becomes visible after mounting and initial Fit.

Design a Page

1. Define the information hierarchy

Start with the operator's three recurring questions: What is the current state? What can I do next? How do I recover from failure? Keep primary state and actions on the first screen, and put diagnostics or infrequent settings in a secondary area or separate Page.

2. Build the visual structure in Design

• Drag a Component from an installed package or the App's own .qpc from the Palette.
• Select an element and use the right Inspector for Geometry, Layout, Spacing, Typography, Appearance, events, and bindings.
• Use multi-select, alignment, and distribution tools for consistent spacing.
• Double-click an App Component instance to open its .qpc; nested Components can be opened the same way.
• Use undo / redo to inspect each visual change, then save before switching to Design.

Repeated elements generated from an array can be hovered and selected individually. Hold Shift, Cmd (macOS), or Ctrl (Windows / Linux) to add or remove selections, or drag a marquee to select several. They still share one template: property edits and deletion affect the repeated group. Multi-selection cannot write conflicting positions or sizes to the same template.

A Page has one top-level visual root. A normal canvas gives that root the Page dimensions and background, then arranges content inside it. Do not infer real dimensions from editor zoom; Design and runtime all use the Page's own CSS layout.

Runtime pages and Player scale the complete Page uniformly to the largest size that fits the window, with no extra padding. At least one pair of opposite edges meets the window edges; the other axis is centered, without cropping or stretching. Resizing the window updates the fit automatically. The root defines the Page dimensions, and internal scroll regions retain their own layout. Design’s manual zoom does not carry over to runtime.

3. Reuse consistent behavior with Components

Extract a repeated visual unit into a Component when it should be maintained consistently. Give it clear inputs, user actions, and default styling, then reuse it across Pages. Role controls are in the Inspector's Permissions section. Keep account switching accessible, and remember that hiding UI never replaces authorization for a sensitive operation.

Ordinary reuse can stay in Design and Inspector. When you need to code Component inputs, events, the root element, or permission forwarding, continue with Advanced: Page source development.

Connect App capabilities

Objects and QG

A Page can call Objects configured in the current App. Use Source completion to choose the exact instance and method instead of copying device addresses or protocol details into the Page. Equipment sequences, waits, timeouts, and recovery branches belong in QG or a business capability; the Page should express intent and display the result.

Design does not perform real Object calls. Start and Debug calls depend on the current Runtime target and its state, so accept at least the normal, timeout / fault, and repeated-action paths.

Queries, Variables, and navigation

Maintain App-level Queries, Variables, and navigation centrally in Settings, then use them through Page bindings or configured capabilities. Do not duplicate external-service addresses and authentication across Pages. Use the project's approved persistence capability for values that must survive a restart rather than temporary Page state.

Localization

Maintain locales and messages in Settings → I18n, then use the corresponding text in the Page. Before delivery, verify the default locale, switched layouts, long-text truncation, and missing-message behavior.

Images and 3D models

Place images, fonts, GLB / GLTF files, and other read-only assets under assets/**. Use workspace-root-relative paths such as assets/logo.png or assets/models/cell.glb. The same path works in Design and Runtime. Mutable runtime data must not be written back into assets/**.

Current App user

An App user represents the operator for role-controlled content inside a Page. Add the CurrentUser Component when a Page should display or switch the current operator, and keep it outside any restricted region that could hide itself. See App users, roles, and runtime-page sign-in for configuration and Advanced: Page source development for source usage.

Recommended path from editing to runtime

1. Complete the change in Design and Source, then save it.
2. Review live markers for the current file and resolve obvious Page-source and type issues.
3. Open Design and check visuals, input, navigation, and interactions without equipment side effects.
4. Stop the current runtime instance, then run Build. Resolve errors from this Build in Problems.
5. Use Start for normal acceptance or Debug for breakpoints and failure paths.
6. From the Runtime root or Player, verify the home Page, sign-in, display resolution, and long-running behavior.

Live editor markers and Problems are different results: live markers follow the open document, while Problems contains diagnostics for saved project files from the latest Build.

When an Object type is unavailable, its references show errors without blocking design and editing of unrelated Pages. In Design, a component rendering failure displays an error at that component while the surrounding layout remains editable; a failure during Page initialization displays a Page error. All Object errors must be resolved before Build can succeed.

Acceptance checklist

• Page names are unique, and the configured home entry refers to an existing .qp.
• Dimensions, text, colors, and interaction agree across Design and Runtime.
• Reused .qpc instances have correct props, events, and styles on every Page.
• Keyboard use, focus, contrast, touch targets, and each supported locale have been checked.
• Assets use assets/... paths and are present in the target environment.
• Object calls show loading, success, failure, and recovery without presenting a fault as a normal result.
• CurrentUser shows the App user, and role branches are accepted on a real runtime Page.
• After Build succeeds, Start / Debug and Player use the same deployed version.

Common issues

Online documentation or an old project shows another Page extension

Current Pages use only .qp, and reusable Components use only .qpc. Do not create compatibility copies or continue in an old format. Move the content into the current files and update every reference.

Runtime content is old or Build is required

Save the source, verify the selected target, Stop, Build, and Start / Debug. Design uses source source; runtime Pages use the deployed version.

Object calls do not execute in Design

This is expected. Design skips Object / Query calls without logging them. Use Preview or a runtime Page after explicit Start / Debug for real business validation.