​

UI Strategy & Design System

​

Overview

​

The UI Strategy Question

Who controls design, behavior, accessibility, and future change — you, or a library?

Fast & Opinionated  ←────────────→  Flexible & Future-Proof

​

The Four UI Strategies

​

🟥 Strategy 1: Full UI Framework (Not Recommended for Visita)

• Very fast to start
• Lots of pre-built components

• Heavy bundle size
• Highly opinionated design
• Difficult to customize deeply
• Generic “SaaS” appearance

• ❌ Long-term civic platforms need custom identity
• ❌ Heavy frameworks conflict with performance goals
• ❌ Opinionated designs don’t reflect civic seriousness
• ❌ Difficult to evolve with changing requirements

​

🟨 Strategy 2: Build Everything Yourself (Not Ideal Alone)

• Total control over everything
• Lightweight bundle

• Accessibility is extremely difficult to get right
• Reinventing wheels slows development
• Requires significant UI expertise

• ❌ Civic platforms require excellent accessibility
• ❌ Small team can’t maintain all primitives
• ❌ Risk of inconsistent behavior across components

​

🟩 Strategy 3: Headless + Utility CSS (Recommended for Visita)

• Radix UI → Behavior + Accessibility foundation
• Tailwind CSS → Styling control
• shadcn/ui → Starter components (copy, not dependency)

• ✅ Full control over design and behavior
• ✅ Accessible by default (Radix handles ARIA, keyboard nav, focus management)
• ✅ No vendor lock-in (we own the code)
• ✅ Scales beautifully with the platform
• ✅ Aligns with civic design principles

• ✅ We control markup and styling
• ✅ We inherit battle-tested accessibility
• ✅ We can refactor without breaking contracts
• ✅ Design reflects civic values, not generic SaaS

​

🟦 Strategy 4: Design System First (Future Evolution)

• Design tokens as single source of truth
• Component contracts and APIs
• UI governance and contribution guidelines
• Automated testing and visual regression

​

Our UI Stack

​

The Recommended Stack

Next.js (App Router)    // Framework
TypeScript (Strict)     // Language safety
Tailwind CSS            // Styling control
Radix UI                // Accessibility + behavior
shadcn/ui               // Component templates

​

Why This Stack Works

1. You Control Markup — No magic divs or unwanted DOM structure
2. You Control Styling — Tailwind utilities, not pre-styled components
3. You Inherit Accessibility — Radix handles the hard parts (ARIA, keyboard nav, focus)
4. You Can Refactor — Own the code, change what you need
5. Civic-Appropriate — No “startup” aesthetic imposed by framework

​

Component Hierarchy

​

The Three-Layer Architecture

/components
 ├── ui/              ← Primitives (generic, reusable)
 │    ├── Button.tsx
 │    ├── Input.tsx
 │    ├── Modal.tsx
 │    └── Dropdown.tsx
 │
 ├── layout/          ← Structural (persistent UI)
 │    ├── Header.tsx
 │    ├── Sidebar.tsx
 │    └── Footer.tsx
 │
 ├── domain/          ← Visita-specific (business logic)
 │    ├── WardCard.tsx
 │    ├── CrimeMap.tsx
 │    ├── BusinessListing.tsx
 │    └── PoliticalProfile.tsx

​

The Golden Rule

UI components must not know business logic. Domain components may use UI components. Never the reverse.

// ✅ GOOD: Domain component uses UI primitive
function WardCard({ ward }: { ward: Ward }) {
  return (
    <Card>
      <CardHeader>
        <Text variant="heading">{ward.name}</Text>
        <Badge variant="info">{ward.code}</Badge>
      </CardHeader>
      <CardContent>
        <WardStats ward={ward} />  // Domain-specific stats component
      </CardContent>
    </Card>
  );
}

// ❌ BAD: UI component knows about wards
function Button({ wardCode }: { wardCode: string }) {
  // Never do this - Button shouldn't know what a ward is
}

​

Design Philosophy

​

Visita’s UI Must Feel:

1. Civic — Serious, trustworthy, institutional
2. Calm — Not flashy or attention-grabbing
3. Structured — Clear hierarchy and organization
4. Neutral — Data-respecting, not emotionally manipulative
5. Accessible — Works for all citizens

​

What We Avoid:

• ❌ Over-rounded “startup bubbles” (excessive border-radius)
• ❌ Flashy gradients and animations
• ❌ Loud, attention-seeking visuals
• ❌ Trendy designs that age poorly
• ❌ Engagement-optimized patterns (infinite scroll, pull-to-refresh for its own sake)

​

Design Principles

1. Clarity Over Cleverness — Simple, readable interfaces
2. Function Over Form — Beauty emerges from purpose, not decoration
3. Consistency Over Novelty — Predictable patterns build trust
4. Accessibility Over Aesthetics — If it’s not accessible, it’s not done
5. Civic Responsibility Over Engagement — Inform, don’t manipulate

​

Design Tokens

​

Foundation Before Components

​

🎨 Colors (Semantic, Not Aesthetic)

// Not just pretty colors - they mean something
primary      → Civic blue/green (trust, stability)
secondary    → Muted neutral (background, subtle)
danger       → Red (alerts, crime, warnings)
warning      → Amber (caution, attention needed)
success      → Green (positive, confirmed)
surface      → White/light gray (cards, panels)
muted        → Gray text (metadata, secondary info)

​

🔲 Border Radius

radius-sm    → 4px   (inputs, small elements)
radius-md    → 8px   (cards, panels)
radius-lg    → 12px  (modals, large containers)

​

📐 Spacing

space-xs     → 4px
space-sm     → 8px
space-md     → 16px
space-lg     → 24px
space-xl     → 32px

​

Styling Strategy

​

How We Use Tailwind

• ✅ Spacing and layout (p-4, mt-2, grid-cols-3)
• ✅ Colors (bg-surface, text-muted, border-danger)
• ✅ Responsive design (md:p-6, lg:flex)
• ✅ Typography (text-sm, font-medium)

• ❌ Create massive custom CSS files
• ❌ Inline styles everywhere (style={{ color: 'red' }})
• ❌ Over-abstract class names too early (classNames="card-primary")
• ❌ Create one-off utilities for every variation

​

Design Token Implementation

// ✅ GOOD: Using semantic tokens
function Alert({ variant }: { variant: 'info' | 'danger' }) {
  return (
    <div className={`
      p-4
      rounded-md
      border
      ${variant === 'danger' 
        ? 'bg-red-50 border-red-200 text-red-800' 
        : 'bg-blue-50 border-blue-200 text-blue-800'
      }
    `}>
      {/* Content */}
    </div>
  );
}

// ❌ BAD: Hardcoded values
function Alert({ variant }: { variant: 'info' | 'danger' }) {
  return (
    <div style={{
      padding: '16px',
      borderRadius: '8px',
      backgroundColor: variant === 'danger' ? '#fee' : '#eef'
    }}>
      {/* Content */}
    </div>
  );
}

​

Accessibility Strategy

​

Non-Negotiable for Civic Platforms

​

What Radix Provides

1. Keyboard Navigation — All components work without a mouse
2. Focus Management — Proper focus traps and restoration
3. ARIA Roles — Correct semantic HTML and ARIA attributes
4. Screen Reader Support — Announcements and state changes
5. Color Contrast — Meets WCAG AA standards

​

Our Accessibility Requirements

• ✅ Keyboard navigation (Tab, Enter, Escape, Arrow keys)
• ✅ Focus rings (visible focus indicators)
• ✅ Screen readers (ARIA labels, live regions)
• ✅ High contrast mode (4.5:1 minimum contrast)
• ✅ Reduced motion preferences

​

Accessibility Checklist

• Test with keyboard only (no mouse)
• Test with screen reader (NVDA, VoiceOver, or JAWS)
• Verify color contrast ratios
• Check focus management in modals/dialogs
• Ensure form labels are properly associated
• Test with browser zoom (200%)

​

Performance Strategy

​

UI-Level Performance

1. Is this component above the fold? → Load immediately
2. Can this load later? → Lazy load
3. Is it static or interactive? → Server vs client component
4. Does it have heavy dependencies? → Dynamic import

​

Tactics

​

1. Server Components by Default

// ✅ GOOD: Server component (default)
export default async function WardPage({ params }: { params: { code: string } }) {
  const ward = await fetchWard(params.code);  // Server-side fetch

  return (
    <div>
      <WardHeader ward={ward} />  {/* Static content */}
      <WeatherWidget data={ward.weather} />
    </div>
  );
}

​

2. Client Components Only When Needed

'use client';
// Only use client when you need:
// - useState, useEffect
// - click handlers
// - browser APIs
export default function SignalFilter() {
  const [selectedCategory, setSelectedCategory] = useState('all');

  return (
    <Select value={selectedCategory} onValueChange={setSelectedCategory}>
      {/* Options */}
    </Select>
  );
}

​

3. Dynamic Imports for Heavy Components

import dynamic from 'next/dynamic';

// Lazy load heavy components
const DirectoryMap = dynamic(
  () => import('@/components/ward/DirectoryMap'),
  {
    loading: () => <MapSkeleton />,  // Show skeleton
    ssr: false  // Don't SSR map (browser-only)
  }
);

export default function WardPage() {
  return (
    <div>
      <WeatherWidget />  {/* Above-the-fold */}
      <DirectoryMap />   {/* Below-the-fold, lazy load */}
    </div>
  );
}

​

4. Skeleton Loaders

// Show skeleton while data loads
function WardSkeleton() {
  return (
    <div className="animate-pulse space-y-4">
      <div className="h-8 bg-gray-200 rounded w-1/3"></div>
      <div className="h-32 bg-gray-200 rounded"></div>
      <div className="space-y-2">
        <div className="h-4 bg-gray-200 rounded"></div>
        <div className="h-4 bg-gray-200 rounded w-5/6"></div>
      </div>
    </div>
  );
}

​

Page-Building Rule

​

Pages Compose, Not Design

// ✅ GOOD: Page composes domain components
export default function WardDashboard({ params }: { params: { code: string } }) {
  const ward = await fetchWard(params.code);

  return (
    <DashboardLayout>
      <WardHeader ward={ward} />
      <WardStats ward={ward} />
      <WardFeed wardCode={params.code} />
    </DashboardLayout>
  );
}

// ❌ BAD: Page contains UI logic
export default function WardDashboard({ params }: { params: { code: string } }) {
  const ward = await fetchWard(params.code);

  return (
    <div className="p-6 max-w-6xl mx-auto">
      <div className="flex items-center justify-between mb-6">
        <h1 className="text-2xl font-bold">{ward.name}</h1>
        <div className="flex gap-2">
          {/* Page shouldn't design UI */}
        </div>
      </div>
      {/* More inline UI logic */}
    </div>
  );
}

​

UI Governance Rules

​

Prevent Chaos with Clear Rules

1. No Page-Level Styling — Pages compose, components style
2. No Business Logic in ui/ — UI components are dumb
3. No State in Layout Components — Layouts are static structure
4. No Copying JSX Across Pages — Extract to shared component
5. No Component Without Clear Purpose — Every component solves a problem
6. Extend, Don’t Fork — Add variants to existing components
7. Accessibility First — No component ships without a11y testing

​

Component Lifecycle

1. Does it belong in ui/, layout/, or domain/?
2. Can an existing component be extended?
3. What are its states? (loading, empty, error)
4. What props does it need?
5. Is it accessible?
6. Is it performant?
7. Does it follow design tokens?

​

How This Fits Visita

​

Visita Needs:

1. Trust — UI must feel reliable and institutional
2. Clarity — Information must be easy to understand
3. Seriousness — This is civic infrastructure, not entertainment
4. Accessibility — Must serve all citizens
5. Scalability — Must grow with the platform

​

Our UI Strategy Delivers:

• ✅ Calm Design — No flashy animations or trendy effects
• ✅ Structured Layout — Clear information hierarchy
• ✅ Neutral Aesthetic — Data-respecting, not emotionally manipulative
• ✅ Accessible by Default — Radix ensures baseline accessibility
• ✅ Maintainable — Clear separation of concerns
• ✅ Civic-Appropriate — Reflects seriousness of civic intelligence

​

Summary

​

Next Steps