M1Durations and curves are tokens

Every move uses a token; nothing types a number. Scripts read the same values from window.rsMotion() (or motion() in src/lib/motion-read.mjs outside the Shell).

Retired: --dur-pulse (the fault pulse), --dur-blink (rack link lights), --dur-fill (bars filling to their value), and every loop on a working page.

Each look sets its own tempo with these tokens (motion.css), so changing the look changes its motion as well as its colour: Studio is warm and calm (the values above); Enterprise is crisp (about a fifth shorter, a tighter curve and spring, a smaller press); Playful is a little livelier (a little longer, a deeper press, still no overshoot); High contrast moves as little as it can (short fades, no press, no stagger); the Drawing set’s lines draw on.

• Why one rhythm reads as one system, and one edit retunes it.
• Do transition: background-color var(--dur-hover) var(--ease-settle); an exit on --ease-exit.
• Don’t transition: all .3s ease, or a number typed into a script.

M2Five moves: persist, enter, exit, state, transform

A thing on both views moves and resizes into its new place (persist, --dur-morph or --dur-page). A new thing grows from nothing at its own centre, one beat (--stagger) after the moving ones start (enter, --dur-enter). A leaving thing shrinks to its own centre, quickly, on --ease-exit, and takes no clicks (exit, --dur-exit). A change of colour, shape or status eases in place, once (state, --dur-state). A container becomes the next container: the clicked shape’s box tweens to the destination’s picture box while the content cross-fades inside it (transform, --dur-page for a card to its page, --dur-zoom between zoom levels, --spring-settle when scripted).

• Why people see what moved, arrived and left without reading.
• Do give a shared thing the same key on both views (data-vk, data-k, a port id); mark a card’s picture data-vt-rec and its page’s picture recHere(id).
• Don’t fade everything out and in, or fly things in from off screen.

M3Nothing overshoots, and everything can be interrupted

CSS moves decelerate into place on --ease-settle. Scripted and gesture moves use a critically damped spring (spring, springEasing and retarget in src/lib/spring.mjs): a spring described by its duration with zero bounce never overshoots, and when it is retargeted mid-flight it keeps its velocity, so a move you interrupt reads as one motion. Nothing scales past 1 on arrival, nothing pulses: stillness means fine, and a fault is told by its shape and word.

• Why bounce is noise in a tool used all day; a restart mid-move looks like a glitch.
• Do el.animate(frames, { duration: M.springSettle, easing: M.spring }), and start a second move from retarget(state, now).
• Don’t a keyframe past 100%, or a bounce value.

M4Inner layers stay inside

Parts on a device, ports on a panel and rows in a card share their container’s curve and timing, and are clipped to it.

• Why a part poking out of its body mid-move looks broken.
• Do clip face parts to the body and ports to the chassis.
• Don’t give a child its own duration.

M5Movement has a direction, and what both pages share stays put

Between pages, what both pages have stays in place: the top bar, the sidebar and its marker, the place tabs and their marker, the page band (PageBand names itself band) and the filter bar (fb). The rest of the page (main) leaves upward and the next rises in; going up the sidebar, up the path, or Back reverses it (data-nav-dir in Shell.astro). A clicked record transforms into its page: mark its picture data-vt-rec="<id>" in the list and spread recHere(id) (src/lib/vt.mjs) on the element it becomes; the Shell pairs them just before the page changes and names nothing without a pair. Inside a page, the next tab comes from the side you moved towards (DetailTabs does this).

• Why direction tells people where they went, and a thing that stays put is a thing they need not look for again.
• Do at most 8 named view transition elements per page; one PageBand and one FilterBar per page.
• Don’t give list items permanent view-transition-names, or name a record picture yourself.

M6Never jump

Switching a tab, filter, view or step never moves the page under the pointer. Wrap the swap in window.rsHold(box, swap): the box keeps its height through the swap (so the scroll cannot jump), then eases to its new height over --dur-morph and lets go. A height is the one layout property that may animate, and only on one held box. The shared parts do this for you: DetailTabs for tabs, FilterBar for filters, Sort and the view switch, Section for “Show all”, SidePanel (window.rsPanelSwap) for a detail column.

• Why a jumping page loses people’s place. “It should never jump.”
• Do hold every in-page swap.
• Don’t toggle hidden on panels of different heights without holding their box.

M7Reduced motion is a second design, not the animations off

With reduced motion on, every meaning survives: travel and zoom become a cross-fade, a state change is instant, the heartbeat still updates its words, and a reduced page reaches its final state sooner than the full one. CSS is covered by base.css, motion.css, craft.css and motion-library.css; scripts check window.rsMotion().reduced (or km.reduced()) themselves. Each row of the table in M13 names its reduced equivalent.

Reduced motion is on when the person says so, else when the site’s switch does, else when the system does. The person’s choice is Settings › Accessibility › Motion (src/lib/a11y.mjs, accessibility): Follow my device, Reduced (this second design) or Off (nothing moves at all). It is kept in this browser (rs7-a11y) and written to html[data-motion] before first paint. html[data-motion="off"] or "reduced" (from Settings, a tool or a page) reduces motion, html[data-motion="full"] keeps it on even when the system asks for less, and otherwise prefers-reduced-motion decides. One function answers for every script, window.rsReducedNow() (alias rsReduced), defined by the accessibility boot script in the <head> of the Shell, the front door and the room guide, before any other script; rsMotion().reduced, km.reduced() and motion() all ask it, and no script reads matchMedia for motion itself. In CSS, a rule is written once, in @media (prefers-reduced-motion: reduce): the build copies every such block to [data-motion="reduced"] and [data-motion="off"] (tools/postcss-a11y.mjs). Off goes further (src/styles/a11y.css): every transition and animation lasts no time, the duration tokens are zero, and Element.animate() finishes at once at its end state. Keep things still (the same Settings section, or the front door’s Pause animations) starts the front door’s loops paused (row 51) and lands the site-wide grammar’s moves (M19) at once.

• Why WCAG 2.2, 2.3.3: motion makes some people ill.
• Do guard every el.animate() and startViewTransition(): if (M.reduced) { apply(); return; }. node tools/motion-check.mjs --base <dev server> walks the zoom, the palette, the quick menu, the Settings page, Organisation settings, View as, a port, a disclosure, a filter, sections and charts scrolling in, a project’s phases and a card’s hover, once with the system set to reduced motion and once with data-motion="off" on a full-motion system, and fails on any scripted animation.
• Don’t assume the CSS rule stops script animation. It doesn’t.

M8Lights come on in turn

Health glyphs (HealthGlyph.astro, .hg; design notes) arrive quiet, then come on once to their state, one after another (--stagger apart), as they scroll into view. The heartbeat (“checked 40 s ago”) shows last. A later change of state eases in place over --dur-state. A check that is running shows the In progress arc, still; there is no spinner.

• Why it shows something was checked, not just asserted; and a still page reads as fine.
• Do use HealthGlyph (or glyph() from src/lib/health.mjs in a script, .hg-m in an inline script), with a word beside it.
• Don’t invent another status dot, spin anything, or loop anything on a working page.

M9When not to animate

Not text being read. Not numbers counting: a figure never counts up through the values in between; when it changes, the new value ticks into place once (km-tick, M19), exact on every frame. Not charts on a loop: a chart draws in once, the first time it is seen (km-draw-in, M19), and after that it is redrawn still; small multiples and floor plans are drawn still (a floor thumbnail draws in once and eases a changed space in place, row 50). Not things the person did not cause, with three exceptions that happen once: glyphs coming on at load, a new signal, a live change by a colleague. Not decoration on a loop. Stagger at most 12 list items, then show the rest together.

• Why motion that explains nothing hides motion that does; and data is read from still pictures.
• Do ask “what changed?” If nothing did, nothing moves.
• Don’t add motion to make a page feel busy.

M10Live changes stay in place

When someone else changes something you are looking at, it stays where it is. The changed field or card eases to a highlight and back (.is-changed, --dur-state) with a small “Ruth, just now” mark that fades after --dur-linger: call window.rsMarkChanged(el, who). If it moves to another column, hold the box (rsHold) and let it slide across with its data-vk.

• Why shared, live work must not pull the page from under the person reading it.
• Do change the one field, mark it, and say who.
• Don’t re-render the list, re-sort it, or move the scroll.

M11Opening things: one move, from where it came

Everything that opens makes one move from its origin. Peek cards grow from the hovered item (--dur-pop, after --peek-rest of rest) and, when you move to the next item, slide there instead of closing and opening. Settings and View as grow from the button that opened them and shrink back to it (window.rsPopIn, rsPopOut). Search grows from the search button. Filter and Sort menus drop from their pill. A side panel’s content cross-fades in place; the panel never slides. Toasts rise from the bottom (window.rsToast). A <dialog> leaves the way it came, from its backdrop, its Cancel and Escape alike (km.closeDialog(dlg, { to })). Every exit uses --dur-exit on --ease-exit and takes no clicks.

• Why the move says where the thing came from, so people know how to put it back.
• Do start the move at the control that opened it.
• Don’t fade a panel in from nowhere, or slide a side panel across the page.

M12Controls: one family of moves for everything that changes what you see

Every control that changes what is on screen uses the same few moves on the same tokens. The shared parts and the Shell do this; a page only calls them.

• The filter bar’s shape depends on its width only. It is laid out with everything at its widest and again only when its width changes, so no pick and no view switch re-lays it.
• Why motion that is not cohesive reads as unfinished.
• Do call the shared moves; start a move at the control that caused it; keep the pointer’s target still.
• Don’t reload a page to show a setting, or let a control’s own bar or menu change shape as you use it.

M13Every interaction has one row

Each interaction on a page is one of these rows (design notes), with its reduced-motion equivalent. A new interaction adds a row in the same change.

A list that appears with the page (a card grid, a list of rows) makes one quiet stagger, once: the first 12 items rise into place --stagger apart, the rest together; filtering, sorting and live changes never replay it.

• Why a row per interaction is how one system stays one system.
• Do find the row before you build; add one if nothing fits.
• Don’t invent a move for one page.

M14What never moves

• Text being read. A figure never counts through the numbers in between (its new value ticks into place once, M19).

• The band, the top bar, the sidebar, the place tabs and the filter bar between pages.

• The page under the pointer (M6).

• A fine glyph. Nothing that is fine pulses, breathes or glows.

• The floor plan: it never pans or zooms on its own.

• Sparklines and charts after their one draw-in (M19), and small multiples: updated by a still redraw (a floor thumbnail: row 50).

• Focus rings and error text.

• An empty Restricted slot for a partner: drawn at once with its reason.

• Why: stillness is the designed state; a quiet screen means fine.

• Do: let the heartbeat’s words prove the page is alive.

• Don’t: animate something to show it is live.

M15Performance

• Why a move that drops frames reads as slowness, not polish.
• Do measure the heaviest move on a page with reduced CPU.
• Don’t animate width, top, box-shadow or filter on a list.

M16The motion budget: small places, never overwhelming

1. Motion only at a moment of change the person caused or needs to know about. Never ambient, never decorative, never looping.
2. Hierarchy. Navigation (zoom, page to page, card to page) is the largest move; then state change (a ring, the With chip, a section opening or closing); then feedback (hover, press, copy, a toggle); then text updates (the heartbeat’s words), which do not move at all.
3. Budget per screen. Outside the person’s own action, at most one thing moves at a time. A new fault moves at most three things, once (M13, row 15). A list reveal is one quiet stagger, once per page load, never on a re-render.
4. Small by default. Hover and press are the lightest moves (--dur-hover and --dur-press, no layout shift). Nothing larger than the element itself moves unless it is navigation.
5. Still places. Reading text and table rows never animate, and data never moves on its own. A chart draws in once when first seen, and a figure ticks once when it changes (M19); both are the whole of the move.

• Why motion that is everywhere stops meaning anything, and a busy screen is tiring to work in all day.
• Do count what moves on a screen when nothing was pressed: it should be none, or one.
• Don’t add a move to a page that already has one playing, count a figure up, loop a chart, or animate a table row.

M17The motion library is the one source

The seventeen micro-motions of the Keia motion library live in src/styles/motion-library.css and src/lib/motion-library.js (window.km), loaded on every page by src/components/Motion.astro. Their durations and curves are the tokens in motion.css, so each look keeps its tempo; their spring is V2’s (src/lib/spring.mjs, --ease-spring); --km-t is 0 under reduced motion, so every one of them lands on its end state.

Two helpers in the library carry the persist and step moves for any page that regroups or steps through things: km.regroup(box, swap) (M2 persist: FLIP by data-vk, with [data-km-chrome] fading in) and km.slide(el, swap, { dir }) (M12, a step). Both land at once under reduced motion, which km.reduced() reads from the system setting, html[data-reduced] and html[data-motion="off" | "reduced"].

• Why one library, one set of tokens, one spring: the site moves as one thing.
• Do reach for a km- motion before writing a new one.
• Don’t copy a motion’s keyframes into a page.

M18The motion map

What moves where, page type by page type, so it can be audited. Everything not listed is still.

M19One grammar for every page

Every page gets the same moves for the same kinds of change, from the library, without writing any motion of its own. Most of it is wired once for the whole site (src/components/Motion.astro loads src/lib/motion-wire.js; the room guide’s layout does the same), so a new page that uses the shared parts moves like every other page. The audit of every page family against this grammar is docs/rules/motion-audit.md.

Under reduced motion (Follow my device, Reduced or Off, M7) and under Keep things still (Settings › Accessibility), settle, disclose, tick, draw-in and lift land on their end state at once (km.still() in src/lib/motion-library.js).

• Why motion is how Keia Atlas shows a change instead of claiming it; one grammar on every page is what makes it read as one product.
• Do use the shared parts (Section, FilterBar, DetailTabs, <details>, .num, a bar as a track of <i> sized to its value, sparkSvg) and the moves come with them. A new chart that is none of these takes data-chart; a new bar track takes data-chart-bar.
• Don’t write a page’s own version of any of these moves, or turn one off without a reason written beside the opt-out.

L1Same slots, same order, every page

1. Path in the top bar: Place / parent / this.
2. Place tabs, the pages inside the place. Never a second row of view buttons under them.
3. Band (PageBand): overline row (the kind of thing, a status, a SimTag), title, one line; on the right KeyNumbers (3 or 4 figures, each may link) and at most one primary action.
4. Filter bar (FilterBar), first in .content on any page with a list: find box, facets, switches, Clear, then at the right the view switch, Sort and “N of M”. Nothing above it.
5. Main area: the picture and its facts, or the list, full width on the one 12-column grid.
6. Secondary detail: full-width Sections with an h2 each, or DetailTabs when there are more than four. A SidePanel only as a sticky detail column beside a picture.
7. Empty: EmptyState, one sentence and one button, where the list would be.

Every page is one of four archetypes:

A. List (Spaces, Units, Models, Projects, Playbooks, People…)

PATH                                  [Search] [Report]
TABS ─────────────────────────────────────────────────
Overline · Sim                   11     7     9   [Action]
Title / one line                 sites  ...   ...
[find] [Region] [Office] [Kind] [Status] Clear  [Cards|List] Sort  N of M
┌─────┐┌─────┐┌─────┐┌─────┐   cards, rows or a board
└─────┘└─────┘└─────┘└─────┘   groups continue below

B. Record (a space, a unit, a model, a project, a task, an incident, a person)

PATH: Spaces / New York office / 20.10 Whooper Swan
Overline · status · Sim        13 units  ✓ matches  8 seats  [Action]
Title / one line
┌ picture (7 cols) ──────────┐┌ SidePanel: key or facts (5 cols, sticky) ┐
└────────────────────────────┘└──────────────────────────────────────────┘
┌ tile (4) ┐┌ tile (4) ┐┌ tile (4) ┐   equal heights
Section (12 cols)   Section   ...   or DetailTabs when more than four

C. Board, plan or timeline (Incidents board, Schedule, Year, Capacity, Budget, Lab, Scenarios)

Band with numbers
[find] [facets] [switches]         [Day|Week|Month|Year]  N of M
Columns, grid or gantt at natural height; the page scrolls
Legend and "how it works" below

D. Overview (Home, Work overview, Usage, Learn, About, Search)

Band with 3 or 4 numbers
[filter bar, if there is a list]
Priority tiles (12 cols, equal heights)
Main list or table, full width; secondary sections below

• Why filters, band, key numbers and tabs in the same place on every page. A page learnt once is every page learnt.
• Do pick the archetype first, then fill its slots with the shared parts.
• Don’t a page’s own band, stats row, tab strip or filter; a chart, alert card, colour key or explainer above the filter bar.

L2Retired: board pages fit one screen

Retired on 29 Sept 2026 (decision 0026) and replaced by L7 and L8. Boards, plans and grids now take their natural height and the page scrolls. The fit helper is gone from Shell.astro and base.css.

• Why fitting a board to the window made it scroll inside itself, and the page jumped as the helper re-measured.
• Do let the board be as tall as it is.
• Don’t add data-fit-fill or .content.fit to a page.

L3Places, then tabs, then detail

The sidebar is a short, fixed list of places, in one order for everyone: Home, then one entry per module (Locations, Services, Assets, Support, Projects, Vendors, Team, Knowledge), then Learn and Method below a rule (design notes). Each module is On, Connected or Off in Settings › Modules (src/lib/modules.mjs): an Off module is absent from the sidebar and its pages say so and offer to switch it on; a Connected one shows its source on hover (“from ServiceNow”). Pages inside a place are tabs across the top, set in NAV in Shell.astro. When a place is renamed its old address stays as a Moved page (/work/ to /support/, /devices/overview/ to /assets/), and the client router goes straight to the new one.

• Why a sidebar that never changes is learnt once.
• Do add a new page as a tab of its place.
• Don’t add a sidebar entry for one page, or grey a module out: Off means gone.

L4Need to know first

Cards and rows show a name, a status and one line. More is a click or hover away: a peek card (data-peek) shows on hover, stays on click, and closes on a second click or Escape. Every hover has a click and keyboard equivalent.

• Why hover alone is invisible on phones; too much on a card hides what matters.
• Do .list of .rows; zebra rows on long tables.
• Don’t hover-only information.

L5Phones

Under 768 px the sidebar is a bottom tab bar with More, the band stacks (key numbers two by two, the action full width), the filter bar folds its facets into a Filters sheet, and tables, matrices and boards become cards or lists (L10). A device drawing or wiring diagram scales down to fit its card.

• Why technicians use Keia Atlas on site.
• Do check every page at 375 px wide.
• Don’t let the page itself scroll sideways, or make a box that scrolls sideways inside it.

L6One grid, and a path you can climb

Cards on a page sit on one 12-column grid (.g12, spans .s-3 to .s-8) with equal gutters; cards in a row stretch to the same height, so their edges line up. A long list shows its first few rows and a “Show all” (Section with showAll). Every deep page (a unit, a space, a model, a device type’s model) puts its path in the top bar, and each step but the last is a link. On the map the path is the zoom (design notes): Locations / EMEA / Dublin office / Third floor / 3.09 Whooper Swan / Video bar / LAN 1, worked out from the address (src/lib/zoom.mjs), so it reads the same whichever page linked there. Going up it zooms out; [ zooms out one level and ] back in to where you were. The floor (?floor=3) and the port (#port-lan-1) are states of their page and add their own step (window.rsPath).

• Why stacked boxes of different sizes push the answer down, and people need to get back up a level in one click.
• Do pass crumbs to Shell; a page filled in the browser rewrites .mast .crumbs once it knows the unit.
• Don’t leave a gap in the grid for one tall card, or end a path at a step that is not a link.

L7The first screen is a priority order

Not a height cap. The top of the page is a clean block in priority order, the answer first; everything else follows further down. Checks at 1440 by 900:

1. Band and place tabs together at most 150 px (the band about 100).
2. The filter bar (a list) or the picture (a record) starts within 260 px of the top of main.
3. The first block under the band is the answer: the list, the drawing beside its key, the board. Never an explainer, a chart, an alert digest or a colour key.
4. Cards in a row share a height.

• Why people judge a page by its first screen, and what they came for must be the first thing on it (the most important information sits at the top, neatly organized).
• Do move explainers, legends and “how it works” below the main area, or into a disclosure.
• Don’t shrink things or add inner scrollers to squeeze more onto the first screen.

L8The page scrolls; nothing scrolls inside it

One scrollbar: the page’s. No box with a fixed or window-based height that scrolls inside itself, no fit-to-window heights. A long list uses “Show all”; a detail column is a sticky SidePanel, which follows the page and, when it is taller than the window, sticks by its foot so every part is reached by scrolling the page. A pop-up that floats over the page (a filter list, the phone Filters sheet, a peek) may scroll inside itself when it is taller than the window; nothing on the page itself does, sideways included (L10).

• Why cramped modules that scroll inside themselves are what not to do. Two scrollbars hide content and trap the wheel.
• Do natural heights; SidePanel for a column that should stay in view; .stick on a record’s picture so it stays beside a taller panel.
• Don’t max-height with overflow: auto on content, or height: calc(100vh - ...).

L9The band: one line, key numbers, one action

PageBand takes the overline (the kind of thing: “Space”, “Unit”, “Project PRJ-09”, “Catalogue”), the title, one line (cut with an ellipsis), and sim or stage for the SimTag. KeyNumbers holds 3 or 4 figures, each a link where it can be (a page, ?status=installing to filter this list, #incidents to open a tab or section), with a tone only when the label says the same thing in words. The count of a filtered list is not a key number: it is the filter bar’s “N of M”. One primary action, at the right end of the band.

• Why one band everywhere replaced twelve page-made variants, and the band stays put between pages (M5).
• Do make each key number answer “how many need me?” and link to them.
• Don’t a button under the lede, two primary buttons, a count as the overline, or a “shown” number beside the bar’s count.

L10Every width, not one screen

Keia Atlas is laid out for any window from a 375 px phone to a 2560 px monitor, and checked at 375, 768, 1024, 1280, 1440 and 1920. Nothing scrolls sideways, nothing overlaps, and no label is squeezed or broken inside a word; when something does not fit, it changes shape.

The frame follows the window (media queries, in base.css and Shell.astro):

From 1900 px the content stops at --page-max (1760 px) and centres. The path stays on one line; the page’s own name is cut with an ellipsis. The place tabs never scroll: the ones that do not fit go into a More menu at their right end, and the current tab always shows.

Parts follow their column (container queries). main is the container main and every .content is the container content, so a part lays out by the width it really has, beside the sidebar or not. Inside .content use @container content (max-width: ...), not @media. The usual steps are 1100, 1000, 840, 700, 600 and 560 px of content.

The grid (.g12): 12 columns from 840 px of content; 8 columns from 560 px (quarters and thirds two a row, a lone one takes the row, halves stay halves, anything wider takes the row, and a picture’s SidePanel moves under it and stops sticking); 4 columns under 560 px (everything takes the row). The gutter (--gutter) is 20, 16, then 12 px.

The shared parts:

• PageBand: key numbers and the action sit right of the title from 900 px of main; under that they go below the title, the action at the right end of their row; under 600 px the numbers are two by two and the action takes the full width.

• FilterBar lays itself out by the space it has. Line: everything on one line. Stack: the find box with the view switch, Sort and count, then the facets as one group on the next line; or the find box alone, then the facets beside the view switch, Sort and count, whichever is shorter. Sheet: under 600 px of content, or when stacking would take more than three lines, the facets fold into one Filters button (showing how many choices are on) that opens a sheet from the bottom. Sort and the count never part. A closed facet list takes no space. The bar sticks under the top bar only when it is one line, or from 1024 px.

• DetailTabs wrap into rows of pills when they do not fit on one line.

• SidePanel moves under the picture under 840 px of content.

• A table marked class="to-cards" becomes one card per row under 700 px of content, each cell with its column’s name (filled from the heading). A matrix (Who does what, RACI) becomes one card per row listing only its non-empty cells. A board goes 4, 2, then 1 column. The Schedule’s week goes from people by days, to each person above their days, to days stacked; the year plan narrows its name column, then puts each name above its bar. A phase rail turns to run down the page.

• Why: a page should adapt to whatever screen size, not just a single one. A page tuned for 1440 looked broken in a narrower window: facets orphaned on a second line, matrix headings squashed to “Pro-vision”.

• Do: design each block’s narrow shape (cards, a list, a stacked row) when you design its wide one; run node tools/responsive-check.mjs --base <dev server>/keia-atlas before you commit (it fails on sideways scroll, overlapping parts and labels wider than their box, at all six widths).

• Don’t: a min-width on a table or grid that forces a sideways scroll, overflow-x: auto on content, text broken inside a word, @media for a part inside .content, or a hidden pop-up sitting past the window’s edge (it widens the page even while hidden).

D1Data before drawing

Write data/device-models/<manufacturer>-<model>.yaml from two independent readings of the vendor’s documents. What they don’t state goes under gaps.

• Why drawing, ports, wiring and checks all read this file.
• Do cite each document in data/sources/.
• Don’t fill a field from memory.

D2Front-on, from the vendor’s picture, to scale

Trace the vendor’s front photo or dimensional drawing into src/lib/art.mjs (a 320 by 180 canvas centred on 160, 88) at 0.35 px per mm, and name the source in ART_SRC. No picture, no drawing: the class outline shows and says so.

• Why people recognise the box on the wall, and size is information.
• Do take width and height from the data sheet.
• Don’t guess a shape, add text, or add a logo beyond a plain mark.

D3Same parts, same order

Every model of a type draws the parts in that type’s ORDER; a missing part becomes zero size. The shell is shadow, body, then only what hangs off it (mount, stand, feet); everything on the face is clipped to the body.

• Why matching parts let one model morph into the next.
• Do switch to and from every other model of the type before committing.
• Don’t invent a part name for one model.

D4Colours from art tokens

Drawings use only art-* classes and art tokens. Real finishes are near-black, so art keeps its colours in every look.

• Why a look can retune all art in one place.
• Do pick the nearest art-* class.
• Don’t write a hex colour in a drawing.

D5Ports by id, face and signal

One entry per physical port: an id (hdmi-in-1, lan-1), a face (front, rear, bottom) and an order left to right. Each face gets its own row. Colour comes from the signal (video, USB, PoE, network, HDBaseT, power, audio). A new connector gets a shape in SHAPES in src/lib/ports.mjs first.

• Why the same id on two models makes the port slide, not reappear.
• Do reuse an id when another model has the same port.
• Don’t colour a port per model.

D6State beside the drawing

Health is a status light beside the device. An open incident makes its row or card radiate red. Lifecycle is a pill in plain words: Ordered (plan), Procured (procure), Being installed (deploy), In service (manage), Retired (retire), from STAGE_LABEL in src/lib/data.mjs. One physical device is a unit, and the list of them is Units, because a unit is installed for only part of its life.

• Why the drawing stays recognisable and state reads the same everywhere.
• Do pair each light with a word, and use the same status words everywhere.
• Don’t tint the drawing, or call the set of units “Installed”.

D7Glyphs at small sizes

At icon size a device is its class glyph from src/lib/glyphs.mjs: 40 by 28, 1.8 stroke, round ends, current text colour.

• Why a traced drawing turns to mush at 40 px.
• Do add a glyph with every new device class.
• Don’t shrink a full drawing into a list row.

R1To scale, one viewpoint

Each space type is modelled in metres from its published facts: area, table size, display size, camera height. Sizes not published are chosen to fit, kept the same everywhere, and named in the caption. Every space is a cut-away from the front right corner, display wall at the back, with a ruler in metres. This is for space drawings; a whole building is R8.

• Why a small huddle room must look small, and one space read means all spaces read.
• Do change the profile’s data and let the drawing follow.
• Don’t nudge furniture by eye.

R2What every space drawing shows, and how hidden kit looks

Every item in the build option, numbered to match the Key beside it, and every outlet plate, lettered A, B, C. Displays on the wall or a stand, monitors on desks, furniture at real size. Things out of sight (behind the display, under the table, behind storage, outside the door, in the ceiling) are drawn where they really are, under what hides them, with a faint dashed outline over it. One marker rule everywhere, drawing and Key alike: a solid marker is something you can see in the space, a dashed one something hidden. A visible thing’s marker sits just above it (or below or beside it, never on another device); a hidden thing’s marker sits just outside what hides it, on the nearest side, with a short leader line back to it. Markers never overlap. “See behind” fades what hides them; pointing at a hidden thing does the same.

• Why the drawing and the equipment list must never disagree, and hidden kit must not pile up on the display face.
• Do give every item a place from the profile; let layoutLabels in src/lib/room3d.mjs place the markers.
• Don’t leave out a device because it is hard to see, or put a marker on the thing that hides it.

R3Outlets are real plates, in the site’s plug type

Every outlet in the option is drawn as what it is, to scale, on its surface: a wall plate on the wall, a floor box flush in the floor, a desk module on the desk, a plate in the ceiling. The outlets at one place share one group (behind a pair of displays, the ports split in order, half behind each screen). Power sockets are the site’s type from mains in data/sites/<site>.yaml (a Danish site draws Type K, since C is a plug only); data ports are keystone jacks coloured by signal with the same tokens as ports and cables everywhere; a laptop wall plate shows its HDMI and USB-C. Sizes, in mm:

A wall outlet sits at the height the guideline gives (height_mm on the outlet, the middle of a range); where it gives none, 450 mm to its centre (house default, inside Approved Document M’s 450 to 1200 mm and above ADA’s 15 in). Outlets behind a display sit low behind it, under the track and the hidden devices (R7). The caption names the format and any house default. A space type has no country, so it shows plain outlets. The Key lists every plate, drawn front-on, with what it feeds. “Cables” draws every cable in the option along its containment (R7), coloured by signal; pointing at a plate lights the devices plugged into it and their ports, and pointing at a device lights its plate.

• Why Dublin has Type G sockets on 86 mm plates, Chicago Type B on 70 mm ones; a technician should see where to plug in.
• Do record the mains for every new site, and number wiring ends as outlet ports (outlet:power/behind-display#2) so the cable finds its socket.
• Don’t draw an outlet as a floating icon, or one country’s plug everywhere.

R4Wiring reads left to right

Where a signal starts, what carries or switches it, where it ends. Cables take their signal’s colour. In the wiring diagram, outlets are listed under each device, not drawn as long lines (the space drawing shows them as plates, R3). Hovering a device or cable lights its path; a table lists the same cables.

• Why people trace a fault the way the signal flows.
• Do keep the diagram on one screen.
• Don’t draw how every space reaches the internet.

R5Racks: small and whole, the chosen item large

Racks are drawn in millimetres to scale: 1U is 44.45 mm, U1 at the bottom, each item from its front in src/lib/rackfaces.mjs and its product in data/rack-gear. The whole rack is small (about 12 px a unit) with a bar in each item’s group colour; the chosen item is drawn large beside it, every port on it, with its facts and links. A port a recorded patch cable uses shows a plug in the cable’s standard colour, and pointing at it says where the cable goes. Choosing keeps the item in the address and lights its cables in Patching; nothing dims and the page never moves. Power strips are listed, not drawn, in the small rack. A recorded replacement can be shown as it was (decision 0028).

• Why a technician should see the whole rack at once, then read one device port by port before touching anything.
• Do add the gear’s front and product before placing it; record a swap with replaced on the rack item.
• Don’t draw a generic box for real gear, draw the whole rack so large it needs a list to navigate, or put details in a panel that changes height under the pointer.

R6Plans in cards: long side across, blue line is the screen

The small floor plans on space type and space cards sit on a wide tile. A space that is deeper than it is wide is turned a quarter turn so its long side runs across the tile and the plan fills it. The display wall is marked in blue, and it stays the one fixed thing: at the top of an upright plan, on the left of a turned one. Each plan is to scale inside its own card, with its 1 m bar. The big drawing on a profile page keeps the display wall at the back.

• Why a tall plan on a wide tile leaves it half empty and small; “the blue line is the screen” is easy to learn and works either way round.
• Do let RoomPlanSprite.astro decide the turn from the space’s width and depth.
• Don’t turn a plan by hand, or drop the blue marker to make a shape fit.

R7Cables run along containment, from the real ports

Every cable in a space drawing runs the way an installer would run it: out of the port it really uses, a short straight drop into containment, along the containment, and a short straight drop into the port at the other end. Nothing crosses the space in the air. Behind a display, bottom to top: the outlet plates just above the screen’s lower edge, then the track (a horizontal channel across every screen), then the boxes behind the display, hung on their base with the rear panel down so their cables drop straight into the track, each behind the screen whose plate it plugs into. Elsewhere: a wall riser from the floor duct and skirting up to the track, clear of the video bar and the plates; a ceiling drop from the track to the ceiling baskets along the display wall and the door wall, with a branch across the ceiling to each ceiling device; skirting with straight rises to each wall plate; under a table a tray, then a cable spine or a leg down to a floor cover into the floor box, and the floor duct from the box to the wall riser (a table fixed to the display wall uses a wall pass-through instead); under a desk a tray, a back leg, a floor cover to the nearest wall. The building’s data comes in above the door, from the corridor ceiling; each plate’s feed runs up inside the wall to it (a floor box’s through the floor void). Each profile records its containment and data entry in geometry.

Routing is Manhattan in the space’s axes (along the display wall, away from it, up): the shortest path over the containment, with few bends. Cables that share a run lie side by side in lanes 3.2 px apart (the track’s lanes close up to 2.1 px to fit behind the screen), each in its signal’s colour, keeping their lane round every fold; the order is chosen to leave the fewest crossings. Stretches under the floor are dashed. Ports come from the model’s face and order; where the model does not give them, the house default is the rear face, lower third, spread about the middle, and the Key says so. Containment is drawn only with Cables on, and only as far as its cables go. Pointing at a cable lights its whole route (the containment it runs in) and both ends; the Key lists every cable in words (“Video bar LAN 1 to plate B, data 5, via the track behind the display”).

• Why a technician must be able to trust the drawing to find a cable, and a tidy, standard route is what a good install looks like.
• Do give each device model its ports’ face and order; change the containment rule in src/lib/cableroute.mjs, never one cable by hand.
• Don’t draw a cable as a curve, invent a port the model does not have, or route anything through the air to make a picture fit.

R8A building is one model, shown two ways

An office with floor files is one building model (src/lib/floors.mjs), shown as an interactive 3D view and as floor plans (decision 0030). The 3D view starts at the house angle (front right, like a space drawing), has preset views and a floor switch, and never moves on its own; the floor plan is the phone view, the keyboard route and the view without WebGL. Choosing anything in either lights its whole path to the internet in both, and the panel beside lists it hop by hop from trace(). Spaces are coloured by their live state, cables by purpose (the house cable colours) or by health; a problem glows, or shows a still ring with reduced motion. Every view of it carries the fictional floor plan label (F9) and “Simulated live” for the states.

• Why a building with a riser and hundreds of cables cannot be read from one fixed angle, and a phone or a keyboard needs a flat, focusable view of the same thing.
• Do change the floor files, runs or circuits and let both views follow; keep one choice for both views.
• Don’t draw a second, hand-made plan, let the 3D view turn by itself, or show a floor or cable that is not in the data.

P1Every list has find and filter

A list longer than a screen gets FilterBar (src/components/FilterBar.astro): a find box, then pill buttons (Region, Office, Kind…) that open on hover, click, tap or keyboard focus. People pick as many choices as they like, each shows how many items it would leave, the list changes as they pick, and the address bar follows so a filtered list can be shared. It says “N of M”, Escape clears the find box, and an empty result says so and offers “Clear the filters”.

• Why scrolling is the slowest way to find something, and one filter that looks and moves the same everywhere is learnt once.
• Do mark items data-fi with data-find and data-f-<key> (several values with a bar, a|b), and give the bar facets ({ key, label, options: [{ value, label }] }). Switches use data-t-<key>="1". A view switch is views, a sort is sort (both at the right); anything else inside the bar tag sits to their left. Items and groups hide through the bar, which holds the page still (rsHold) and uses the motion tokens.
• Don’t build a one-off filter, or hide list items yourself. PageFind is the older flat version still on Setup guides and Device types; move them to FilterBar when they are next redesigned.

P2Search reaches everything

The top bar Search (/ or Ctrl K) finds spaces, profiles, devices, models, setup guides, projects, people, spares, cables and retired kit, and reads “EMEA spaces with X52” into chips people can change. The same words always give the same answer.

• Why one box beats knowing where things live.
• Do add a new kind of thing to src/lib/search-index.mjs in the same change.
• Don’t ship something search cannot find.

P3Report on every page

Report offers Propose an edit, New firmware found or Urgent issue, filled in with what the page is about (the about prop on Shell), and sends it to the owner.

• Why people fix knowledge where they notice it is wrong.
• Do pass about on every page about one thing.
• Don’t add a separate feedback form.

P4View as

Anyone can see Keia Atlas as any role: from their name in the sidebar, the ribbon’s Change, the gear’s quick menu and the Settings page (on a phone too) or the palette (“> Liam”). View as is one sheet: a find field, three suggested people, then every role as a list grouped by team, each with one whole line on what it is for and its people as named chips (src/components/ViewAs.astro). Role changes what comes first, never what exists; vendors alone see less.

• Why people learn each other’s jobs.
• Do order a role’s first screen (Home) and its place tabs by role; the sidebar keeps one order for everyone (L3).
• Don’t build a page only one role can open.

P5Simulated data says so

There are no stages: every page belongs to a module (its place in the sidebar), and while Organisation settings (/settings/organisation/) has that module Off, the page says so and offers to switch it on (Shell.astro; minStage is retired and ignored). Invented numbers (usage, costs, scenarios) carry the dashed “Simulated” tag, and made-up figures that change as you watch “Simulated live”, both from SimTag in the band’s overline row.

• Why trust depends on knowing what is real.
• Do label simulated numbers where they appear.
• Don’t show made-up data as live.

P6Empty states say what next

An empty list or a filter with no match says so and offers the way out: clear the filter, try fewer words, add the first one.

• Why a blank panel looks broken.
• Do one sentence and one button: EmptyState.
• Don’t a blank box or a bare “0”.

P7Undo and archive, never delete

Actions take effect at once and offer Undo for about five seconds. Records are archived or retired with who, when and why; retired pages and files are removed, and stay in the project’s git history.

• Why audits need history, and fear of mistakes stops people using a tool.
• Do “Archived. Undo”. Changes to work (a task ticked, assigned or moved) go through the live layer, src/lib/live.mjs: each is an event with who and when, the History drawer shows every version, and Undo writes a new event that puts the old value back (decision 0025).
• Don’t “Are you sure?” dialogs, or a Delete button. Don’t change work in browser storage behind the live layer’s back: other windows will not see it and it has no history.

P8Propose, then approve

Anyone proposes a change to a profile, setup guide or playbook; its owner approves; nothing changes before that. Agents only propose.

• Why the standard stays right when a person or an AI is wrong.
• Do say who will see a proposal.
• Don’t let an edit change the standard directly.

P9Help on every page

Every page has a Help switch in the top bar (the round ? beside Report; the ? key toggles it, Escape turns it off, and it is remembered for the window). With it on, everything that has help gets a dotted outline, and pointing at it, focusing it or, on a touch screen, tapping it once shows a small card: what it is, what to do with it, and a Learn more link to the matching lesson or glossary word. Every page gets help for free from the shared parts (the top bar, band, key numbers, filter bar, tabs, panels, sections, empty states and the live layer), and adds a key only for a widget of its own.

• Why people understand a page by pointing at it, without training and without leaving it.
• Do put data-help="<key>" on a widget only your page has, and write its entry in src/lib/help.mjs (name, what it is, what to do, and where to learn more). Take the words of a glossary term from the glossary (term:<id>). tests/help.test.mjs fails, and names the key, if a data-help key has no entry.
• Don’t explain a control in a page’s own tooltip or a paragraph above the list. Don’t write help that repeats the label: say what the thing is for and what happens when you use it.

P10Every number drills down

On overview and summary pages (Home, the Work overview, the Spaces and Devices overviews, office and region pages, service pages, and the band and summary tiles of a record), every count, key number, tile, matrix cell, chip and “See all” is a drill-down: selecting it opens the page that owns that list, with the matching filters already in the address, which the filter bar reads when the page opens. The link says where it goes (“See all 9 in Incidents →”, “See all 288 in the Work list →”), and the page it opens shows the same count in its “N of M”. Back returns to the same place on the page you came from.

• Why a number is a question (“which nine?”), and the answer lives on one page, with its filters, sort and actions. A summary that grows 288 rows in place stops being a summary, hides where the list really lives, and makes two versions of the same list.
• Do give KeyNumbers items a to ('/incidents/?state=new,in-progress,on-hold', or '?status=problem' when this page holds the list). Give an overview’s Section a to and a place (and carry when both pages share a filter bar): it shows the first few items and “See all N in →”, never “Show all”. A figure that counts no list (a phase, a date, an estimate, a size, a percentage, or the total of the list right under it) is the one exception, and says so with fact: true. Mark a drill-down’s number or chip data-vt-rec="dd-<path>" (KeyNumbers and Section do it for you) and give the destination’s PageBand rec="dd-<path>", so the number flies into its title (M5). A hover peek may preview; the click always navigates, or opens the record. A control that changes how this page is seen (See as) or filters this page’s own list may stay on the page; mark its box data-dd="<why>".
• Don’t expand a list in place on an overview. “Show all” (Section showAll) is only for a list on its own page, or a short extra of a few rows inside a record; never 20 or more rows onto an overview. Don’t link to a list without the filter the number counts, and don’t show a number that opens a page counting something else. node tools/drilldown-audit.mjs --base <dev server>/keia-atlas lists every summary element, what a click does and whether the counts agree.

P11Depth and density, remembered per person

Every page has four layers: Band, Summary, Record and Raw. At each boundary, OpenHere says the layer’s name and offers “Open pages like this here”: pressing it makes that layer where every page of the same kind (home, space, device, job, service…) opens for this person, straight there with no scroll animation. The address wins (#record, #raw), and Back keeps its scroll. Density is Comfortable (the default) or Compact (the default in the Enterprise and High contrast looks): row height, card padding and type one step smaller, never a slot hidden, touch targets still 44 px. Both are per person and kept in this browser (rs6-depth, rs6-density, src/lib/depth.mjs); density is applied as html[data-density] before first paint; Settings has both: Density, and “Where pages open” (Band, Summary, Record or Raw for every kind of page at once).

• Why one person wants the answer and to leave, another lives in the log; the page serves both when the layer is theirs to choose and it is remembered.
• Do put <OpenHere kind="..." layer="..."> at each layer boundary; give the layer’s first element data-layer-start; read spacing from --row-py, --row-px, --card-py, --card-px and type from --name-size and --support-size (src/styles/density.css).
• Don’t hide anything in Compact, remember depth per page instead of per kind, or animate the scroll to a remembered layer.

P12Standing rules: reversible runs, irreversible asks, people keep the diagnosis

Routine work runs only under a standing rule a named owner approved once (data/standing-rules/, the model in src/lib/rules.mjs). Every rule declares its way back: Undo (it truly reverses), Roll back (the previous state is kept), nothing (it ends as it started), or Asks (it cannot be put back, so a person confirms every run). Before every run it checks its conditions in order and its caps: never more units than its wave, never in a booked meeting, never in a change freeze, halted after runs in a row unable to complete. A run reads, writes and reads back; a write that does not read back as intended is “Unable to complete”, never done, and a rule that declared a way back restores what it changed and raises an incident to its owner. Every automatic action carries “How was this done?” (HowCard.astro): what it read, did, ruled out and did not check, evidence as a count, only the declared verb, Run again only for the rule’s owner or the job’s owner, and the full trace one link away in the audit log (/support/log/). On a P1 or P2 the person says what they think before the suggestion opens. Work nobody takes within the response target goes to the service owner (the default owner clock); a major incident names one commander.

• Why automation that explains itself and can be put back is trusted; automation that hides or fakes an Undo is not, and people who stop diagnosing lose the skill.
• Do declare the way back in the rule’s data; show the verb from the rule, never from the page; word results as “Done automatically” or “Unable to complete” with the rule and its owner; keep “What it did not check” filled.
• Don’t show an Undo that is not real, run anything irreversible without a person’s confirmation, show a confidence percentage, or open the suggestion before the person’s call on a P1 or P2.

P13Capabilities are switched on when they are needed

The bigger items a team adds when it needs them (licences, room checks, out of service, alert rules, certificates, security flaws, config backups, meeting quality and the rest) are capabilities of a module, each On, Connected or Off in Organisation settings (/settings/organisation/), inside its module’s card (src/lib/modules.mjs, SettingsModules.astro). The page draws every module and capability from the registry, so a new one needs no change there. A capability is off while its module is Off or anything it requires is off. The registry in modules.mjs is the one list of ids. The page head writes data-feat-off and data-feat-conn on <html> before first paint (rs6-features), and featureCss() takes away every element marked data-feature="<id>" while it is off; a Section (or a box marked data-feat-wrap) whose content is all gated by one capability goes with it, heading and all; a section that holds several capabilities’ cards carries data-feat-any="<ids>" with the rule featureAnyCss(ids) puts beside it, and goes when all of them are off. A work item that belongs to a capability (a room check round) carries feature, and the Schedule leaves it out while it is off. A Connected capability shows its source mark (FeatureSource, “from Datadog”).

• Why Keith’s rule (30 Sept 2026): switched off, a capability leaves no trace, so nothing ever looks missing; switched on, it is there in full.
• Do mark the section, card, figure (KeyNumbers feature), tab (NAV feature) or answer fragment with data-feature; check featureOn(id) when the site is built and window.rsFeatureOn(id) in a script before writing an answer or a count; redraw on rs:demo-change (detail.what is features or modules); give a page that belongs to one capability a gate that says it is switched off, with its own Switch on.
• Don’t leave a heading, an empty card, a zero or a sentence behind for something switched off, or register a capability anywhere but modules.mjs.

P14Settings: mine, the organisation’s, and the demo’s

The gear opens a short quick menu: who you view as, light or dark, the look, text size, and links to All settings, Accessibility and Organisation (src/components/Settings.astro). It never scrolls. /settings/ holds a person’s own settings in short sections (You, Accessibility, Organisation as a link, Demo, About), each a heading and a list of rows, with a find box and a section list (src/lib/settings.mjs). /settings/organisation/ holds what an admin sets for everyone: the modules and their capabilities, labelled “Organisation · affects everyone”. Controls that exist only for the demo (View as, time away, Reset the demo) sit together under Demo and say so.

• Why Keith (30 Sept 2026): “way too much in that one settings button”. A person should not have to scroll past the organisation’s switches to change their own look.
• Do put a new personal setting in a section of /settings/ as a row (name, one line, control), give it data-fi and data-find so the find box reaches it, and keep its storage key applied before first paint. Put anything that changes Keia Atlas for everyone on the Organisation page.
• Don’t add to the quick menu (six things at most, nothing wraps), cut a label short, or put a three-way pill on every row of a phone list.

W1Plain English, thing first

Short sentences, the thing people need first. Buttons say what happens; links name where they go. Irish English spelling (colour, organise), sentence case, numbers as digits.

• Why people are busy, and many are new to this kind of tool.
• Do “Report an urgent issue”.
• Don’t “Utilise the escalation functionality”.

W2Glossary words, used exactly

Space, space type, device type, model, setup guide, manufacturer, known error, device, unit, lifecycle, build option, playbook, task, proposal and report mean what src/pages/learn/_glossary.mjs says, everywhere.

• Why one word for one thing is how people learn a system.
• Do add a new term to the glossary before using it.
• Don’t call a space type a “room profile”, “room type” or “template”, or a device type a “device profile”.

W3No internal names

Public vendor and product names are fine. A real company’s internal systems, hostnames, people, job titles and ticket text never appear. Name systems by what they do (the asset register) or with a made-up name.

• Why Keia Atlas is open source; every copy must be safe to publish.
• Do map real names in the work version’s configuration.
• Don’t paste a real hostname or ticket as an example.

W4No em dashes

Use a comma, colon, brackets or a full stop.

• Why house style, and shorter sentences.
• Do search for the character before committing.
• Don’t use two hyphens instead.

W5Find boxes and facets say the same thing everywhere

The find box says “Find a” and the thing, then two examples: “Find a space, number or office”, “Find a unit, hostname or serial”. Facets come in one order, Region, Office, Kind, Status, then the page’s own (Space type, Priority, Colour). An office is always “Office” (never “Site”), a state always “Status”.

• Why a bar that reads the same on every page is used without reading it.
• Do name the facet by what it filters, in the shared order.
• Don’t “Site” for an office, “State” for a status, “Use” or “In use” for a kind, or a find box that lists five made-up examples.

W6The right end of the filter bar: view, Sort, count

At the right of the bar, in this order: the view switch as word pills, “Cards | List” (or “Day | Week | Month | Year”); then the Sort pill, “Sort: By office”, which opens like a facet; then the count, “N of M spaces”, always shown, the noun in the plural. Sort choices start with “By” (“By name”, “By space type”) or end with “first” (“Being installed first”, “Incidents first”).

• Why the count answers “how many?” in one place, and a sort that works like the filters is learnt once.
• Do pass views and sort to FilterBar.
• Don’t icon-only view buttons, a <select> for sort, or the count again in the band (“Spaces shown”).

W7Buttons: one primary, verb then thing

Each band has at most one primary button, at its top right, named verb then thing: “New project”, “New playbook”, “New model”, “Propose an edit”.

• Why one obvious next step per page, worded the same way on every page.
• Do “New” for making a thing, “Propose” for changing a standard (P8).
• Don’t “Make a change”, “Add a device model”, “New project from a playbook”, or a second primary button under the lede.

W8Status words and the simulated tag

One set of words per kind of thing. Units: Ordered, Procured, Spare (arrived and kept in an office’s IT store), Being installed, In service, Retired (“Live” is kept for live data: “Simulated live”, “Live between windows”). Spaces: Planned, Being installed, Being replaced, In service. Tasks: To do, Doing, Waiting on, Done. Incidents: New, In progress, On hold, Resolved. Project phases say Plan, Design, Procure, Deploy (provision, install, configure and commission together), Hand over, Closed. Data that is not live says one of two things, in the band’s overline row only (SimTag): “Simulated” (made-up figures or people) or “Simulated live” (made-up figures that change as you watch). A page never says which stage it belongs to.

• Why the same state in two words reads as two states, and trust depends on knowing what is real (P5).
• Do take lifecycle words from STAGE_LABEL; pass sim to PageBand.
• Don’t “Integrate”, “Install” and “Commission” as phases, “Live” or “Decommissioned” for a unit, “Not yet in service”, or “Demo figures”, “Demo people”, “Placeholder”.

W9The overline names the kind of thing

The small line above a page title says what kind of thing the page is about: “Space”, “Unit”, “Project PRJ-09”, “Catalogue”, “Directory”. Status and the simulated tag follow it on the same row.

• Why people glance at the overline to know where they are.
• Do a noun for the kind, then the facts that place it (“NYC · New York office · Level 20”).
• Don’t an audience (“For service managers”) or a count (“20 device types”).

W10Offices by city, manufacturers by name

An office is called by its city: “the Dublin office”, “the New York office”. Remote groups keep their own names (“Remote EMEA”). The made-up building name stays in the building field of the site file and is never shown. Who makes a model is its manufacturer, on screen and in the data. “Vendor” is a company that installs or looks after devices.

• Why a made-up name per building was one more thing to learn, and easy to confuse with the real ones.
• Do “at the Dublin office”, “Dublin office video bar refresh”, “Juneau 2.03 Wren” for a room calendar (the city, not “office”).
• Don’t an invented building name, “maker” for a manufacturer, or “Site” for an office in a label.

T1Components use tokens only

Colours, fonts, radii, borders, shadows and sizes are CSS custom properties. A look is one file in src/styles/looks/ setting the same tokens.

• Why a new page gets every look for free; a new look is one file.
• Do background: var(--surface).
• Don’t a hex colour in a component (art tokens aside).

T2Five looks, light and dark

Studio (default: warm and calm, one burnt-orange accent), Enterprise (crisp and dense: a deep navy frame, one clear brighter blue accent, no red or burgundy, set in Inter), High contrast (maximum clarity), Drawing set (blueprint: blue ink lines on drafting film; a blueprint in dark) and Playful (brighter, ink outlines, hard shadows). A head script sets data-look before first paint. Auto mode follows the system; the mode button flips it; each look sets dark tokens under both prefers-color-scheme: dark and [data-theme="dark"].

Each look also has its own motion personality, set by the motion tokens in src/styles/motion.css (docs/rules/motion.md, M1): Studio calm, Enterprise shorter and tighter, Playful a little livelier (never bouncing), High contrast minimal motion, Drawing set lines that draw on. Changing the look cross-fades the page and changes both its colour and its tempo.

• Why the design is a system, and eyes and screens differ.
• Do check new pages in every look, light and dark.
• Don’t design for Studio in light only.

T3Contrast

Text passes WCAG AA (4.5 to 1) on its surfaces in every look and mode; large text and controls 3 to 1. Status is never colour alone.

node tools/contrast-check.mjs checks the health palette in every look, light and dark. It runs in npm run build and npm test.

• Why WCAG 2.2, contrast (minimum).
• Do use --text-2 and --text-3 for quieter text.
• Don’t lower text opacity to make it quieter.

T4Colour has jobs

Health has six states, each with one shape from the HealthGlyph set and a word beside it: Fine, To review, Fault, Not reporting (the fault colour, dashed), In progress, Planned, Off. Shape carries the state; colour backs it up.

Each state has three tokens in every look and mode:

• --h-<state>: the fill, for glyphs and chart marks. At least 3 to 1 on --bg and --surface.
• --h-<state>-ink: the words. At least 4.5 to 1 on --bg, --surface and its own soft.
• --h-<state>-soft: a light tint for backgrounds.

The states are fine, review, fault, progress, planned and off.

Fine is calm, not grey. A Fine glyph always has its own soft green-teal (--h-fine), on overviews too, so a healthy workplace reads as healthy rather than off or unknown. The dark cockpit keeps overviews still, not colourless: To review, Fault and Not reporting stand out by a stronger colour, their shape and their word. Red at more than glyph size is only for a P1 or major incident, a safety matter or a live event at risk, and it leaves when that is over.

Useful colour beyond health: each service and each lens has its own colour (--svc-av, --svc-network, --svc-infrastructure; --lens-health, --lens-support, --lens-network, --lens-projects, --lens-vendors, --lens-knowledge, in src/styles/craft.css), for charts, a section’s accent and small highlights. They are chosen away from the health hues, are at least 3 to 1 in every look and mode, and never mean health.

The accent marks where you are, focus and the one action. It never means health. Cables and ports use signal colours, never health colours.

The old families (--green, --amber, --red, --blue, --violet, --grey) are now aliases of the health tokens. They are retiring from components: use --h-* in new work.

• Why when a colour means one thing, people read it without thinking.
• Do pair each glyph with its word, and use the ink token for any text.
• Don’t use the accent for health, a fill token for text, or red for decoration.

T5Icons follow the text

Anything that sits in a line of text scales with Text size; anything that belongs to a drawing keeps the drawing’s scale.

Settings › Accessibility › Text size multiplies every font size by --rs-text (1, 1.15 or 1.3). Beside text, icons grow by the same amount through --rs-icon: health glyphs, button and chip icons, chevrons on links, the sidebar and palette icons, avatars and the With chip’s avatar, the pause button, a device’s small picture in a row, and the grid column an icon sits in. Hit targets grow with them and are never under 24 px.

On a floor plan, a floor thumbnail, the 3D office, the front door’s hero or a room drawing, markers belong to the picture and keep its scale: the drawing sets --rs-icon: 1 on itself, or draws its markers inside its own picture.

How it works (tools/postcss-a11y.mjs, src/styles/a11y.css): the build scales any px size of 48 or less on an svg or img, and on a small fixed box that holds letters (an avatar, a step number, a chip of a set height). An svg sized only by its width and height attributes is scaled by rules in a11y.css. A health glyph’s size is calc(<px> * var(--rs-icon, 1)), and its stroke is drawn in its 16-unit box, so it thickens with the glyph as a letter’s stems do.

• Why a status mark that stays small beside large text looks wrong and is harder to see (WCAG 2.2, resize text).
• Do size icons in px (or em) in CSS or with width and height; add /* text-size: icon */ to any other box that must grow with text (an icon button, a frame round an icon, a status dot); add /* text-size: drawing */ to a rule for a mark that belongs to a picture.
• Don’t size an icon, an avatar or a label column in px in an inline style, or set a fixed height on a box of text without letting it grow; write the size in CSS instead, or multiply it by var(--rs-text, 1).

No accent bars on rounded boxes

A coloured stripe down one edge of a box with rounded corners curves around the corners and looks off. Don’t use border-left or an inset left shadow as an accent on anything rounded. Show state with a thin tinted outline (box-shadow: inset 0 0 0 1px color-mix(in srgb, <colour> 55%, transparent)), a soft tinted background, or a small dot or icon. Straight table rows may keep a straight edge.

F1YAML, checked by schema

Data lives in data/, a folder per kind of thing, each checked by the JSON Schema (2020-12) that schemas/registry.yaml names. The Keia framework’s core schemas are pinned and never edited; Keia Atlas’s own ideas go in schemas/ext/. Change the schema first, then the data.

• Why a copy that passes the same schemas can exchange data with any other.
• Do describe every field in the schema.
• Don’t put data in a page or a component.

F2Checks stop the build

npm run validate checks every file and cross-checks references: cables fit both ends, no port is used twice, enough outlets, unique serials and asset tags. Then npm test and npx astro build. It also reports standards coverage: every must rule in data/standards/ names how it is proved (record: a field, on-site or connect), and the report lists each rule whose field no record carries, so a rule is never written that no page can show (tools/coverage.mjs).

• Why a wrong fact caught at build time never reaches a technician.
• Do run all three before committing.
• Don’t skip a failing check.

F3Every fact has a source

Sources live in data/sources/ with a last_verified date; a model says which source provides what. Unknown is a valid answer, recorded under gaps; a guess is not.

• Why people trust what they can check.
• Do say “Unknown” and why.
• Don’t fill a gap with a typical value.

F4Real where public, made up where private

Device facts and space guidelines are public and cited. The company, sites, people, serials and incidents are made up.

• Why the open version must be safe to publish.
• Do follow the demo’s naming (trees for buildings, birds for spaces).
• Don’t copy anything from a real building or company.

F5Retire, don’t remove

A record no longer current gets a retired or archived status with a date and reason; its file stays.

• Why refresh plans and audits need the history.
• Do keep old models and old installs.
• Don’t delete a file to shorten a list.

F6Reshape data with a migration you keep

When the model changes (two phases become one, anonymous groups become one space each), a one-off script in tools/migrations/, named by date, rewrites the data. Run it once, commit its output with it, and keep the script.

• Why a reviewer can see how every file changed and why, and nothing is typed in by hand.
• Do keep every fact the old shape held (dates, summaries, sign-offs, asset tags), and say in the script where each went.
• Don’t hand-edit a hundred files, or delete the script once it has run.

F7Home offices are spaces, never people’s addresses

Each home office is a space at its region’s remote site, labelled by town and number, with its country and nearest office. A person’s base links to it.

• Why the schedule needs to know who is at home and where their kit is; nobody’s address belongs in Keia Atlas.
• Do “Bray home office 1”, near the Dublin office.
• Don’t a street, an eircode or a person’s name in a space name.

F8A manufacturer’s known error stays the manufacturer’s

Known errors (data/known-issues/, decision 0029) keep what the manufacturer published: its reference, models, versions, fix and source. Anything Aigna adds says so: a workaround the manufacturer didn’t publish is from: aigna, a reading of an unclear version list goes in affected_note, and a made-up feed or issue says demo: true and cites a demo source (the checks refuse a mix). Matching an incident or raising a case with the manufacturer is always a person’s decision, recorded with who and when.

• Why a service manager quotes a known error to the manufacturer and to the team; it must be exactly what the manufacturer said, and Keia Atlas’s guesses must never look like the manufacturer’s words.
• Do “Poly lists this as fixed in 5.0.1 and doesn’t say which earlier versions have it. Aigna reads it as every version before 5.0.1.”
• Don’t invent a manufacturer reference, a workaround or a fixed version, or close, link or send anything without a person.

F9Made-up buildings say so, and use no real names

Floor plans, trays, cable runs and circuits (data/floors/, data/runs/, data/circuits/) are invented for the demo, so every floor carries the label in FICTION (src/lib/floors.mjs): “Fictional floor plan: space sizes from the space types; layout, trays and cable lengths made up for the demo.” Every map and 3D model shows it, and the checks fail a floor file without it. Labels on made-up things are generic: providers are “Carrier One” and “Carrier Two”, never a real company; buildings have no street address; serials start DEMO-.

• Why a plan that looks real is easy to mistake for a survey; the label and generic names keep the demo honest and keep real companies’ names off made-up faults.
• Do space sizes from the space types, within their area range; “Carrier Two (secondary, north duct)”; a circuit’s bandwidth, ID, service level and support desk made up for the demo and marked demo: true, with a desk and an account reference, never a person or a phone number.
• Don’t a real provider’s name, a real building’s address, or a floor plan without the label.

F10Every fact carries a label, and the label decides who sees it

Four labels. Public: facts about models (ports, drawings, datasheets, space types, manufacturers’ known errors). Internal: facts about Aigna that staff may see (rooms, units, incidents, projects, budgets). Restricted: facts about Aigna’s buildings that would help an attacker: floor plans, camera and door-controller positions, IP plans and VLANs, racks and switch ports, the vulnerable-firmware list (units matched to a manufacturer’s known error), who at a vendor can reach Aigna’s systems, and whether a unit still has its default password. Secret: credentials and break-glass details, which never sit in data/, only the name of a vault entry (the secret check in tools/secrets.mjs).

Each folder’s default label is classification in schemas/registry.yaml. A field more sensitive than its folder carries x-classification: Restricted in its schema (install units’ default_password_changed, vendors’ people). Views worked out from several folders are listed in RESTRICTED_VIEWS (src/lib/classification.mjs). Wherever Restricted content shows, the page shows a small “Restricted: floor plan” label beside it (src/components/Restricted.astro).

• Why the model catalogue is open and shared, but a building’s plan, addresses and weak spots are a map for an attacker (ISO 19650-5). The label on the schema means each new folder or field is classified when it is made.
• Do give every new folder a label in the registry; label a new sensitive field in its schema; put the Restricted label beside any new view of Restricted facts. Keep a repository that describes real offices private.
• Don’t label a folder Secret (the validator refuses it), or publish a real building’s plan, camera positions or addresses, even from a friendly site.

F11Sensing devices carry a privacy record; models carry their security support

Every installed camera, microphone, video bar, codec, desk video device and door or CCTV device is covered by exactly one privacy record in data/privacy/ for its class and site: what it captures, whether it identifies people, purpose, lawful basis, DPIA reference, room notice (and where), retention, the works-council agreement (required where the country has works councils) and the approver. Occupancy is counted per room with a minimum group size; per-person views are off, and turning them on needs a logged decision. The unit page shows the record, and “What Keia logs about users” (linked from About) says what Keia Atlas keeps about its own users.

Every installed model with firmware worth attacking (anything networked, and every camera and microphone) has security_support: its firmware line, the end of security updates and the manufacturer’s vulnerability contact. A date or page the manufacturer published cites its source in data/sources/; anything else says demo: true and the page says “Demo value”. Units record default_password_changed once someone has checked. The unit and model pages warn from 12 months before support ends.

• Why the GDPR, works councils, the EU Cyber Resilience Act and the UK PSTI rules all ask for these records; keeping them beside the device means they are there when someone asks.
• Do “Security support ends Jun 2027”; “Counted per room, never per person”; “not legal advice”.
• Don’t say a device or Aigna is “compliant”, call aggregated counts “anonymous”, or invent a manufacturer’s support date or contact without marking it as a demo value.

F12The demo’s dates move with today; real facts never do

The demo’s records are written as of one day, the anchor (demo_anchor in data/house-values/). With demo_clock: rolling (Aigna’s demo only), each build moves every date inside the demo world forward by the whole weeks between the anchor and the build date, when the data is loaded (src/lib/demo-clock.mjs); the YAML files never change. The story stays the same (the 3.09 fault is still “today 07:52”, PRJ-14 is on the same step, a warranty still ends in 10 months) and weekdays are kept. Pages rebuilds every Monday at 03:00 UTC, so the live demo stays current. A real organisation leaves demo_clock out, and its dates never move.

Which dates move is an allow-list, DATE_FIELDS in src/lib/demo-clock-core.mjs, per folder and field path: shift (a demo date: by whole weeks), fy (the year plan’s bounds, its quarterly reviews and freezes, and the planning years: by whole financial years, and only once today has crossed into another one), year (the work plan’s horizon: by calendar years) or fixed (a real-world fact, a connector’s own record, or when this repository’s public files were written). The validator fails any date-like field that is on neither list.

Registering a new folder. Add the folder (or folder/sub-folder) to DATE_FIELDS with the path of every date field: dotted keys, [] for any item of a list, * for any key of a map and ** for any path below (positions[].units[].warranty.ends, rooms.*.hearing_loop.tested). A made-up record’s date is shift; a date someone outside Aigna published (a release, an end of support, a standard taking effect, a citation) is fixed. Then run npm run validate: it names any date you missed, with its file and line. A date written in JavaScript for the demo goes through demoShift(); a page script that needs today reads document.documentElement.dataset.demoToday, never its own clock’s date.

• Why a demo that looks three months old reads as abandoned, and a real fact that moved would be a lie.
• Do check a change with DEMO_BUILD_DATE=2026-12-28 npm run build (13 weeks on) as well as the plain build, and read a few pages.
• Don’t move a date by editing the YAML, put a demo date in prose (“on 12 September”) where a field could carry it, or mark a real fact shift to make a page read better.