App settings¶
App settings apply to every item of an application key. They live in the studio side panel, under the application key.
Settings¶
| Setting | Effect |
|---|---|
| Application key | Names the application. Default demo. Items, bundles and settings are scoped to it |
| Use the open site | Requests access to the current tab's origin and adds it to the first environment (creating dev if there is none) |
| Help bubble: enabled | Shows or hides the help button |
| Help bubble: position | bottom-right, bottom-left, top-right or top-left. The top positions draw a compact header button |
| Help bubble: offset | Optional x and y pixels that move the bubble in from its corner, to clear controls on the host page |
| Announcements shown at once | maxAnnouncements: at most this many announcements show together, the rest queue until one is dismissed. Unset shows all |
| Theme variables | One --wp-* variable per line; see below |
The schema also holds testIdAttributes, textCapture, themeOverride and conditionSourceFields. They are not in the side-panel form; set them by importing a bundle.
CSS variables¶
The player picks up colours and fonts from the host page, and lets you override them. Only these keys are accepted:
--wp-font, --wp-font-size, --wp-text, --wp-muted, --wp-surface, --wp-border, --wp-primary, --wp-on-primary, --wp-warning, --wp-success, --wp-radius, --wp-shadow, --wp-tooltip-width.
Values are rejected if they contain url(, expression, @import, ;, {, }, <, >, a backslash, a comment, or javascript:, or if they exceed 200 characters. They are sanitised again at render time.
Preview¶
Under the theme variables box the studio shows a preview: a real tooltip, modal and banner drawn with the variables as you type them. Nothing is saved until you press Save theme variables, and a variable the studio will reject is listed above the preview while the rest still apply.
The switch above the preview chooses the base the variables sit on:
| Choice | Base |
|---|---|
| Light | The stock light theme |
| Dark | The stock dark theme |
| Match the open page | The colours and font Guidepost reads from the browser tab you are working on, plus the application's saved theme override. Needs access to that site; without it the preview uses light and says so |
Under the box, a line lists every variable you can set. Insert primary, surface, text, radius and font add that variable with the value the preview uses now, or replace its line if it is already there, so you can edit a real value instead of guessing a name.
How the page theme is read¶
The player reads the look of the page from what the user sees: the elements under the middle of the window, their translucent backgrounds composited down to the first solid colour, then the page canvas (the html background, else the body background, else white, or the dark canvas when the page declares color-scheme for dark and the system prefers it). A white wrapper on a transparent body, or a light app behind a dark body, therefore reads as light. It reads again when the page finishes loading, when the system colour scheme changes, and when the class or style of html, body or the app root changes.
Worked example¶
Match a corporate blue and make the corners square:
--wp-primary: #0b5cad
--wp-on-primary: #ffffff
--wp-radius: 2px
Save, then reload the page so the player reads the new settings.
Gotchas¶
- Unknown or unsafe variables are dropped silently by the player. The studio warns about rejected keys.
- The preview is a stand-in page, not your application. It shows the colours, radius and font; positions on the real page can differ. Use Preview on page on a content item to see it in place.
- A page that shows its look only through a background image or gradient reads as the colour behind it. Set
--wp-surfaceyourself in that case. - Contrast is your responsibility when you override colours. Automatic theme extraction nudges text colours to reach 4.5:1 contrast on the host surface; explicit overrides are used as given.