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.

2.1 Internationalisation

• The UI supports Polish (pl) and English (en). English is the default and fallback.
• All UI strings live in translation files; no hardcoded user-facing text in templates or TypeScript.
• Language is resolved: URL param ?lang= → user profile preference → navigator.language → en. Persisted in the user profile for signed-in users, in localStorage otherwise.
• Specification content is not translated by the system. Each specification declares its own content language (contentLanguage, ISO 639-1) which is used for filtering and hreflang.
• Dates, numbers and relative times use the active locale.

2.2 Accessibility

• WCAG 2.2 level AA across all pages.
• Full keyboard operability; visible focus indicators; logical tab order; skip-to-content link.
• Correct landmark roles and a single <h1> per page.
• Colour contrast ≥ 4.5:1 for text, ≥ 3:1 for UI components and graphics.
• All images require alt text; screenshot upload requires an alt text field before saving.
• Live regions announce async results (save, publish, copy, download).
• Respect prefers-reduced-motion and prefers-color-scheme.
• No functionality depends on hover or pointer only.

2.3 Performance

• Public specification pages are server-side rendered and indexable.
• Lighthouse targets on public pages: Performance ≥ 90, Accessibility ≥ 95, Best Practices ≥ 95, SEO ≥ 95 (mobile).
• Largest Contentful Paint ≤ 2.5 s on a 4G connection.
• Editor and diff viewer are lazy-loaded route chunks.
• Initial JS payload of the landing page ≤ 200 kB gzipped.

2.4 Security & privacy

• Authentication only through Firebase Auth with Google provider.
• Authorisation enforced in Firestore Security Rules and Storage Rules, not only in the UI. The UI hides what the rules forbid; the rules are the boundary.
• Never trust client-supplied counters, ownership fields or timestamps — they are set by Cloud Functions or rules.
• Personal data stored: Google uid, display name, avatar URL, e-mail, chosen handle, locale. Nothing else.
• GDPR: account deletion removes the user profile and anonymises authorship on published public specifications (Deleted user), or deletes them if the user requests removal of content. Data export available on request via contact form.
• Cookies: only essential (auth session, language). No third-party analytics cookies. If analytics is enabled it must be cookieless and IP-anonymised.
• All Cloud Function endpoints validate input with a schema and enforce rate limits.

2.5 Code quality

• Angular standalone components, signals for local state, OnPush change detection everywhere.
• Strict TypeScript (strict: true, noUncheckedIndexedAccess: true), no any in application code.
• Feature-first folder structure (§12.2). Data access only through typed repository services — components never touch Firestore SDK directly.
• Unit tests for services, guards, pipes and diff logic. E2E tests for the critical paths in §15.
• Every route has a title and meta description set through Angular's Title/Meta services.

---

3. Glossary

Term	Definition
Specification	The top-level content unit. Owned by a user, has a slug, metadata, articles and versions.
Article	One markdown document inside a specification.
README	Mandatory article of type README, the landing content of a specification, contains screenshots.
CONSTITUTION	Optional article of type CONSTITUTION holding general/cross-cutting requirements.
Structure mode	Whether articles are arranged as steps (implementation order) or modules (functional decomposition).
Draft (working copy)	The mutable current content of a specification, visible only to the owner and collaborators.
Version	An immutable snapshot of all articles, published with a semantic version number.
Visibility	public or private.
Stage	draft or production. Indicates maturity of the specification, independent of visibility.
Fork (duplicate)	A copy of a specification into another user's account, keeping attribution to the source.
Bundle	The downloadable ZIP archive of a specification version.
Handle	Unique, URL-safe user identifier, e.g. @mzmigrodzki.

---