Design System

v1.1

MyLife OS · Source-of-truth map · 2026-05-06 · Interaction Design Guide

This is the canonical reference. Any other doc, stub, or page that describes the design system is non-canonical. If you find drift, update the source artifact (listed below), not a mirror.

Source-of-Truth Map

One canonical artifact per layer. Subordinate docs and tooling may reference these but never replace them.

🎨

Token Layer

Runtime: assets/theme.css · Human reference: Platform Design Tokens Guide (Drive)

REQUIRED

All --ml-* CSS custom properties. Modules consume tokens — never raw hex values.

Token group	Version	Example
Core palette (primary, danger, warning, success)	v1.0	--ml-primary, --ml-danger
Surface (bg, card, border, text1–text3)	v1.0	--ml-bg, --ml-card, --ml-border
Spacing, radius, shadow, nav-height	v1.0	--ml-radius, --ml-shadow
Font scale (fs-xs → fs-2xl)	v1.0	--ml-fs-xs, --ml-fs-xl
Brand color scales (indigo, teal)	v1.1	--ml-indigo-50 … --ml-indigo-900
Neutral scale (ink, paper)	v1.1	--ml-ink-100 … --ml-ink-900, --ml-paper
Type system (font-body/display/mono, text-xs→5xl, leading-*)	v1.1	--ml-font-body, --ml-text-lg
Spacing scale (space-1 → space-20)	v1.1	--ml-space-4 (= 1rem)
Radius scale (sm/md/lg/xl/pill)	v1.1	--ml-radius-md
Shadow scale (xs/sm/md/brand)	v1.1	--ml-shadow-md
Status colors (active/pending/error/info/inactive)	v1.1	--ml-status-active-bg, --ml-status-active-fg
Sensitivity governance (public/unknown/pii/phi)	v1.1	--ml-sens-phi-bg, --ml-sens-phi-fg
State tokens (staged/stale/locked/readonly/degraded)	v1.1	--ml-state-staged-bg, --ml-state-staged-ring
Tags (green/blue/purple/amber/rose/teal)	v1.1	--ml-tag-green-bg, --ml-tag-green-fg
Z-index scale	v1.1	--ml-z-modal, --ml-z-toast
Touch targets & density	v1.1	--ml-touch-min (44px), --ml-touch-rec (48px)
Breakpoints	v1.1	--ml-bp-sm (640) / md (900) / lg (1200) / xl (1600)
Animation	v1.1	--ml-ease, --ml-duration-fast/base/slow

Rule: Use var(--ml-*) tokens in Styles.html. Never use raw hex values or hardcoded px sizes for color, spacing, or typography.

🧩

Component Layer

CSS: assets/base.css · JS API: assets/components.js → MyLifeComponents

REQUIRED

Structural component CSS (base.css) and the JS constructor API (components.js). Both must be loaded.

JS Components (`MyLifeComponents.*`)

confirm(opts) — modal with focus trap, Esc, typed-ID gate
emptyState(id, opts)
statCard(opts) → HTML
statRow(id, stats[])
progressRing(opts) → HTML
filteredList(id, opts)
dataTable(id, opts)
badge(text, variant, opts)
skeleton(id, opts)
checkboxDropdown(id, opts)

CSS-Only Components (base.css)

.btn / .btn-primary / .btn-danger
.ml-btn--primary/secondary/ghost/danger
.ml-badge--active/pending/error/info
.ml-badge--sens-phi/pii/public/unknown
.ml-tag--green/blue/purple/amber/rose/teal
.ml-card
.ml-stat-row / .ml-stat-card
.ml-data-table
.ml-data-card-list (mobile fallback)
.ml-filter-bar
.ml-pagination
.ml-alert--warning/error/success/degraded
.ml-skeleton-line / .ml-skeleton-card
.ml-empty-state
.ml-confirm-overlay (CSS shell; use JS confirm())
.ml-progress-ring

Rule: Use MyLifeComponents.confirm() for all confirmation dialogs — never hand-roll. The JS function implements the full accessibility contract (focus trap, Esc, typed-ID gate, cancel-default focus).

⚙️

Operational Patterns Layer v1.1

CSS: assets/patterns.css (CSS-only, no JS)

OPTIONAL

Include when your module renders any of these patterns. Requires theme.css + base.css loaded first.

.ml-queue-list / .ml-queue-item
.ml-queue-icon--review/error/comm/doc
.ml-timeline / .ml-timeline-item--success/error/staged
.ml-split-review / .ml-split-pane
.ml-diff-old / .ml-diff-new
.ml-empty (4 canonical variants)
.ml-degraded-card / .ml-degraded-code
.ml-confirm / .ml-confirm-scrim (CSS base; use JS API)
.ml-approval / .ml-approval-head/diff/sign
.ml-case / .ml-case-head/body/events/aside

Include patterns.css when: module shows a queue/inbox, audit timeline, document split review, approval workflow, or case workspace. If you're only using base component styles (buttons, badges, cards), you do not need patterns.css.

📐

Page Template Layer v1.1

CSS: assets/templates.css (CSS-only, no JS)

OPTIONAL

7 canonical page-shell layouts. Requires theme.css + base.css + patterns.css loaded first.

.ml-tmpl-profile-* (entity profile — domain_app)
.ml-tmpl-queue (review queue with saved views)
.ml-case-* (case workspace — task-engine)
.ml-tmpl-dashboard-* (dashboard)
.ml-tmpl-registry-* (registry view — admin)
.ml-tmpl-doc-review (document review — admin)
.ml-tmpl-audit-body (audit / timeline page)

Include templates.css when: module uses one of the 7 canonical layout shells. Most modules do not need templates.css — they compose layouts from base.css components directly. Only use a template shell if the module's primary view matches one of the canonical page types above.

Required Load Order

Every module Index.html must load assets in this sequence. Comments indicate when optional assets apply.

<link rel="stylesheet" href="CDN/assets/v2/theme.css">
<link rel="stylesheet" href="CDN/assets/v2/base.css">






<script src="CDN/assets/v2/platform.js"></script>
<script src="CDN/assets/v2/utils.js"></script>
<script src="CDN/assets/v2/components.js"></script>
<script src="CDN/assets/v2/state.js"></script>
<script src="CDN/assets/v2/auth.js"></script>

Conformance Rules

Rule	Rationale
Use `var(--ml-*)` tokens — never raw hex	Enables dark mode / theme rebrand without touching modules
Use `MyLifeComponents.confirm()` for all modals	Enforces a11y contract (focus trap, Esc, cancel-default)
Load CDN via `/assets/v2/` path	Versioned delivery; legacy `/assets/` path is deprecated
CSS before JS in load order	Prevents FOUC and class-not-yet-defined JS errors
No `@import` for Google Fonts	theme.css already loads Fraunces, Inter, JetBrains Mono from CDN
Only use breakpoints in {600, 640, 900, 1200, 1600} px	Matches `--ml-bp-sm/md/lg/xl` token values; unsupported values create inconsistent layouts
Interactive targets ≥ 44px in both dimensions	Matches `--ml-touch-min`; required for mobile usability
Do not duplicate pattern/template classes in Styles.html	Load patterns.css instead; local reimplementations drift from platform
Prefix module-local classes: `.module-id-*`	Prevents collision with CDN class names

Golden Examples

One exemplar module per template type. Builders should reference these when implementing a new view of that shape. Marked PILOT when the module is the recommended migration target for that template.

Template	Golden module	What it shows
`.ml-tmpl-profile-*` entity profile	`client-profiles` PILOT modules/domain/client-profiles	Entity sidebar + tabbed detail view, document panel, related-records list. First migration target for the profile shell.
`.ml-tmpl-queue` review queue	`scheduler-review` modules/domain/scheduler-review	Inbox of items needing operator action — saved views, bulk-select toolbar, single-row detail.
`.ml-case-*` case workspace	`tasks` PILOT modules/domain/tasks	Single-instance workspace: head + body + events timeline + aside. Used for work-OS instances.
`.ml-tmpl-dashboard-*` dashboard	`jarvis` modules/dashboard/jarvis	Stat-row + cards layout with at-a-glance numbers and entry points to other modules.
`.ml-tmpl-registry-*` registry view	`voice-agent-admin` modules/admin/voice-agent-admin	Sheet-row table editor with inline edit, version history, publish/rollback controls.
`.ml-tmpl-doc-review` document review	`staff-docs` modules/domain/staff-docs	Document classifier output + extracted-fields panel + accept/reject controls.
`.ml-tmpl-audit-body` audit / timeline	`system-overview` modules/dashboard/system-overview	Timeline of platform events with severity filters, correlation drill-down, governance flags.

Note: Today, none of the modules above fully consume templates.css classes — they are the recommended migration targets, not yet conformant. As each module migrates, this table will be updated to reflect actual conformance. Run scripts/ds_audit.py to see current state.

Audit

Run the conformance audit to check all modules against this contract:

python3 scripts/ds_audit.py
python3 scripts/ds_audit.py --json # machine-readable

Governance

Artifact	Location	Update via
theme.css (token definitions)	platform/platform-assets/assets/	PR + CDN deploy
base.css (component CSS)	platform/platform-assets/assets/	PR + CDN deploy
patterns.css	platform/platform-assets/assets/	PR + CDN deploy
templates.css	platform/platform-assets/assets/	PR + CDN deploy
components.js (JS API)	platform/platform-assets/assets/	PR + CDN deploy
manifest.json (asset registry)	platform/platform-assets/assets/	Updated with each CDN asset change
ORGANIZATION.md (load order, conventions)	platform/platform-assets/	Updated when contract changes
Platform Design Tokens Guide	Drive: MyLife OS / Documents / Governance	Updated when token semantics change
This page (design-system.html)	platform/platform-assets/pages/	Kept in sync with above; non-canonical docs redirect here

MyLife OS Design System v1.1 · Updated 2026-05-06 · Phase DS1