Current rules

Source

This page is published from docs/current-rules.md. Edit it there.

Binding guidance register, reviewed 2026-11-13 for DS-AUDIT phase 2, batch 1A. Start here when retained passages disagree. IDs are permanent; link to the subject ID rather than repeating a rule. Later owner decisions win. Rule 395 requires additive, dated corrections beside old passages; it does not permit rewriting history.

Authority is the SpaceWorks ledger handover/research/decisions-2026-10-18.md (number and full date below), with the public decision record. An implementation observation is evidence, not a new owner decision. Where no later geometry decision exists, the adopted brand spec remains the default; the auto decisions are stated explicitly below.

CR-THEME-01

Theme choices: Light, Dark and System. Light is the fallback. Respect a saved choice, cross-tab updates and a session choice when storage fails. System follows the device only when chosen by the visitor or configured as a space’s default look on public/member/display surfaces. A fixed choice ignores OS changes. Paint html.dark before first paint and update browser chrome with the painted theme.

Deciding authority: SW-364, 2026-11-13 (explicit light/dark/system implementation), later than the undated D11 prohibition; SW-204, 2026-11-07 (light default). Verified read-only against app lib/theme.ts, public/boot.js and ThemeChoice.tsx on 2026-11-13.

Occurrences: theming §§2–4 and checklist, brand D11, brand H.7, brand checklist row 21, UX user menu, lesson 29, product themes, SW-364, SW-204.

CR-STATUS-01

Small status marks keep their fills in both themes. Success = bg-success text-on-success; warn = bg-warn text-on-warn; info = bg-info text-on-info; emphasis = bg-emphasis text-on-emphasis. Do not turn these pastel marks into dark soft pills. A word is mandatory; an icon is optional. Accent remains bg-accent-soft text-accent-ink; danger remains bg-panel border-danger-line text-danger; neutral remains bg-surface border-line text-ink. “Solid in both themes” does not turn these three exceptions into filled action buttons. Large success/warn/info callouts use the solid fill in light and the named opaque soft fill plus tone ink in dark.

Deciding authority: SW-373, 2026-11-13 (current brand guidelines), corroborated by lesson 9’s app commit 6e60c20c4 and current components/ui/tones.ts. The D6/C dark-pill recipe predates this recorded small-mark/large-surface distinction; no separate owner SW-number is recorded for that implementation change.

Occurrences: brand D6, status matrix and domain words, lessons 9–12, UX P10, long-tail conventions, theming bright fills.

CR-RADIUS-01

Product controls use 10 px; cards/panels use 16 px; tags/status pills are fully round. Use the component role, not a radius measured on an inspiration board. The retained 6/8/10/12/16/20/full scale permits explicitly specified component variants; it does not change these defaults. Cards are flat. The documented shadow-overlay exception belongs only to floating popovers, menus, modals, drawers and toasts.

Deciding authority: SW-373, 2026-11-13, brand spec D8/E. Auto decision: retain those adopted brand defaults because no later owner switch to pill controls is recorded. The “owner may switch” sentence is conditional, not evidence of a switch.

Occurrences: brand D8, shape tokens and overlay exception, open control-radius item, UX measured scale, UX buttons, long-tail pill terminology.

CR-SIDEBAR-01

Sidebar: Citron in light, neutral #0B0B0B in dark, text-only navigation, filled teal current item with aria-current="page". Use the brand E product geometry: 256 px desktop width, 20 px inset, 44 px items and 4 px gaps. The measured 240–300 px widths, 264 px proposal, warm-grey active item and reference icons are research. Keep task grouping, route-aware disclosure, scrolling and responsive navigation behaviour from the UX spec. The user menu includes the theme choices in CR-THEME-01.

Deciding authority: SW-316, 2026-11-11 (neutral dark family); SW-373, 2026-11-13 (brand defaults). Auto decision: brand D9/E wins on visual geometry over the earlier measured reference; no later owner approval of the 264 px proposal is recorded.

Occurrences: brand D9, sidebar tokens, interaction states, brand E, logo sizes, icon rules, open sidebar item, UX P1, UX L1, UX sidebar IA, theming sidebar, lesson 30.

CR-TYPE-01

Three families, with explicit weights. Gilroy ships only Light 300 and ExtraBold 800: use 800 for display headings, 300 for deliberately light display text. Outfit 400–700 handles body/UI; use Outfit 600 for the documented page/panel/section heading roles and numbers. Unbounded 500–600 provides one short accent phrase per layout. Never request Gilroy 400/500/600/700 or synthesise a missing face. IDs/code in product UI use Outfit with tabular figures (and .code-text where specified), not a separate monospace family.

Deciding authority: SW-299, 2026-11-11, superseding earlier Gilroy arrangements; SW-220, 2026-11-09, for Outfit. The one-accent role is retained from the adopted brand spec.

Occurrences: brand D7, faces, CSS, scale and IDs, font migration, brand checklist rows 14–16, lessons 21–23, UX observed weights, README font changelog, SW-299.

CR-LOGO-01

Closed logo: four visible, solid flap regions, two orange and two green in both themes. Top-left and bottom-right stay green #006E63; top-right and bottom-left stay orange #FF7447, on both sides throughout movement. Reversed product geometry keeps the cream body and this flap palette. Explicit monochrome/forced-colours variants keep four separate regions in one colour. Retain static-rest fidelity, no holes, depth order and reduced-motion stills. SW-381’s one-orange-lid interpretation and face recolouring are historical.

Deciding authority: SW-389, 2026-11-13, superseding that part of SW-381. No change to the newly added public decision is made by this register.

Occurrences: motion Brand catalogue, lessons 39 and 40, lesson 40 at the end of the page, brand logo use, theming artwork, superseded SW-381 wording.

CR-DARK-01

Dark is one neutral black family: page #000000, surface/sidebar #0B0B0B, panel #141414, hover #1C1C1C, decorative line #2C2C2C; Cream text and Citron focus. No green-tinted dark page surfaces. Bright brand fills remain accents. A deliberately dark island on a light page may use Deep Ink; on an already dark page it rejoins the neutral black family. The old blanket “no black” rule is superseded. Tenant label derivation may use black as its documented final functional fallback.

Deciding authority: SW-316, 2026-11-11, superseding SW-225’s intermediate palette and the dark clauses of SW-275/300; brand H.5 records the preserved tenant-label fallback.

Occurrences: brand introduction, brand D1 and A token/CSS tables, brand tenant fallback, theming introduction/token layer, motion dark guide, lesson 1 and pairing table, README dark changelog, SW-316.

CR-CHART-01

Series are --chart-1 … --chart-5: teal #006E63, orange #FF7447, citron #DFFF8F, sky #B5CDFF, yellow #FFD447, identical in both themes. Contrast comes from --chart-edge (Deep Ink in light, Cream in dark): 1 px edge on filled marks and 4 px casing under 2 px lines. Retain stable identity mapping, dash patterns and meaningful labels. Danger is an explicit negative/error role, never an ordinary series. Old named series aliases and dull ink recipes are historical, not the current series API.

Deciding authority: SW-380, 2026-11-13.

Occurrences: theming palette, theming artwork/charts, lesson 13, brand migration chart rule, README old chart label, SW-380.

CR-MOTION-01

Use the shared motion defaults: fast/base/slow = 120/180/240 ms; standard/enter/exit curves = cubic-bezier(0.2,0,0,1) / cubic-bezier(0.16,1,0.3,1) / cubic-bezier(0.4,0,1,1). Use transform/opacity; ordinary hover is colour only. Interaction-path motion never blocks input beyond 240 ms. Theme reveal (720 ms), box opening (1600 ms), hover fold/open (600 + 1600 = 2200 ms) and loader loop (4400 ms) are named non-blocking exceptions. Logo hover/focus finishes once, does not restart in flight, and never runs on touch or under reduced motion. Tenant logos stay still. Use the box loader and a meaningful status label; reduced motion shows its still state. Kiosk/TV zero distances. Delight defaults on with the space’s opt-out; reduced motion takes precedence, including for theme switching.

Deciding authority: SW-51, 2026-10-20 (defaults); SW-322/323, 2026-11-11 (loader/motion); SW-364/367/376, 2026-11-13 (catalogue, full hover cycle, theme reveal). Ledger 399, 2026-11-13, adds symmetric choreography, token timing, interruptibility, focus/announcements and reduced-motion end states; named logo-cycle semantics remain as specified above.

Occurrences: motion defaults, motion rules and tokens, brand E, theming reveal, lessons 24–29, product loading/motion, long-tail loading, README historical one-shot description, SW-367, SW-376.

CR-OPACITY-01

Text is opaque. Use text-muted/--color-muted for secondary text, never text-ink/80 or rgb(var(--color-ink) / .8). Use named opaque *-soft roles for tinted backgrounds, never an alpha brand fill. Triplet storage enables compositing where explicitly permitted (for example a scrim); it grants no exception for translucent text. Temporary animation opacity does not define the resting text colour.

Deciding authority: SW-373, 2026-11-13, and adopted brand D5/B/H.1; implementation provenance and contrast rationale are recorded there. Rule 395, 2026-11-13, governs how the contradictory examples are retained.

Occurrences: brand D5, brand interaction states, migration bans, theming triplet explanation, theming component examples, product accessibility, lesson text rules.

CR-DISABLED-01

Disabled controls use explicit opaque states: bg-surface text-muted border-line, with hover/press effects suppressed. Use native disabled where supported; if aria-disabled is needed, also prevent activation. Explain what enables the action beside the control when it is not obvious. A disabled-opacity example or the old “allowed outside the button family” exception is not a current recipe. Read-only retains readable content and its label; it is not a disabled action.

Deciding authority: adopted brand B, reaffirmed by SW-373, 2026-11-13; DSA-015’s correction is additive under rule 395, 2026-11-13.

Occurrences: brand B, historical H.1 exception, UX button states, current theming example.

CR-RELEASE-01

Keep product, release and working-tree versions distinct. The design-system series is v2.0, independently of the SpaceWorks app 0.12.0. v2.0.0 was released 2026-11-13 (SW-382/386 and the supplied lane release record); local tag v2.0.0 is present. The fixes named by SW-389/390/405 are the v2.0.1 checkpoint, whose intended VERSION is 2.0.1. Ledger 397, 2026-11-13, sets the larger phase-2 additions to v2.1.0. Neither a target nor a VERSION edit proves publication.

Observed at 2026-11-13, batch 1A baseline: the root VERSION actually reads 2.0.0, and git tag --list includes v2.0.0. The requested 2.0.1 checkpoint value is therefore pending the owning release lane; this batch cannot edit VERSION. No live GitHub release query was made. Release status above is attributed to the owner/lane record, not a new remote observation. Refresh this observation additively after integration.

Deciding authority: SW-382/386/389/390, 2026-11-13, ledger 397 and the batch brief. Do not relabel app release numbers, asset paths or dated decision titles.

Occurrences: README version, README token-sync heading, delivery static-site status, delivery status table, delivery gaps, SW-382, SW-389, SW-405.

CR-SCOPE-01

Canonical product guidance, documentation presentation and historical research have different scope. Apply this register and the adopted brand roles to product UI. Reference-board pixel measurements, ASCII wireframes and earlier proposed values remain research even when an old heading says “use these”. Documentation chrome or an animation demonstration does not grant a product exception. Literal 0.12.0 app references stay valid; the system is v2.0. The current brand book is v2 (50 pages); v1 (17 pages) remains a historical download. Typography has three families. Stale labels in files outside batch 1A must be clarified by their owning integration batch without deleting old content.

Deciding authority: SW-373/382/385, 2026-11-13, DS-5 (2026-10-15 and 2026-10-19), and rule 395, 2026-11-13. Geometry precedence is the explicit auto decision in CR-RADIUS-01/CR-SIDEBAR-01, not a newly invented owner approval.

Occurrences: brand source statement, brand measured mock, brand open-items heading, UX measured scale, UX pending-data heading, long-tail research status, README contents, historical SW-366.

CR-CONTENT-01

Clear, warm, specific and truthful. Use the voice and content guide, British English, sentence case and action labels that name the result. No fake Undo for evidence, handovers, payments or other audited records. A correction/refund/reversal is a new authorised operation with its own record; show the actual scope and consequence. Distinguish empty, filtered-empty, loading, offline queued, partial failure and confirmed success. Keep identifiers and exact evidence available without making an ID the primary label.

Deciding authority: SW-235, 2026-11-10, SW-373/405, 2026-11-13, and the retained UX P30 safety contract. DSA-026 supplies the expanded writing patterns, not new backend capabilities.

Occurrences: UX microcopy, UX Undo/confirmation, long-tail copy conventions, product language, product landing/docs rule, brand checklist row 19.

CR-DELIVERY-01

Delivery tables are dated observations; pipeline proposals are rules, not work authorised in this batch. SW-386, 2026-11-13, explicitly defers adding workflows, CODEOWNERS or branch-protection changes. SW-387, 2026-11-13, records maintainer-only main/dev protection without new required checks. Retain the tables, but read their implementation claims at the stated observation date. The retired SpaceWorks-Docs site is not the current documentation architecture: SW-405, 2026-11-13, puts feature docs in each product and has native apps link to the hub. Keep product-rules §12.1 and public SW-405 as supplied.

Occurrences: delivery general rules, static sites, status table, gap proposals and checklist, product CI/CD rule, per-product snapshot, product §12.1.