Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.1.0 Last Updated: 2026-04-18 Status: Active Target Audience: Platform Foundation, Design System maintainers, AI agents

​
Purpose

This document defines the source-of-truth policy and synchronization workflow for UI design tokens used by:
  • Encore Health OS application runtime (/workspace/src/index.css)
  • Encore design system site/library (encoredesign-lovable)
  • Documentation and implementation guides
The goal is to prevent token drift and preserve visual parity across products.
What changed in v1.1.0 (2026-04-18): Added the Tri-Source Parity Contract documenting the three independent palettes that must stay in sync (src/index.css, PF-95 DEFAULT_THEME_COLORS, edge PLATFORM_DEFAULTS). Added the Deprecated / Reserved Tokens table (encore brand, unused module short codes, legacy module aliases, --duration-base). Added the Audit Scripts section. Token catalog cross-references the new Token Catalog Reference in SEMANTIC_COLORS.md v1.4.1.

​
Canonical Source of Truth

The canonical source for token values is the design system token contract in:
  • encoredesign-lovable/src/styles/theme.css
  • encoredesign-lovable/src/app/utils/token-generator.ts
Encore Health OS must consume and mirror these canonical values for agreed token families. The runtime authority within this repository is src/index.css — when this document and runtime values diverge, treat src/index.css as ground truth and update both this document and the canonical design-system source. The complete token inventory lives in SEMANTIC_COLORS.md § Token Catalog Reference. Avoid re-listing every token here; this document defines governance.

​
Token Families and Lock Levels

​
Hard-Locked (must match canonical exactly)

  • Core surfaces: --background, --card, --card-elevated, --border, --popover
  • Brand & action: --primary, --primary-hover, --primary-foreground, --accent, --accent-hover, --accent-foreground
  • Status: --success, --success-subtle, --success-foreground; --warning, --warning-subtle, --warning-foreground; --info, --info-subtle, --info-foreground; --destructive, --destructive-hover, --destructive-foreground
  • Typography: --font-display, --font-body, --font-mono
  • Radius base: --radius
  • Motion durations/easings: --duration-*, --ease-*
  • Module colors (active 12 short codes): --module-pf, --module-cl, --module-pm, --module-fm, --module-rh, --module-it, --module-hr, --module-lo, --module-ce, --module-fa, --module-gr, --module-fw (each with -hover and -subtle)

​
App-Local (can diverge with explicit justification)

  • Product-specific chart palettes: --chart-1 … --chart-8 (light + dark)
  • Sidebar slot: --sidebar-* (PF currently owns these; PF-95 v2 may expose them)
  • Device/safe-area/layout sizing tokens: --mobile-*, --safe-area-*, --app-header-height, --mobile-header-height, --mobile-nav-height, --dock-height
  • Component-specific tokens: --overlay-scrim, --shimmer-highlight, --ai-accent, --glass-bg, --glass-border, --glow-opacity, --focus-ring-offset-color
  • Reserved module short codes: --module-th, --module-qo, --module-da, --module-rpt (pre-allocated; not in canonical until activated)
  • Encore brand tokens: --encore-navy, --encore-slate, --encore-teal, --encore-teal-light, --encore-teal-mid, --encore-gray, --encore-light, --encore-gold (marketing surfaces)
Any app-local divergence from canonical for a hard-locked family must be documented in the “Local Overrides” section of this file.

​
Token Aliases

The following semantic tokens intentionally alias to another token’s value. They serve different semantic roles but share the same visual output for design cohesion.
TokenResolves ToRationale
--color-secondaryhsl(var(--card-elevated))Secondary surfaces use the elevated card color for subtle visual hierarchy
--color-mutedhsl(var(--muted))Muted backgrounds use the --muted scale (slightly distinct from elevated card in light mode)
--color-secondary follows --card-elevated (near-white in light mode, elevated slate in dark). --color-muted follows --muted (cool gray in light, darker slate band in dark) so de-emphasized chrome reads differently from secondary interactive surfaces. Tailwind mappings live in src/index.css @theme inline.
Known limitation: PF-95’s colorSecondary field writes to the raw --secondary HSL var, but the Tailwind utility bg-secondary resolves to --card-elevated via the alias above. Tenants who customize colorSecondary will not see bg-secondary consumers update. This is documented in SEMANTIC_COLORS.md § Tenant Theming Mapping Table. A future PF-95 v2 will reconcile this.

​
Tri-Source Parity Contract

The same semantic palette is duplicated across three sources for different runtime contexts. They MUST stay in sync.
SourceFileFormatUsed by
Runtime (browser)src/index.css — :root and .dark blocksHSL strings (H S% L%)All app code via Tailwind v4 @theme inline
Tenant theming UI default (PF-95)src/platform/theming/types.ts — DEFAULT_THEME_COLORSHEX (#RRGGBB)BrandingSettingsPage, ColorsTab, pf_tenant_themes row defaults
Edge function fallback (PF-91-EN-01)supabase/functions/_shared/compliance-contrast.ts — PLATFORM_DEFAULTSHEX (#RRGGBB)generate-compliance-evidence and other Deno functions that need to render branded compliance exports

​
Parity rules

  1. Same semantic palette: All three sources MUST resolve to the same color for each semantic role: colorPrimary ≡ --primary, colorAccent ≡ --accent, colorBackground ≡ --background, colorSurface ≡ --card-elevated, colorText ≡ --text-main, colorTextMuted ≡ --text-muted, colorDestructive ≡ --destructive, colorSuccess ≡ --success, colorWarning ≡ --warning (HSL→HEX conversion permitted with ΔE-CIE76 tolerance ≤ 3 for rounding).
  2. HEX must match exactly between DEFAULT_THEME_COLORS and PLATFORM_DEFAULTS for the same field.
  3. Validated by: npm run audit:token-parity (planned, see Audit Scripts below).
  4. Update workflow (any change to a hard-locked token): update src/index.css first, then update both HEX copies in the same PR, then run npm run audit:token-parity --strict and npm run validate.

​
Synchronization Workflow

  1. Update canonical tokens in encoredesign-lovable.
  2. Generate/export token artifacts via design system generator utilities if changed.
  3. Mirror into app in one scoped PR:
    • update src/index.css :root and .dark values (HSL),
    • mirror the change into DEFAULT_THEME_COLORS (HEX) in src/platform/theming/types.ts,
    • mirror the change into PLATFORM_DEFAULTS (HEX) in supabase/functions/_shared/compliance-contrast.ts,
    • preserve alias compatibility where needed.
  4. Run validation:
    • npm run typecheck
    • npm run lint
    • npm run build
    • npm run audit:hardcoded-colors
    • npm run audit:token-parity (planned)
    • targeted browser visual regression (light/dark, desktop/mobile)
  5. Update docs/version metadata:
    • docs/development/SEMANTIC_COLORS.md (re-run any embedded HSL examples)
    • docs/development/UI_UX_STANDARDS.md (only if semantic-status section changes)
    • docs/VERSIONS.md
  6. Record evidence in spec/task logs when part of a scoped initiative.

​
Backward Compatibility and Deprecation

  • Introduce aliases first, then migrate consumers.
  • Maintain aliases for at least one release cycle when feasible.
  • Remove deprecated aliases only after:
    • consumer sweep confirms no references remain (rg against src/),
    • visual regression pass is complete,
    • docs are updated.

​
Deprecated / Reserved Tokens

Tokens that are declared but not actively consumed by product UI today. Consult before removing or repurposing.
Token familyStatusNotes
--encore-navy, --encore-slate, --encore-teal, --encore-teal-light, --encore-teal-mid, --encore-gray, --encore-light, --encore-goldReserved (marketing only)Currently 0 consumers in src/ outside index.css. Reserved for marketing surfaces (login chrome, brand splash, PDF letterheads, marketing emails). Do not use in product UI without DS owner approval.
--module-th, --module-qo, --module-da, --module-rpt (each with -hover, -subtle)Reserved (future modules)Pre-allocated for future modules. 0 consumers today. Adding a consumer requires (a) confirming the short code maps to a real module in MODULE_REGISTRY, and (b) updating SEMANTIC_COLORS.md § Module Identity Tokens.
--module-clinical, --module-finance, --module-operations, --module-people (each with -hover, -subtle)Deprecated aliasUse the short-code form (--module-cl, --module-fa, --module-fw, --module-hr). 0 consumers today. Will be removed in next DS major release.
--duration-baseDeprecated aliasUse --duration-normal (300ms). Kept for backward compatibility during the DS v3.0 transition.

​
Removal procedure

To remove any token in this table:
  1. Re-grep to confirm 0 consumers: rg --no-heading -F "module-clinical" -- src/ (or token name).
  2. Remove from :root, .dark, and @theme inline blocks of src/index.css.
  3. Remove from canonical encoredesign-lovable source if present.
  4. Update this section noting removal date and PR.
  5. Bump DESIGN_TOKEN_SYNC_POLICY.md minor version.

​
Audit Scripts

ScriptPurposeStatusWired into
npm run audit:hardcoded-colorsFlags Tailwind palette literals (text-red-500), bg-black/text-white escapes, and hex literals outside legitimate paths✅ ActiveAlready gated in CI via validate:governance → npm run audit:hardcoded-colors:strict
npm run audit:token-parityVerifies :root HSL values in src/index.css match the HEX defaults in DEFAULT_THEME_COLORS and PLATFORM_DEFAULTS🔨 Planned (color-system review Phase 4.1)Will gate CI under validate:governance
npm run audit:dead-tokensReports CSS vars declared in :root with 0 consumers in src/🔨 Planned (color-system review Phase 4.3)Informational only
The hardcoded-colors auditor reads an allowlist (scripts/utils/.audit-color-allowlist.json) for legitimate exceptions (PDF generators, picklist hex presets, chart fallbacks). Add new exceptions there with a reason and owner — do not relax the audit script itself.

​
Local Overrides

Current approved local overrides:
  • None.
If a local override is added, document:
  • token name,
  • reason,
  • owner,
  • expected removal/reconciliation date.

​
Ownership

  • Canonical owner: Design system maintainers (encoredesign-lovable)
  • App mirror owner: Platform Foundation (/workspace/src/index.css)
  • Tenant theming owner: Platform Foundation (PF-95 — src/platform/theming/)
  • Compliance theming owner: Platform Foundation (PF-91-EN-01 — src/platform/compliance/, _shared/compliance-contrast.ts)
  • Documentation owner: Platform Foundation docs maintainers

​
References