====== Domain Design ======

In the bar: **"Domain" → "Design"**. One screen that paints the **whole domain** — the ordinary pages and the task page in the game alike.

Styling used to be built by overriding the engine's rules one at a time: a long list of selectors in the domain's css, each with a colour of its own. Now there are two simpler layers underneath — the **theme** and the **tokens** — and your own css goes on top of them rather than instead of them.

===== The Theme =====

A theme is a ready-made set of values that your css is laid over. It is picked on the **"Domain settings"** tab, in the **"Theme"** row.

  * **No theme** — the way the domain has always looked.
  * **Green**
  * **Dark Purple**
  * **Dark Radix**
  * **Light Radix**

**A theme paints the domain as a whole, not only the game.** One and the same set describes the site, the game, the light mode and the dark one — so a domain cannot end up with a sand-coloured day and a cyberpunk night.

A theme is a **delta, not a full set**: whatever it does not name stays as the engine has it. So "No theme" is not "broken" but "everything by default".

===== How the Studio Is Laid Out =====

{{ :admin_main:domain_design_studio_en.png?800 |The design studio: screens and slots on top, the editor on the left, the showcase on the right}}

**The top row — the screens:**

  * **"Menu"** — the row of links under the header, on every page of the site.
  * **"Site"** — ordinary pages: the main one, the list of games, the profile.
  * **"Game"** — the task page. A theme of its own for light and for dark.
  * **"Domain settings"** — the title, the start page and the choice of theme.

**The second row — the slots**, that is, the fields you actually write into:

^ Screen ^ Slots ^
| Menu | Menu (HTML) |
| Site | Header (HTML), Footer (HTML), CSS |
| Game | Header in the game (HTML), CSS: light theme, CSS: dark theme |

Under the tabs there is a line about what the open slot is laid over, and next to every **css** slot a "Theme tokens" link.

**On the left the editor, on the right the showcase.** The showcase is **not a live page of the domain** but a sample built by the studio: for "Site" it is the menu, a basic page, the list of games, the statistics, the codes map and the answers log (the showcase has a table of contents of its own); for "Game" it is the task container, the inventory, a spoiler and an alert. This is deliberate: a draft no longer lands on real pages where anyone could run into it.

The showcase has switches of its own: **"Light" / "Dark"** (on the "Game" screen only), full width or **as on a phone**, and **redraw**.

> **css is applied on every keystroke**, with no reload of the showcase. HTML cannot do that — the server builds it, and the showcase redraws after a pause once you stop typing.

===== The Tokens =====

A token is a name for a colour (or a size) that the engine uses in all of its rules: ''--qeng-body-bg'', ''--qeng-surface-bg'', ''--qeng-accent'' and a few hundred more. Set the name and the colour spreads across every rule by itself — no selector has to be overridden:

<code CSS>
:root {
  --qeng-body-bg: #050505;
}
</code>

The list opens by the **"Theme tokens"** link next to any css slot.

{{ :admin_main:domain_design_tokens_en.png?800 |"Theme tokens": the reference of names the engine paints by itself}}

  * The names are grouped, and the **palette** comes first — the few dozen the whole site is described with. It is usually enough: the roles of the screens take their colour from the palette and follow it. Open the other groups only when one single thing has to be led aside.
  * The swatch next to a name shows the colour **after** your css, not the default one — so you can see what you have already overridden.
  * Groups that do not apply to the open slot are hidden.
  * Some tokens are marked as the engine's own: nothing can override them, and they are not offered on any slot at all.

This is a **reference, not an input field**: you still edit css, the tokens are only listed here.

===== The Inspector and the Contrast Check =====

Above the showcase there is a contrast bar: **"Contrast: OK (N elements)"** or "N contrast problems", the "◀ ▶" arrows to walk the problems, and **"Show all"**. Its thresholds are deliberately softer than WCAG — this is a hunt for the plainly unreadable, not an accessibility audit.

The **"🔍 Inspector"** button turns on element picking: you click anything in the showcase and see **which layer** the rule came from:

  * 📄 on the page (inline and ''<style>''),
  * 🌐 the domain design (your css),
  * 🎨 the theme,
  * ⚙️ the base qeng design (the engine),
  * 🅱️ Bootstrap.

The **"➕ To the editor"** button inserts the selector into the open slot. On an html slot it does not work — there is nowhere to put a rule.

> **Both tools work on a css slot only.** While an html slot is open, it is your html running in the showcase, and it is served in a sandbox; the inspector closes itself and the contrast bar goes quiet. This is not a fault but a safety boundary.

===== The Draft, Saving, the History =====

  * **The draft lives in your browser.** Come back to the page and the studio asks: "An unsaved draft was found from … Restore it?". If a slot was changed on the server meanwhile, it names which one and asks you to look at it in the list of changes.
  * **"Save"** first shows the **"Changes before saving"** window — line by line, for every changed slot. The same window as in the task editor.
  * **"History (N)"** — up to **30** of the last saved versions, labelled with the date and the login of whoever saved it.
  * Limits: an html slot — **64 KB**, a css file — **512 KB**. If it does not fit, the studio says what and by how much.

> **Broke the layout so badly that the page will not open?** Add **''?safe''** to the address — the domain shows up with no styling of its own and no theme, and the studio opens.

===== What a Theme Does Not Paint =====

**Admin pages and the editors on their own pages take no domain styling** — no theme, no css of yours, no header of yours. They look the same on every domain; there is no screen for them in the studio at all.

Two subtleties that are easiest to trip over:

  * **The admin bar over the site and game pages //is// painted.** It is the admin //pages// that take no styling, not the bar itself.
  * **The task editor takes the theme only when embedded** — when it is open on the game page itself. On its own separate page it is always light.

===== Day and Night in the Game =====

The light and dark mode in a game is chosen by the **player** — with the **"Dark mode"** switch in the game menu. It is not the domain's theme and is not tied to it: a theme describes both modes at once.

Technically the mode is an attribute on the root element of the page:

<code CSS>
:root[data-theme="dark"]  { /* night */ }
:root[data-theme="light"] { /* day */ }
</code>

> **Only the game page sets the attribute.** On the pages of the site it is not there at all, so ''html:not([data-theme])'' means **a page of the site, not the day**. The rule for the day is written ''[data-theme="light"]''.

In the **domain's** css for the game you usually do not have to write this: the domain's light and dark themes live in **two separate slots**, and the engine links the right file itself.

If a theme has to be forced on one level, that is done by a task script: [[en:authors_main:task_editor:advanced:page_elements|Elements of the task page]].

===== See Also =====

  * [[en:admin_main:dark_example|A dark domain built out of rules]] — how it was done before themes; the example is still there.
  * [[en:admin_main:domain_menu|Configuring the domain menu]]
  * [[en:admin_main:domain_pages|Domain pages]]
  * [[en:admin_main:domain_localization|Domain translation]]