Atlas + SFMS — Design & UX Specification

Companion to docs/engineering/ · Status: v1.0 · Owner: Design Lead Audience: Designers, frontend engineers, Product Owner, QA (accessibility)

This folder is the design and user-experience source of truth for the Atlas Data Platform + SFMS. The engineering plan (docs/engineering/Phase_*.md) describes what the system does and how it is built; this folder describes how it feels to use and how it looks. Every product screen built in Phases 2–8 must trace back to the personas, journeys, information architecture, and design system defined here.

It exists because the engineering plan is deliberately UI-light — it owns architecture, data, and contracts. The UX layer is owned here, and is a hard gate input to Phases 1, 2, 4, 5, and 8.

1. Why this matters

Atlas competes on two axes that are experience-first, not feature-first:

A facility manager must trust the data at a glance. Dashboards, KPI cards, and alerts are read in 2–5 second bursts on a wall display or a phone between site visits. If the hierarchy of information is wrong, the product fails even with perfect data.
A technician must complete work on a phone, often offline, often gloved, often in a plant room with bad light. Touch targets, contrast, and offline clarity are not polish — they are the core loop.

Good architecture is invisible. Bad UX is the only thing the customer sees. This spec makes UX a first-class, gated deliverable rather than an afterthought layered onto finished screens.

2. Document index

File	Purpose	Primary consumers	Gate input
`00_README.md`	This file — design principles, index, process	All	—
`UX_personas.md`	Who we build for; goals, pains, contexts, devices	Product, Design, Eng	G1
`UX_journeys.md`	End-to-end journey maps for the critical loops	Product, Design, QA	G1
`information_architecture.md`	Navigation model, screen inventory, URL map, drill-through	Frontend, Product	G1, G2
`design_system.md`	Tokens, components, theming, motion, density, iconography	Frontend, Design	G0, G2, G5
`UX_patterns.md`	Interaction patterns, state matrix, accessibility, responsive, content/voice	Frontend, QA, Design	G2, G4, G5, G8
`wireframes/anchor_screens.md`	Lo-fi structural wireframes for the 6 anchor screens	Product, Design, Eng	G1

3. Design principles (the ten we hold each other to)

Glanceable first. The most important number on any screen is legible from 3 metres (TV mode) and from arm's length on a phone. Default to large type for primary metrics, quiet type for chrome.
One primary action per screen. Every screen answers "what is the one thing the user came here to do?" That action is the most prominent, thumb-reachable element. Everything else is secondary.
Show state, never a dead end. Every surface has explicit loading, empty, error, partial, offline, and no-permission states. A blank screen is a bug (see UX_patterns.md §State Matrix).
Progressive disclosure. Lists → detail → drawer → edit. Power lives one level deeper than the default; the default is calm.
The data is the design. Charts, KPI cards, and maps use the theme token palette only — no decorative colour. Colour carries meaning (semantic) or brand, nothing else.
Trust through transparency. AI answers cite sources. Audit is visible. Workflow runs show every step. Offline submissions show their sync state. The user always knows why and whether it saved.
Mobile is a primary target, not a shrink. The technician flow is designed phone-first; desktop is the richer sibling. We never ship a desktop screen and "make it fit later."
Theme-able to the core. Light, dark, and per-tenant brand are equal citizens. No hard-coded colour ever ships (lint-enforced). A tenant's brand applies in < 1 frame on load.
Accessible by construction. WCAG 2.2 AA is the floor, checked in CI (axe) and by manual screen-reader passes. Keyboard parity with mouse on every interactive surface. 44px minimum touch targets.
Fast is a feature. Perceived performance (skeletons, optimistic UI, instant theme switch) is designed, not hoped for. Budgets in UX_patterns.md are gate conditions, not aspirations.

4. How design plugs into the SDLC phases

Phase	Design deliverable owed	Design gate condition
P0 Foundation	Token contract + base component visual spec proven in Storybook (light/dark).	Tokens match `design_system.md`; both themes render.
P1 Requirements	Personas, journeys, IA, and lo-fi wireframes for the 6 anchor screens approved.	Product Owner signs personas + journeys + wireframes (AC1.3).
P2 Core Platform	Hi-fi design of the app shell (nav, command palette, theme/tenant switch, admin screens).	Shell matches IA + design system; a11y axe clean.
P4 SFMS Modules	Hi-fi flows for asset, work-order lifecycle, ceiling-plan, mobile work-order.	Every new screen passes the state matrix + a11y + i18n.
P5 Dashboards	Editor UX, widget visual catalogue, three view modes, theme tiers.	Visual regression baseline per widget × theme (Chromatic).
P8 Mobile/PWA	Mobile patterns: bottom nav, sticky actions, swipe, offline, capture.	Lighthouse ≥ 90, touch targets, offline UX field-tested.

Design reviews are part of the phase gate, signed by the Design Lead alongside the Engineering Lead.

5. Design-ops: how design and code stay in sync

Single token source. Design tokens live as CSS variables (design_system.md §Tokens), consumed by Tailwind and by Figma via a synced token set. The CSS variables are canonical; Figma mirrors them.
Storybook is the contract. Every base component and every dashboard widget has a Storybook story with light/dark/brand previews and all interaction states. "Done" means the story exists and matches the spec.
Visual regression as a design gate. Playwright/Chromatic snapshots per component × theme. A visual diff is a required review, not a silent pass.
No hex in components. A lint rule bans raw #hex/rgb() outside the token files (Phase 5 risk mitigation). Colour only ever comes from a token.
Figma ↔ code handoff. Designers annotate against token names and component props, never pixel values. Engineers implement against the same names.

6. Reading order

New designer or PM: UX_personas.md → UX_journeys.md → information_architecture.md → wireframes/anchor_screens.md.
New frontend engineer: design_system.md → UX_patterns.md → information_architecture.md.
QA / accessibility: UX_patterns.md (state matrix + a11y) → UX_journeys.md (what to test end-to-end).