Constitution

General functions requirements.

Every screen should be optimiezd for mobile screens.

Technical requirements

Try to create and reuse components if possible.

If there is a requirement to upload and use file, reuse file folder component, suggesting user to add file to newly created or existing file folder, and then attaching file folder to the designed component. All uploaded files should be access via file foldeer component.

If a file is upload it should be stored within folder specifications/<specification id>/ folder. All files stored should be assigned to an organition and stored in a folder associated with a tool this file is used in.

UI & layout guidelines

- there should be two layouts light and dark available with switch in user dropdown menu under its avatar or picture.

Icons — one shared set, never emoji

- **Never use emoji or Unicode symbols as UI glyphs** (▶ ✏️ 🗑 ☁️ ⛶ ✕ ＋ ↺ …).

They render differently on every platform, ignore the light/dark theme, cannot

take a brand colour and carry no accessible name.

- Use the shared keyed line-icon set, `shared/ui-icons.ts`

(`UiIconService.icon(key, size)`): 24×24 grid, `fill:none; stroke:currentColor;

stroke-width≈1.7; round caps/joins`. Add a new key there rather than inlining

an `

(`play` = open/run, `pencil` = edit, `copy` = duplicate, `trash` = delete,

`restore` = restore, `chart` = report, `present` = present/host, `qr`, `link`).

- Render into a span marked `aria-hidden="true"`; the *button* carries the

meaning through its label, or through `title` + `aria-label` when icon-only.

Icons injected via `[innerHTML]` never get the component's

emulated-encapsulation attribute, so size them with the `size` argument (which

writes real `width`/`height` attributes), never with component CSS.

- Emoji are still fine as **content** — game and template data, story cubes,

quiz answers, marketing copy — just not as interface chrome.

List cards — one primary action, the rest behind "⋯"

- **Exactly one primary button** (`btn btn--primary`) — the thing the teacher

came to do (Open / Run / Launch / Report).

- **At most one secondary** (`btn btn--ghost`), and only when it is genuinely

frequent (Events: *Launch*; Boards: *Share*; Quizzes: *Edit*).

Buttons and labels

- Label + icon, in that order of importance: the icon supports the label, it

does not replace it. Icon-only buttons need `title` **and** `aria-label`.

- Keep destructive wording explicit (*Delete permanently*) and always confirm

through `ConfirmService` with `danger: true`.

- Page headers get at most one primary action (usually "New …"); secondary

links stay ghost.

- **Floating docks, not chrome bars.** Group controls into compact floating

panels over the workspace — a card background (`--card`), a hairline border

(`--border`), a soft shadow (`--shadow-lg`) and ~14px radius. Split concerns

into distinct docks instead of one crowded bar: e.g. creation tools in a left

vertical dock, properties + view controls in a bottom-centre bar. Use hairline

`--border` dividers between logical groups.

- **Monochrome line icons — never emoji.** Toolbar, menu and action-button

glyphs must be inline SVG line-icons on a shared 24×24 grid

(`fill:none; stroke:currentColor; stroke-width≈1.7; round caps/joins`). Do not

use emoji or Unicode symbols (✏️ ▭ ➜ 🗑 …) as UI icons — they render

inconsistently across platforms and themes. Keep one keyed icon set per

surface and reference glyphs by key.

- Icons injected via `[innerHTML]` do not receive the component's emulated-

encapsulation attribute, so size them with explicit `width`/`height`

**attributes** on the `

`aria-hidden="true"` and give its button an `aria-label` and `title`.

- **States use tint, not solid fill.** Idle buttons are transparent; hover uses

a soft surface tint (`--surface-2`); the active/selected state uses a light

brand tint with a brand-coloured glyph

(`color-mix(in srgb, var(--brand) ~15%, transparent)` + `color: var(--brand)`),

not a heavy solid fill. Declare a solid fallback before any `color-mix`.

- **Theme tokens only.** Never hardcode colours; use the design tokens

(`--bg, --surface-2, --card, --border, --text, --text-muted, --brand,

--brand-dark, --danger, --shadow, --shadow-lg`) so light and dark themes both

work.

- **Centred bars need `width: max-content`.** A bar pinned with

`left:50%; transform:translateX(-50%)` has its shrink-to-fit width capped at

half the viewport; without `width: max-content` its single-line content wraps

and leaves dead space at the ends. Reset to `width:auto` in mobile overrides.

- **Accessibility.** Toolbars use `role="toolbar"` with an `aria-label`; toggle

buttons expose `aria-pressed`; every icon button has both `title` and

`aria-label`; honour `prefers-reduced-motion`. Must pass AXE and WCAG AA

(contrast, focus management).

- **Mobile.** Consistent with the mobile rule above, docks collapse into

full-width, horizontally-scrollable strips; no control bar may overflow the

viewport horizontally.

Exemptions