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:
    1. Brand: Logo.
    2. Domains: Property, Ops, Finance (Curated Order).
    3. Utilities: Communications, Analytics.
    4. 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).