Prism Design System Specification

Version: 1.0 Platform: Commercial Real Estate Intelligence Stack: React 19, Mantine 7, MapLibre GL, ECharts, TanStack Router/Query/Table

Migration Notes

This specification targets the following changes from the current codebase:

A. Design Token Table

A.1 Color Tokens — Neutrals

A.2 Color Tokens — Structural & Action

A.3 Color Tokens — Semantic

A.4 Color Tokens — Interaction States

A.5 Color Tokens — Chart Palette

A.6 Color Tokens — Map Layer Palette

B. Typography System

B.1 Font Stack

font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;

Enable OpenType features for tabular numerals:

.tabular-nums {
  font-variant-numeric: tabular-nums lining-nums;
  font-feature-settings: 'tnum' 1, 'lnum' 1;
}

Apply .tabular-nums to: KPI values, table numeric cells, chart axis labels, stat bars, pagination counts.

B.2 Type Scale

B.3 Hierarchy Rules

1. Size and weight establish hierarchy before color.
2. Do not use color alone to distinguish heading levels.
3. Maximum three weight levels on any single page: 400, 500/600, 700.
4. Uppercase is reserved for: table column headers (captionStrong) and overlines.
5. No italic usage in the interface except user-generated content.

C. Spacing, Radius, Density

C.1 Spacing Tokens

C.2 Radius Tokens

C.3 Border Specification

Borders are the primary visual separation mechanism. Shadows are not used for cards or sections.

C.4 Shadow Tokens

No other shadows. Cards, panels, and sections use borders only.

C.5 Density Modes

Two modes: Comfortable (default) and Compact. Toggle available on Explore and Operations pages.

Implementation Strategy

Density is managed via a CSS class on the content area and a React context:

// DensityContext.tsx
type Density = "comfortable" | "compact";
const DensityContext = createContext<{
  density: Density;
  setDensity: (d: Density) => void;
}>({ density: "comfortable", setDensity: () => {} });

CSS applies via [data-density="compact"] attribute on the page wrapper:

[data-density="compact"] .prism-table tbody tr { height: 32px; }
[data-density="compact"] .prism-table tbody td { padding: 4px 12px; font-size: 13px; }
[data-density="compact"] .mantine-TextInput-input { height: 30px; font-size: 13px; }
[data-density="compact"] .mantine-Button-root[data-size="sm"] { height: 26px; }
[data-density="compact"] .mantine-Button-root[data-size="md"] { height: 30px; }
[data-density="compact"] .mantine-Card-root { padding: 12px; }

Persist density preference per-page to localStorage under prism:density:{pageKey}.

D. Layout Grid System

D.1 Container Specification

D.2 Grid System

12-column grid using Mantine SimpleGrid and Grid components.

Common Layouts

D.3 Breakpoints

D.4 Collapse Behavior

D.5 Alignment Rules

• Charts and tables always align to the same left edge within a card or section.
• Map components are always full-width within their container (no internal margin).
• Form fields in two-column layout use equal-width columns; labels are above inputs, never side-by-side.
• KPI cards in a row all have equal height (Mantine Grid with grow).
• Tables span full card width with no internal horizontal padding beyond cell padding.

E. Z-Index & Layering Model

E.1 Z-Index Scale

E.2 MapLibre Layering Rules

MapLibre renders its own canvas at z-index 0. UI elements that overlay the map must:

1. Use position: absolute or position: fixed relative to the map container.
2. Set pointer-events: none on overlay containers; pointer-events: auto on interactive children.
3. Never use z-index values that conflict with Mantine's internal popover stack (Mantine popovers use z-index 300 by default — override via theme to 600).

Map controls (zoom, layer toggles, legend) sit at z-index 100 within the map container's stacking context. Since the map container creates its own stacking context, these values don't conflict with page-level z-indices.

E.3 Mantine Z-Index Overrides

// In Mantine theme
{
  other: {
    zIndex: {
      dropdown: 600,
      drawer: 700,
      modal: 801,
      tooltip: 900,
      notification: 1000,
    }
  }
}

Override via component defaultProps:

Popover: { defaultProps: { zIndex: 600 } },
Select: { defaultProps: { comboboxProps: { zIndex: 600 } } },
Modal: { defaultProps: { zIndex: 801 } },
Drawer: { defaultProps: { zIndex: 700 } },
Tooltip: { defaultProps: { zIndex: 900 } },
Notifications: { defaultProps: { zIndex: 1000 } },

F. Shell Architecture

F.1 Sidebar

F.2 Topbar

Breadcrumb Specification

• Font: font.size.caption (12px), color color.text.secondary
• Separator: / character, color color.text.muted
• Current page: font.size.body (14px), weight 600, color color.text.primary
• Breadcrumb and title stack vertically in a single line-height-adjusted container

Global Search Trigger

F.3 Command Launcher

G. Interaction Pattern Standards

G.1 Hover States

No hover lift/translate effects. No scale transforms. No shadow additions on hover.

G.2 Focus States

All interactive elements use a consistent focus ring:

:focus-visible {
  outline: none;
  box-shadow: 0 0 0 2px #ffffff, 0 0 0 4px #0d9488;
}

• 2px white inner ring for contrast on any background.
• 2px teal outer ring for visibility.
• Applied via :focus-visible only (not :focus) to avoid showing on mouse click.
• Override Mantine's default focus styles in theme.

G.3 Keyboard Navigation

G.4 Form Validation

Validation is shown on blur or on submit, never on keystroke.

G.5 Destructive Action Pattern

1. Destructive buttons use color.error.base as fill.
2. Single-step destructive actions (delete a row): Confirmation popover with explicit action name. E.g., "Delete building 'Park Tower'? This cannot be undone." with "Cancel" (outline) and "Delete" (filled red) buttons.
3. Bulk destructive actions: Modal with count and explicit confirmation. E.g., "Delete 12 buildings? This cannot be undone."
4. Never use browser confirm() dialogs.

G.6 Disabled State

• Opacity 0.5 is not used. Instead:
  • Background: color.disabled.bg
  • Text: color.disabled.text
  • Border: color.disabled.border
  • Cursor: not-allowed
  • No hover/focus effects

G.7 Motion

No spring, bounce, or physics-based easing. No transition-delay. No animation keyframes except loading spinners.

H. Page Pattern Standards

H.1 Dashboard

┌──────────────────────────────────────────────────────┐
│ PageHeader: "Dashboard"                              │
├──────────────────────────────────────────────────────┤
│ Filter Bar (collapsible)                             │
│ [Property Type ▾] [Class ▾] [Status ▾] [Market ▾]   │
├──────────────────────────────────────────────────────┤
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐                 │
│ │ KPI  │ │ KPI  │ │ KPI  │ │ KPI  │  SimpleGrid 4   │
│ └──────┘ └──────┘ └──────┘ └──────┘                 │
├──────────────────────────────────────────────────────┤
│ ┌────────────────────┐ ┌────────────────────┐        │
│ │ Chart Card         │ │ Map Card           │  2-col │
│ │                    │ │                    │        │
│ └────────────────────┘ └────────────────────┘        │
├──────────────────────────────────────────────────────┤
│ ┌────────────┐ ┌────────────┐ ┌────────────┐        │
│ │ Activity   │ │ Activity   │ │ Activity   │  3-col  │
│ └────────────┘ └────────────┘ └────────────┘        │
└──────────────────────────────────────────────────────┘

• Filter bar sits above KPIs, collapsible via Collapse component.
• KPI cards: font.size.kpi for value, font.size.caption for label, tabular-nums.
• KPI delta indicator: green up arrow or red down arrow, font.size.caption.
• Map card: Fixed 340px height within card.
• Activity cards: time-relative labels ("2h ago"), entity link.

H.2 Explore Pages (Buildings, Comps, TIMs)

┌──────────────────────────────────────────────────────┐
│ PageHeader: "Buildings"  [+ New Building]             │
├──────────────────────────────────────────────────────┤
│ DataTableToolbar                                      │
│ [🔍 Search...] [Density ▾] [View: Table | Map]       │
├──────────────────────────────────────────────────────┤
│ StatBar: Total: 1,234 | Filtered: 567 | Page 1 of 57│
├──────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────┐ │
│ │ Table (full width, sticky header)                │ │
│ │ ┌────┬────────┬──────┬───────┬────────┬────────┐ │ │
│ │ │    │ Name   │ Type │ RBA   │ Market │ Status │ │ │
│ │ ├────┼────────┼──────┼───────┼────────┼────────┤ │ │
│ │ │    │        │      │       │        │        │ │ │
│ │ └────┴────────┴──────┴───────┴────────┴────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────┤
│ Pagination: ← Page 1 of 57 →                        │
└──────────────────────────────────────────────────────┘

• Table view is default. Map view swaps table for a 580px map.
• Create/edit opens a right-side Drawer (480px width).
• Drawer has its own header (title + close), scrollable body, sticky footer (Cancel + Save).
• Search and filters persist to URL via TanStack Router search params.
• Density toggle available in toolbar.

H.3 Map Explore Page (Immersive)

┌──────────────────────────────────────────────────────┐
│ Topbar (52px)                                        │
├──────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────┐ │
│ │ MAP (fills remaining viewport height)            │ │
│ │                                                  │ │
│ │  ┌─────────────────┐         ┌──────────────┐   │ │
│ │  │ Filter Panel    │         │ Layer Toggle  │   │ │
│ │  │ (floating left) │         │ (floating rt) │   │ │
│ │  └─────────────────┘         └──────────────┘   │ │
│ │                                                  │ │
│ │  ┌──────────────────────┐                        │ │
│ │  │ Legend (bottom left)  │                        │ │
│ │  └──────────────────────┘                        │ │
│ └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

• Map is NOT inside a card. It IS the page.
• Map height: calc(100vh - 52px) (viewport minus topbar).
• Sidebar can be collapsed on this page for maximum map area.
• Floating panels have background: rgba(255,255,255,0.92), backdrop-filter: blur(8px), border, radius.md, shadow.dropdown.
• Feature click opens a right-side drawer or bottom panel with entity details.

H.4 Analytics Pages

┌──────────────────────────────────────────────────────┐
│ PageHeader: "Vacancy Analytics"                       │
├──────────────────────────────────────────────────────┤
│ Controls Bar                                          │
│ [Quarter ▾] [Dimension ▾] [Metric ▾] [Export ▾]      │
├──────────────────────────────────────────────────────┤
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐                 │
│ │ KPI  │ │ KPI  │ │ KPI  │ │ KPI  │                  │
│ └──────┘ └──────┘ └──────┘ └──────┘                 │
├──────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────┐ │
│ │ Primary Chart (trend line, 400px height)         │ │
│ └──────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────┤
│ ┌────────────────────┐ ┌────────────────────┐        │
│ │ Comparison Chart   │ │ Detail Table       │  2-col │
│ └────────────────────┘ └────────────────────┘        │
└──────────────────────────────────────────────────────┘

• KPIs use tabular-nums and font.size.kpi.
• Charts are inside cards with padding: 16px and a card title.
• Chart canvas minimum height: 300px.
• SegmentedControl for dimension switching, not tabs.

H.5 Operations Pages (Queue, Saved Views)

┌──────────────────────────────────────────────────────┐
│ PageHeader: "Needs Review"  [Bulk Actions ▾]          │
├──────────────────────────────────────────────────────┤
│ StatBar: Pending: 45 | In Progress: 12 | Done: 234  │
├──────────────────────────────────────────────────────┤
│ DataTableToolbar                                      │
│ [🔍 Search...] [Status ▾] [Assigned ▾] [Density ▾]   │
├──────────────────────────────────────────────────────┤
│ Table with priority indicators (left border accent)   │
│ Row actions: [View] [Assign] [Complete] [Dismiss]     │
├──────────────────────────────────────────────────────┤
│ Pagination                                            │
└──────────────────────────────────────────────────────┘

• Priority rows: 3px left border in color.error.base (high), color.warning.base (medium).
• Row actions via RowActionsMenu (three-dot menu).
• Density toggle available.

H.6 Data Management Pages

┌──────────────────────────────────────────────────────┐
│ PageHeader: "Owners"  [+ New Owner]                   │
├──────────────────────────────────────────────────────┤
│ DataTableToolbar                                      │
│ [🔍 Search...]                                        │
├──────────────────────────────────────────────────────┤
│ Table (standard, no density toggle)                   │
├──────────────────────────────────────────────────────┤
│ Pagination                                            │
└──────────────────────────────────────────────────────┘

• Simpler than Explore pages — no map view, no density toggle.
• Create/edit via right-side Drawer.
• Row actions: Edit, Delete (with confirmation).

H.7 Admin Pages

┌──────────────────────────────────────────────────────┐
│ PageHeader: "System Setup"                            │
├──────────────────────────────────────────────────────┤
│ Tab navigation: [General] [Database] [Integrations]   │
├──────────────────────────────────────────────────────┤
│ Card-based settings groups                            │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Section Title                                    │ │
│ │ Key-value settings with inline edit              │ │
│ └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

• Tabs for sub-sections (Mantine Tabs component).
• Settings displayed as labeled value pairs with Edit buttons.
• Admin-only access badge in page header.
• Destructive settings use color.error.base buttons with confirmation modal.

H.8 Drawer vs Modal Decision Matrix

I. Map Standards (MapLibre)

I.1 Basemap Philosophy

• Light, desaturated basemap. Streets and labels visible but not prominent.
• Use a light-themed vector tile style (e.g., MapTiler Positron, Carto Positron, or custom OSM style).
• Raster tile fallback: Current OSM tiles are acceptable as interim; migrate to vector tiles for style control.
• Basemap text: #64748b for labels, #e2e8f0 for roads, #f1f5f9 for land fill.
• The basemap must recede behind data layers.

I.2 Marker Styling Hierarchy

MapLibre Style JSON (Circle Layer Example — Buildings)

{
  "id": "buildings-circle",
  "type": "circle",
  "source": "buildings",
  "paint": {
    "circle-radius": [
      "interpolate", ["linear"], ["zoom"],
      8, 3,
      12, 6,
      16, 10
    ],
    "circle-color": "#0d9488",
    "circle-stroke-color": "#ffffff",
    "circle-stroke-width": 2,
    "circle-opacity": 0.85
  }
}

I.3 Cluster Styling

MapLibre Cluster Style JSON

{
  "id": "clusters",
  "type": "circle",
  "source": "buildings",
  "filter": ["has", "point_count"],
  "paint": {
    "circle-color": "#1e3a8a",
    "circle-radius": [
      "step", ["get", "point_count"],
      12, 10,
      16, 100,
      20
    ],
    "circle-stroke-width": 2,
    "circle-stroke-color": "#ffffff",
    "circle-opacity": 0.9
  }
}

I.4 Layer Toggles Panel

┌────────────────────────┐
│ LAYERS                 │
│ ┌────────────────────┐ │
│ │ ● Buildings    ☑   │ │
│ │ ◆ Comps        ☑   │ │
│ │ ▲ TIMs         ☐   │ │
│ │ ─ Heatmap      ☐   │ │
│ └────────────────────┘ │
└────────────────────────┘

• Position: Top-right of map, below zoom controls.
• Background: rgba(255,255,255,0.92), backdrop-filter: blur(8px).
• Border: 1px solid color.border.default.
• Border radius: radius.md (8px).
• Padding: 12px.
• Toggle: Mantine Checkbox or Switch, sm size.
• Entity symbol matches marker shape and color.

I.5 Map Tooltip / Popover

I.6 Map Performance Rules

1. Enable clustering at all zoom levels below 14.
2. Use source.cluster: true with clusterMaxZoom: 14, clusterRadius: 50.
3. Limit visible features to viewport bounds via MapLibre's built-in frustum culling.
4. Avoid re-creating map sources on filter change — update source data in place via source.setData().
5. Use requestAnimationFrame for batch marker updates.
6. For heatmap layers, downsample to max 5,000 points.
7. Debounce moveend event handlers by 150ms.
8. Never force a full map re-render on React state change — use refs for map instance.

J. Table Standards

J.1 Structure

┌────────────────────────────────────────────────────┐
│ Sticky Header                                       │
│ ┌──────┬──────────┬──────────┬──────────┬────────┐ │
│ │  ▲   │ Name ▲   │ Type     │ RBA ▼    │ Status │ │
│ ├──────┼──────────┼──────────┼──────────┼────────┤ │
│ │      │ Park Tw  │ Office   │ 456,000  │ Active │ │
│ │      │ Metro C  │ Industr  │ 234,000  │ Draft  │ │
│ │      │          │          │          │        │ │
│ └──────┴──────────┴──────────┴──────────┴────────┘ │
├────────────────────────────────────────────────────┤
│ Showing 1-25 of 1,234          ← Page 1 of 50 →   │
└────────────────────────────────────────────────────┘

J.2 Header Styling

J.3 Cell Alignment Rules

J.4 Row Styling

J.5 Pagination

J.6 Loading State

• Use Mantine Skeleton components in place of rows.
• Skeleton rows: 8 rows matching comfortable row height (44px).
• Skeleton shimmer: Use Mantine's default skeleton animation (subtle pulse).
• Header remains visible during loading.

J.7 Empty State

• Single row spanning all columns.
• Centered text: font.size.body, color color.text.secondary.
• Message: "No [entities] found" or "No results match your filters".
• Optional: Reset filters link below message.

J.8 Error State

• Alert component above table (not replacing it).
• color.error.light background, color.error.text text.
• Retry button inline.

J.9 URL State Sync

All table state syncs to URL search params via TanStack Router:

Read from URL on mount, write to URL on change via router.navigate({ search }).

J.10 Virtualization Readiness

For tables exceeding 100 visible rows:

• Use @tanstack/react-virtual for row virtualization.
• Maintain a fixed row height (no dynamic content expansion within rows).
• Measure container height and calculate visible window.
• Keep sticky header outside virtualized container.
• Overscan: 5 rows above and below viewport.

K. Chart Standards (ECharts)

K.1 Global ECharts Theme

const PRISM_ECHARTS_THEME = {
  color: [
    '#0d9488', // teal — primary series
    '#1e3a8a', // navy — comparison
    '#7c3aed', // violet
    '#ea580c', // orange
    '#0284c7', // sky
    '#c026d3', // fuchsia
  ],
  backgroundColor: 'transparent',
  textStyle: {
    fontFamily: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
    color: '#64748b',
    fontSize: 12,
  },
  title: {
    textStyle: {
      fontFamily: "'Inter', sans-serif",
      fontSize: 16,
      fontWeight: 600,
      color: '#111827',
    },
    subtextStyle: {
      fontSize: 12,
      color: '#64748b',
    },
  },
};

K.2 Axis Styling

const axisCommon = {
  axisLine: {
    lineStyle: { color: '#e2e8f0', width: 1 },
  },
  axisTick: {
    lineStyle: { color: '#e2e8f0' },
    length: 4,
  },
  axisLabel: {
    color: '#94a3b8',
    fontSize: 11,
    fontFamily: "'Inter', sans-serif",
    fontVariantNumeric: 'tabular-nums',
  },
  splitLine: {
    lineStyle: { color: '#e2e8f0', type: 'dashed', width: 1 },
  },
  nameTextStyle: {
    color: '#64748b',
    fontSize: 12,
    fontWeight: 500,
  },
};

• X-axis: Labels aligned to center below ticks.
• Y-axis: Labels right-aligned, padding 8px from axis line.
• Grid padding: { top: 40, right: 24, bottom: 40, left: 56 } (adjust left for label width).

K.3 Gridlines

• Horizontal gridlines only (on Y-axis splitLine).
• Dashed, 1px, color.chart.grid (#e2e8f0).
• No vertical gridlines.

K.4 Tooltip

const tooltipStyle = {
  backgroundColor: '#ffffff',
  borderColor: '#e2e8f0',
  borderWidth: 1,
  borderRadius: 8,
  padding: [8, 12],
  textStyle: {
    color: '#111827',
    fontSize: 13,
    fontFamily: "'Inter', sans-serif",
  },
  extraCssText: 'box-shadow: 0 4px 12px rgba(0,0,0,0.08);',
};

• Tooltip trigger: 'axis' for line/bar, 'item' for pie/scatter.
• Tooltip format: Series color dot + series name + value.
• Number formatting: comma-separated, 1-2 decimal places max.

K.5 Legend

const legendStyle = {
  type: 'scroll',
  bottom: 0,
  left: 'center',
  textStyle: {
    color: '#64748b',
    fontSize: 12,
    fontFamily: "'Inter', sans-serif",
  },
  icon: 'roundRect',
  itemWidth: 12,
  itemHeight: 8,
  itemGap: 16,
  pageTextStyle: { color: '#94a3b8' },
};

• Position: Bottom center, below chart.
• Scrollable when > 6 series.
• Interactive: click to toggle series visibility.

K.6 Series Color Mapping

• Area fills: 10% opacity of series color.
• Bar chart: No gradient fills. Solid color at 85% opacity.
• Line chart: 2px stroke width. No dots except on hover.

K.7 Number Formatting

K.8 Large Dataset Handling

• For > 10,000 data points: use ECharts sampling: 'lttb' (Largest Triangle Three Buckets).
• For > 50,000 data points: server-side aggregation before charting.
• Enable large: true and largeThreshold: 2000 for scatter plots.
• Use dataZoom (inside type) for time-series with > 100 x-axis points.

K.9 Loading / Empty States

Loading:

• Show Mantine Skeleton matching chart card dimensions.
• Do not show an ECharts spinner.

Empty:

• Centered within chart area: Icon (Tabler IconChartOff, 32px, color.text.muted) + "No data available" text (font.size.body, color.text.secondary).
• No ECharts noDataGraphic.

L. Mantine Theme Configuration

L.1 Complete Theme Object

import { createTheme, MantineColorsTuple } from '@mantine/core';

// Custom navy palette for Mantine color system
const navy: MantineColorsTuple = [
  '#eff6ff', // 0
  '#dbeafe', // 1
  '#bfdbfe', // 2
  '#93c5fd', // 3
  '#60a5fa', // 4
  '#3b82f6', // 5
  '#1e3a8a', // 6 — base
  '#1e3a8a', // 7 — base (repeated for primary shade)
  '#172554', // 8
  '#0f172a', // 9
];

// Custom teal palette
const teal: MantineColorsTuple = [
  '#f0fdfa', // 0
  '#ccfbf1', // 1
  '#99f6e4', // 2
  '#5eead4', // 3
  '#2dd4bf', // 4
  '#14b8a6', // 5
  '#0d9488', // 6 — base
  '#0f766e', // 7
  '#115e59', // 8
  '#134e4a', // 9
];

export const prismTheme = createTheme({
  primaryColor: 'teal',
  primaryShade: { light: 6, dark: 7 },

  colors: { navy, teal },

  fontFamily: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
  fontFamilyMonospace: "'JetBrains Mono', 'Fira Code', monospace",

  headings: {
    fontFamily: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
    fontWeight: '600',
    sizes: {
      h1: { fontSize: '20px', lineHeight: '1.3' },
      h2: { fontSize: '16px', lineHeight: '1.35' },
      h3: { fontSize: '14px', lineHeight: '1.4' },
      h4: { fontSize: '14px', lineHeight: '1.4' },
    },
  },

  fontSizes: {
    xs: '11px',
    sm: '12px',
    md: '14px',
    lg: '16px',
    xl: '20px',
  },

  spacing: {
    xs: '4px',
    sm: '8px',
    md: '12px',
    lg: '16px',
    xl: '24px',
  },

  radius: {
    xs: '4px',
    sm: '6px',
    md: '8px',
    lg: '10px',
    xl: '12px',
  },

  defaultRadius: 'sm',

  shadows: {
    xs: 'none',
    sm: 'none',
    md: '0 4px 12px rgba(0,0,0,0.08), 0 1px 3px rgba(0,0,0,0.06)',
    lg: '0 8px 30px rgba(0,0,0,0.12), 0 2px 8px rgba(0,0,0,0.06)',
    xl: '0 8px 30px rgba(0,0,0,0.12), 0 2px 8px rgba(0,0,0,0.06)',
  },

  other: {
    zIndex: {
      mapOverlay: 100,
      mapPopup: 200,
      stickyHeader: 300,
      sidebar: 400,
      topbar: 500,
      dropdown: 600,
      drawer: 700,
      modalBackdrop: 800,
      modal: 801,
      tooltip: 900,
      commandPalette: 950,
      notification: 1000,
    },
  },

  components: {
    Card: {
      defaultProps: {
        withBorder: true,
        shadow: undefined,
        radius: 'md',
        padding: 'lg',
      },
      styles: {
        root: {
          borderColor: 'var(--color-border-default, #e2e8f0)',
        },
      },
    },

    Button: {
      defaultProps: {
        radius: 'sm',
      },
      styles: {
        root: {
          fontWeight: 500,
        },
      },
    },

    TextInput: {
      defaultProps: {
        radius: 'sm',
      },
      styles: {
        input: {
          borderColor: 'var(--color-border-strong, #cbd5e1)',
          '&:focus': {
            borderColor: '#0d9488',
          },
        },
      },
    },

    Select: {
      defaultProps: {
        radius: 'sm',
        comboboxProps: { zIndex: 600 },
      },
    },

    MultiSelect: {
      defaultProps: {
        radius: 'sm',
        comboboxProps: { zIndex: 600 },
      },
    },

    Modal: {
      defaultProps: {
        radius: 'md',
        zIndex: 801,
        overlayProps: { backgroundOpacity: 0.35, blur: 2 },
      },
    },

    Drawer: {
      defaultProps: {
        zIndex: 700,
      },
    },

    Popover: {
      defaultProps: {
        radius: 'md',
        shadow: 'md',
        zIndex: 600,
      },
    },

    Tooltip: {
      defaultProps: {
        radius: 'sm',
        zIndex: 900,
      },
    },

    Table: {
      defaultProps: {
        striped: true,
        highlightOnHover: true,
      },
    },

    Badge: {
      defaultProps: {
        radius: 'xs',
        variant: 'light',
      },
    },

    Tabs: {
      styles: {
        tab: {
          fontWeight: 500,
          fontSize: '14px',
          padding: '8px 16px',
        },
      },
    },

    Skeleton: {
      defaultProps: {
        radius: 'sm',
      },
    },

    Notification: {
      defaultProps: {
        radius: 'md',
      },
    },
  },
});

L.2 CSS Variable Layer

Add to styles.css root:

:root {
  /* Neutrals */
  --color-bg-default: #f8fafc;
  --color-bg-subtle: #f1f5f9;
  --color-bg-muted: #e2e8f0;
  --color-surface-card: #ffffff;
  --color-border-default: #e2e8f0;
  --color-border-strong: #cbd5e1;
  --color-text-primary: #111827;
  --color-text-secondary: #64748b;
  --color-text-muted: #94a3b8;

  /* Structural */
  --color-navy-base: #1e3a8a;
  --color-navy-dark: #172554;
  --color-navy-light: #dbeafe;
  --color-navy-text: #eff6ff;

  /* Action */
  --color-teal-base: #0d9488;
  --color-teal-hover: #0f766e;
  --color-teal-pressed: #115e59;
  --color-teal-light: #ccfbf1;
  --color-teal-subtle: #f0fdfa;

  /* Semantic */
  --color-success: #059669;
  --color-warning: #d97706;
  --color-error: #dc2626;
  --color-info: #2563eb;

  /* Interaction */
  --color-hover-row: #f1f5f9;
  --color-selected-row: #f0fdfa;
  --color-focus-ring: 0 0 0 2px #ffffff, 0 0 0 4px #0d9488;

  /* Typography */
  --font-tabular: 'tnum' 1, 'lnum' 1;
}

M. Compact Mode Implementation Strategy

M.1 Architecture

DensityProvider (React Context)
├── value: "comfortable" | "compact"
├── toggle: () => void
├── persisted to localStorage per-page
└── sets data-density attribute on wrapper div

M.2 File Structure

shared/
  ui/
    DensityProvider.tsx     — Context provider + hook
    DensityToggle.tsx       — SegmentedControl toggle component
  theme/
    density.css             — All density-responsive CSS overrides

M.3 DensityProvider Implementation

// DensityProvider.tsx
import { createContext, useContext, useState, useCallback, ReactNode } from 'react';

type Density = 'comfortable' | 'compact';

interface DensityContextValue {
  density: Density;
  setDensity: (d: Density) => void;
}

const DensityContext = createContext<DensityContextValue>({
  density: 'comfortable',
  setDensity: () => {},
});

export function useDensity() {
  return useContext(DensityContext);
}

export function DensityProvider({ pageKey, children }: { pageKey: string; children: ReactNode }) {
  const storageKey = `prism:density:${pageKey}`;
  const [density, setDensityState] = useState<Density>(
    () => (localStorage.getItem(storageKey) as Density) || 'comfortable'
  );

  const setDensity = useCallback((d: Density) => {
    setDensityState(d);
    localStorage.setItem(storageKey, d);
  }, [storageKey]);

  return (
    <DensityContext.Provider value={{ density, setDensity }}>
      <div data-density={density}>
        {children}
      </div>
    </DensityContext.Provider>
  );
}

M.4 DensityToggle Component

// DensityToggle.tsx
import { SegmentedControl } from '@mantine/core';
import { IconLayoutDistributeVertical, IconLayoutAlignMiddle } from '@tabler/icons-react';
import { useDensity } from './DensityProvider';

export function DensityToggle() {
  const { density, setDensity } = useDensity();

  return (
    <SegmentedControl
      size="xs"
      value={density}
      onChange={(v) => setDensity(v as 'comfortable' | 'compact')}
      data={[
        { label: 'Comfortable', value: 'comfortable' },
        { label: 'Compact', value: 'compact' },
      ]}
    />
  );
}

M.5 Pages That Support Density Toggle

• BuildingsExplorePage
• CompsExplorePage
• TimsExplorePage
• OperationsQueuePage
• OperationsSavedViewsPage (if table-based)

Wrap these pages in <DensityProvider pageKey="buildings">. Add <DensityToggle /> to their DataTableToolbar.

N. Reusable Component Structure

N.1 Current Components (Keep)

N.2 New Components (Add)

N.3 Component API Sketches

KpiCard

interface KpiCardProps {
  label: string;
  value: string | number;
  delta?: { value: number; direction: 'up' | 'down' | 'flat' };
  format?: 'number' | 'percent' | 'currency' | 'sf';
  linkTo?: string;
  loading?: boolean;
}

EntityDrawer

interface EntityDrawerProps {
  opened: boolean;
  onClose: () => void;
  title: string;
  width?: number; // default 480
  children: ReactNode;
  footer?: ReactNode; // sticky footer with Cancel + Save
  loading?: boolean;
}

ChartCard

interface ChartCardProps {
  title: string;
  subtitle?: string;
  height?: number; // default 300
  loading?: boolean;
  empty?: boolean;
  emptyMessage?: string;
  children: ReactNode; // ECharts component
  actions?: ReactNode; // export button etc
}

ConfirmAction

interface ConfirmActionProps {
  title: string;
  message: string;
  confirmLabel: string; // e.g., "Delete"
  onConfirm: () => void;
  variant?: 'danger' | 'warning'; // default danger
  children: ReactNode; // trigger element
}

O. UI Consistency Checklist

O.1 Color Usage

• Page backgrounds use color.background.default (#f8fafc)
• Cards use color.surface.card with 1px solid color.border.default
• No card shadows (borders only)
• Primary buttons use color.teal.base
• Sidebar uses color.navy.base background
• Active nav items have teal left accent
• Destructive actions use color.error.base
• No competing saturated colors beyond navy (structural) and teal (action)
• Semantic colors used only for their intended purpose

O.2 Typography

• Font: Inter loaded and applied globally
• Page titles: 20px / 600 weight
• Section titles: 16px / 600 weight
• Body text: 14px / 400 weight
• Captions: 12px / 400 weight
• Table headers: 12px / 500 weight / uppercase
• KPI values: 28px / 700 weight / tabular-nums
• All numeric displays use tabular-nums
• No italic usage in UI text
• No decorative typography

O.3 Spacing & Layout

• 8px base grid respected
• Page padding: 20px
• Card padding: 16px
• Stack gaps use spacing tokens (4, 8, 12, 16, 24, 32)
• No spacing values outside the token set
• Consistent gutter: 16px
• Tables full-width within containers

O.4 Interactions

• All focus states use the standard teal focus ring
• Focus visible only on keyboard navigation (:focus-visible)
• Hover states are subtle background changes, never transforms
• No hover shadows or lifts on cards
• Disabled states use designated disabled tokens
• Destructive actions require confirmation
• Form validation shown on blur or submit, not on keystroke

O.5 Component Patterns

• Create/edit actions use right-side Drawer (not modal)
• Delete confirmations use centered Modal
• All tables have loading skeleton, empty state, and error state
• All charts have loading skeleton and empty state
• Pagination uses "Showing X-Y of Z" + prev/next buttons
• Search inputs are debounced (200-250ms)
• Filter state synced to URL params
• Density toggle present on Explore and Operations pages

O.6 Maps

• Map uses desaturated basemap
• Entity types distinguishable by shape AND color
• Clusters use navy fill
• Selected features use highlight yellow
• Floating panels have frosted glass treatment
• Map instance managed via ref, not React state
• Clustering enabled below zoom 14
• moveend handlers debounced

O.7 Charts

• Primary series uses teal
• Comparison series uses navy
• No rainbow palettes
• Horizontal gridlines only, dashed
• Legend at bottom center
• Tooltip has white background, border, shadow
• Axis labels use tabular-nums
• Large datasets use sampling

O.8 Accessibility

• All text meets WCAG AA contrast ratio (4.5:1 normal, 3:1 large)
• Interactive elements have visible focus indicators
• Icon-only buttons have aria-label
• Form inputs have associated labels
• Error messages are announced (aria-live or role="alert")
• Keyboard navigation works for all interactive flows
• Color is never the sole differentiator for information

O.9 WCAG AA Contrast Verification

Note: color.text.muted (#94a3b8) fails AA for small text. Use only for:

• Placeholder text (exempt per WCAG)
• Decorative/supplementary text where adjacent high-contrast text carries the meaning
• Large text (18px+ or 14px+ bold)

P. File Summary

All specification sections mapped to implementation files: