ui-architect

Design component architecture for 45Black legaltech products. This skill helps non-coders plan UI structure, separate product layers, and select appropriate design systems.

When To Use

• Starting a new UI product or feature
• Restructuring existing UI architecture
• Deciding which design system variant to use
• Planning component hierarchy for apex products
• Separating concerns between product layers
• User mentions: "architect", "component structure", "layer design", "ui planning"

Workflow

1. Gather Context

Ask the user about:

• Product name and purpose
• Target users (trustees/clients vs developers/admins)
• Usage pattern (occasional vs 8hr+ daily use)
• Data sources (which apex services: helix, governance, precedent, kestrel)
• Key user journeys (what tasks do users need to complete)

2. Select Design System

Based on user answers, recommend design system:

Is this CLIENT-FACING (trustees, advisers, external)?
├── YES → TRUSTEE EDITION v1.0
│         • Light-first, Paper White backgrounds
│         • Inter typography
│         • Governance Blue primary (#1A4F7A)
│         • Compliance status colours
│         • WCAG AAA target
│         • Print-ready
│
└── NO → Is this for 8+ hours DAILY USE?
    ├── YES → SAVILLE v5.0 CLARITY
    │         • Matte OFF
    │         • Hero weight 500
    │         • Data-dense optimised
    │
    └── NO → SAVILLE v5.0 CORE
              • Matte ON (15% dark, 8% light)
              • Hero weight 300
              • Developer/admin aesthetic

3. Define Product Layers

For apex ecosystem products, define these layers:

┌─────────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                        │
│  Components, Pages, Layouts (React/Next.js)                 │
│  Design System: [Selected System]                           │
├─────────────────────────────────────────────────────────────┤
│                    INTERACTION LAYER                         │
│  State Management (Zustand), Form Handling (React Hook Form)│
│  User preferences, UI state, Session management             │
├─────────────────────────────────────────────────────────────┤
│                    DATA ACCESS LAYER                         │
│  React Query hooks, API clients, Data transformation        │
│  Connects to: apex-helix | apex-governance | apex-precedent │
├─────────────────────────────────────────────────────────────┤
│                    COMPLIANCE LAYER                          │
│  AI transparency markers, Audit logging, GDPR consent       │
│  EU AI Act compliance, Hash-chained audit trails            │
└─────────────────────────────────────────────────────────────┘

4. Map Component Hierarchy

Create a component tree document:

markdown
1## Component Hierarchy: [Product Name]
2
3### Layout Components
4- AppShell (header, sidebar, main content)
5- PageLayout (breadcrumbs, title, actions)
6- SplitPane (resizable document/panel views)
7
8### Feature Components
9- [Domain-specific components]
10
11### Shared UI Components (from design system)
12- Buttons, Cards, Badges, Tables, Forms
13- Use shadcn/ui with design system tokens
14
15### Data Components
16- [Product].Provider (context for data)
17- use[Product]Data (React Query hook)

5. Define Data Flow

Document how data moves between layers:

User Action → Interaction Layer → Data Layer → API Proxy → Backend Service
                                                              │
                                                              ▼
UI Update ← Presentation ← State Update ← Query Invalidation ← Response

6. Output Architecture Document

Create docs/UI_ARCHITECTURE.md with:

1. Design System Selection - Which system and why
2. Layer Diagram - Visual representation
3. Component Hierarchy - Tree structure
4. Data Flow - Sequence diagrams for key journeys
5. Compliance Requirements - AI transparency, audit, GDPR
6. Implementation Notes - For developers

Apex Product Layer Matrix

Reference for the apex constellation:

Key Architectural Decisions

API Proxy Pattern (Mandatory)

All backend requests go through Next.js API routes:

• /api/helix/* → apex-helix (port 3001)
• /api/precedent/* → apex-precedent (port 3002)
• /api/kestrel/* → apex-kestrel (port 3003)

AI Transparency (EU AI Act Compliance)

All AI-generated content MUST include:

• "AI-Generated" badge
• "Generated with Claude | Always verify AI suggestions" footer
• Human approval step before any action

State Management

• Server state: React Query (caching, invalidation)
• Client state: Zustand (UI preferences, local state)
• Form state: React Hook Form + Zod validation

Example Output

markdown
1# UI Architecture: apex-lens v2.0
2
3## Design System
4**Trustee Edition v1.0** - Selected because:
5- Primary users are pension trustees (external)
6- Needs print-ready compliance reports
7- Light-first suits office environments
8
9## Component Layers
10
11### Presentation (Trustee Edition)
12├── LegislationViewer
13│   ├── DocumentPane (Merriweather, cream background)
14│   ├── ObligationPanel (cards with status badges)
15│   └── NavigationTree (sidebar with sections)
16├── SearchInterface
17│   ├── SearchBar
18│   ├── FacetedFilters
19│   └── ResultsList
20└── CollectionManager
21    ├── FavouritesList
22    └── CollectionView
23
24### Data Access
25├── useLegislation(id) → /api/helix/acts/{id}
26├── useObligations(sectionId) → /api/helix/obligations
27└── useCaseLaw(query) → /api/precedent/search
28
29### Compliance
30├── AITransparencyBadge
31├── AuditLogProvider
32└── ConsentManager

Model Preference

opus - Architecture decisions require deep reasoning about trade-offs

Part of 45Black UI Expert Devstack For non-coders: This skill helps you plan before building