How to record a decision

Add every new design decision here, in the same change that makes it, so the reason is written down while people still remember it.

Format. Copy an existing entry and keep these fields, in this order:

### SW-nnn or DS-n — Short title
- **Date:** day and month (all dates are in the current year; add the year if not)
- **Decision:** one or two plain sentences. What is now true.
- **Why:** the reason. This is the point of the file. If you do not know the reason, write
  "Reason not recorded" instead of guessing.
- **Status:** current, or "superseded by SW-xxx / DS-n", or "partly superseded by ...".
- **Implemented in:** design repo paths, and app paths if the app changed too.

Numbering.

• A decision that is also in the SpaceWorks decisions ledger keeps its ledger number with the prefix SW-, so the two files can be cross-referenced.
• A decision that belongs only to this design repo and has no ledger number is numbered DS-1, DS-2, …, continuing from the highest DS number in this file (the next is DS-10). DS numbers are never reused.
• Also add a row to the Index and update the count.

Rules.

• Always record the reason, in plain English. Quote the owner where the words explain the choice.
• Never delete or rewrite a decision. When one is replaced, change its status to “superseded by …” and list it under Superseded decisions with what replaced it and why.
• Explain any internal word the first time (“ledger”, “lane”, “token”) in one short phrase.
• No private data: no emails, secrets or personal names (the GitHub organisation name is fine).
• Prefer the ledger’s own words for the reason. If the reason is only in a commit message or a chat, copy the essential sentence into the entry.
• A change that adds or changes a rule also updates the matching doc (docs/ui-brand-spec.md, docs/motion.md, docs/theming.md, docs/product-rules.md) in the same pull request.

SW-389 — Four visible flaps keep their own colours when shut

• Date: 13 November
• Decision: In both themes the closed logo lid shows all four flap regions: top-left and bottom-right green (#006E63), top-right and bottom-left orange (#FF7447). Each flap keeps that colour on both sides throughout the animation. Explicit mono and forced-colours variants keep four separate regions in one colour.
• Why: The owner asked for “in closed also make sure 2 orange and 2 green”. This supersedes SW-381’s one-orange-lid interpretation and its cream-only reversed lid. Hiding two flaps or recolouring a reverse face obscures the mark’s four-flap arrangement.
• Status: current; supersedes SW-381’s closed-lid colour rule. Its no-hole, depth-order, static-rest and reduced-motion rules remain current. Ships with Design System v2.0.1 and SpaceWorks 0.12.0.
• Implemented in: motion/box-open/ (generated CSS, markup, demo and React sources), scripts/check-box-frames.mjs; app frontend/src/components/boxOpen/, components/brand/ and the generated splash block in frontend/index.html. The regular reversed product mark retains the reversed geometry and cream body, using the same approved flap palette as the light mark; explicit mono is unchanged.

Index addition: SW-389 — Four visible flaps keep their own colours when shut.

SW-405 — Every project has its own landing page and feature docs, built from this system

• Date: 13 November
• Decision: Every Space Works project except the Android and iOS apps has its own landing page — with its GitHub repository, release and install, docs, licence and changelog links — and its own feature docs inside the product (one page per area, sources in the repository’s docs/), both built from this design system’s rules, tokens, components, logo, motion and voice. The native apps link to the hub’s landing page and docs. The separate SpaceWorks-Docs site is retired.
• Why: The owner asked that every project present itself the way SpaceWorks does and take everything from the design system, so the family reads as one and the rules cannot drift per project.
• Status: current. Rule text: product rules §12.1.

SW-412 — Orange outer flaps open in order; black-and-white returns to v2.0.0

• Date: 13 November
• Decision: For coloured marks on light grounds, the orange top-right and bottom-left outer flaps close over the hidden green top-left and bottom-right pair. Open them one after the other, then each green flap, then one small damped settle to the exact static logo, with no decorative bursts. Close in exact reverse. Preserve the 1600 ms once, 2200 ms hover and 4400 ms loop budgets and stepped matrices. The owner’s immediate correction restores dark/reversed, mono and forced-colour marks to the v2.0.0 black-and-white family, with no orange or green. This supersedes SW-389’s visible-quarter closed lid for coloured marks and its coloured reversed product mark.
• Why: A real box closes its outer pair over its inner pair; separate turns preserve the panels’ physical order. Keeping a released black-and-white generator path prevents colour or choreography regressions in dark marks and button spinners when the coloured animation changes.
• Status: implemented at the app generator and exported to motion/box-open/; preserves SW-381’s solid lid, no-hole cap, overlap order, static rest and reduced-motion behavior. Snapshot hashes pin the released CSS and markup; frame tests cover the changed sequence. Browser QA and preview/PDF regeneration remain release-orchestrator steps.

Index addition: SW-412 — Orange outer flaps open in order; black-and-white returns to v2.0.0.

SW-424 — Entry points follow the data

• Date: 13 November
• Decision: Every entry point in every product decides from what exists: nothing (or backend unreachable) → introduction; exactly one item → open it directly; several → list. The product’s links (docs, GitHub, features, the full list, the introduction) stay one click away wherever it lands, and sign-in returns to the same action with the visitor’s choices kept. In SpaceWorks: / is the landing with no public makerspace, the makerspace’s page with one, the space list with several; the landing stays at /about.
• Why: The owner asked for the SpaceWorks homepage to behave this way, then: “generalize and make a rule”.
• Status: current. Rule text: product rules §12.2.

SW-433 — Release images are the frontend and the backend only

• Date: 13 November
• Decision: Every product release publishes exactly two images (frontend and backend, amd64 + arm64). Postgres, Redis, object storage, the proxy and other infrastructure are pinned upstream images pulled by the install script as setup decides; workers, schedulers and jobs run from the backend image. No all-in-one image.
• Why: The owner removed the SpaceWorks all-in-one image from the registry and asked for this to be a rule.
• Status: current. Rule text: product rules §2.5.

SW-436 — Every product README follows one structure

• Date: 13 November
• Decision: Every product README follows one order, modelled on the SpaceWorks hub README: banner (light/dark <picture>), a centred block with the landing page’s promise, brand-coloured badges and quick links, intro, “A look around” in both themes, quickstart, who it is for, what you can do, integrations, modules, install options and hosting, architecture, API, roles and access, design system, documentation, roadmap, contributing and licence. No stale versions or dead links; native apps and the design-system repository adapt it.
• Why: The owner asked for the product README structure to be a rule, like the landing page and entry points.
• Status: current. Rule text: product rules §12.3.

Part of Design decisions, with the reason for each, published from docs/decisions.md. Edit it there.