Skip to content

05. UI/UX System: Visual Language & Patterns

Status: Active / Golden Version: 1.0 (Consolidated Jan 2026)

"The Workbench Philosophy: We build tools for doing work, not dashboards for watching it."

1. The Workbench Philosophy

Core Rule: Allow users to complete tasks without leaving the screen.

  • ❌ Dashboard: Passive Cards, Charts, Read-Only info.
  • ✅ Workbench: Interactive Tool Palettes, Action-Oriented.

Layout Archetypes

  1. Standard Workbench: Sidebar + List + Detail. (e.g., Invoices).
  2. Editor Workspace: Focus Mode. Sidebar hidden/minimized. (e.g., Knowledge Article Editor).
  3. Wizard: Step-by-step linear flow. (e.g., New Resident Onboarding).

2. Navigation & Shell (Standard 34)

The Shell is divided into 3 Zones:

Zone A: Global Sidebar (The Map)

  • Role: Application-level switching.
  • Structure:
  • Brand: Logo.
  • Domains: Property, Ops, Finance (Curated Order).
  • Utilities: Communications, Analytics.
  • Admin: System Settings (Bottom).

Zone B: Top Bar (The Context)

  • Role: Wayfinding & Context.
  • Right Anchor (MANDATORY): The Identity & Persona Cluster (Standard 64).
  • Hierarchy: User Avatar (Person) -> Context Switcher (Persona/Hat).
  • Philosophy: "Identity first, then Role."
  • Consolidation: Eliminates user profile elements from the sidebar to maximize operational space.

Zone C: Page Toolbar (The Tools)

  • Role: View manipulation.
  • Standard:
  • Left: Scenario Tabs (Drafts, Active, Closed).
  • Middle: Search & Filters.
  • Right: Primary Action (Solid Button).

3. The Dashboard Composition Engine

The Dashboard is not a static page. It is a JSON-Driven Engine.

  • Logic: Layout = Function(UserRole, Context).
  • Widgets: Autonomous "Micro-Frontends" that fetch their own data via Server Actions.
  • Example: CisternLevelWidget connects directly to PropertyService.

4. Visual Standards

Color System

  • Gold (sd-gold): The accent color. Used for Active State borders and Focus Rings.
  • Semantic Tokens: bg-success/10, text-destructive. Never use raw Tailwind colors (bg-blue-500).

The "Editor Workspace" Standard

For high-focus tasks (Studio):

  • Surface: --studio-canvas (Darker/Neutral).
  • Header: Replaced by Command Strip (Title + Save/Publish).
  • Layout: 3-Surface Model (Canvas > Panel > Overlay).

5. Accessibility

  • Focus Ring: All interactive elements must show a ring-2 ring-sd-gold on focus.
  • Density: The platform operates in Ultra-High Density Mode for administrative work surfaces.
  • Spacing: Minimal Gaps (gap-4 or gap-2).
  • Full-Bleed: Removal of excessive global padding (p-1 in ConditionalLayout).
  • Header Height: Slimmed to h-12.
  • Sidebar Items: 32px-40px.
  • Inputs: Small variant (32px).

Version History

Version Date Author Change
0.1.0 2026-01-26 Antigravity Initial Audit & Metadata Injection