UI/UX Standards

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Constitution Reference: See constitution.md (current: see docs/VERSIONS.md) §6.7 [UI/UX Guardrails] for non-negotiable requirements. Quick Reference: See root AGENTS.md (current: see docs/VERSIONS.md) §[Quick Reference] for condensed guidelines. Color Utilities: See docs/development/SEMANTIC_COLORS.md (current: see docs/VERSIONS.md) for color mapping patterns. Spacing Patterns: See SPACING_AND_UX_STANDARDS.md (current: see docs/VERSIONS.md) for detailed spacing patterns and responsive design guidelines. Tab Patterns: See .cursor/rules/tab-patterns.md for the canonical tab variant decision table, codemod recipes, and accessibility rules.

​

Design Token Governance

• DESIGN_TOKEN_SYNC_POLICY.md

• source-of-truth files and ownership,
• hard-locked vs app-extensible token families,
• backward-compat alias expectations,
• required visual and validation checks before merge.

​

Quick Reference

​

Common Patterns

// ✅ CORRECT
<Badge variant="success">Active</Badge>
<div className="bg-warning/10 text-warning-foreground">Warning</div>
<Button variant="destructive">Delete</Button>

// ❌ WRONG
<Badge className="bg-green-500">Active</Badge>
<div className="text-yellow-600">Warning</div>

• success - Positive states (active, approved, complete)
• warning - Caution states (pending, at-risk, expiring)
• destructive - Error/danger states (rejected, error, critical)
• info - Informational states (in progress, new)
• secondary - Neutral/inactive states

// ✅ ALWAYS use skeleton loaders
if (isLoading) return <AppLoadingSkeleton />;

// ❌ NEVER return null
if (isLoading) return null;

​

Token Usage

​

Empty States

​

Overlay naming

​

N/A and Zero States

​

Hub Entry Copy (Optional)

​

Table of Contents

1. Design System
2. Button Usage
3. Tabs
4. Page Templates
5. Navigation & Information Architecture
6. Mobile-First Requirements
7. Performance UX
8. Accessibility
9. Related Documentation

​

Design System

​

Token System

• CSS Variables + token mappings: src/index.css (@theme inline, :root, .dark)

​

Colors

​

Semantic Colors

• primary / primary-foreground - Primary brand color (deep navy chrome accent; not the main CTA — use accent)
• secondary / secondary-foreground - Secondary actions (note: bg-secondary is aliased to --card-elevated)
• accent / accent-foreground - Brand CTA color (teal); pair with Button variant="accent" for the main action
• destructive / destructive-foreground - Errors, destructive actions
• success / success-foreground - Success states, positive feedback
• warning / warning-foreground - Warnings, caution states
• info / info-foreground - Informational states (a distinct blue, not a primary tint); pair bg-info with text-info-foreground for proper dark-mode contrast
• muted / muted-foreground - Muted text, disabled states
• card / card-foreground - Card backgrounds
• popover / popover-foreground - Popover/dropdown backgrounds

Full token catalog: See SEMANTIC_COLORS.md § Token Catalog Reference for the complete inventory, including subtle variants, hover tokens, sidebar slot, special tokens (overlay-scrim, ai-accent, glass, shimmer-highlight), and the Encore brand reserved set.

// ✅ CORRECT: Use semantic tokens
<Badge variant="success">Published</Badge>
<div className="bg-warning/10 text-warning-foreground">Warning message</div>
<Button variant="destructive">Delete</Button>

// ❌ WRONG: Hardcoded colors
<Badge className="bg-green-500">Published</Badge>
<div className="text-yellow-600">Warning message</div>
<Button className="bg-red-500">Delete</Button>

• ❌ Using text-green-500, bg-red-100, etc. (hardcoded Tailwind colors)
• ❌ Using text-[#FF0000] (arbitrary color values)
• ✅ Use semantic tokens: text-success, bg-destructive/10, etc.

​

Status Colors

• Success: success token (green) - Completed, approved, published
• Warning: warning token (yellow/orange) - Pending, needs attention
• Error: destructive token (red) - Failed, rejected, errors
• Info: info token (blue) - Informational messages, in-progress states. A distinct semantic state — not a primary tint. Pair bg-info with text-info-foreground (a dedicated, mode-aware token); never with text-primary-foreground (which fails WCAG in dark mode).
• Neutral: muted token (gray) - Default, inactive states

​

Module Identity Colors

// ✅ Module accent on a sidebar nav row
<a className="border-l-4 border-module-cl bg-module-cl-subtle/50">Clinical hub</a>

// ❌ Don't use module colors to convey status
<Badge className="bg-module-fa">Approved</Badge> // → Badge variant="success"

​

Chart Palette

// ✅ Theme-aware chart series
<Bar dataKey="value" fill="hsl(var(--chart-1))" />

// ❌ Breaks dark mode and tenant theming
<Bar dataKey="value" fill="#3B82F6" />

​

Typography

• Display/Headings: Space Grotesk - font-heading
• Body/Sans: Inter (primary UI font) - font-sans
• Serif alias: Inter fallback contract (matches body token) - font-serif
• Mono: DM Mono (for code, data) - font-mono

• Fonts are loaded asynchronously in index.html (non-blocking); do not add @import for fonts in CSS.
• Critical inline faces preload Inter and Space Grotesk for first paint parity with design system.
• System font fallbacks are defined in CSS variables.

• Default: font-sans (Inter) for all body/UI text.
• Headings: font-heading (Space Grotesk) for page titles and heading hierarchy.
• Mono: font-mono (DM Mono) for code blocks, data tables, and technical strings.
• Tenant overrides:
  • --tenant-font-family overrides body typography,
  • --tenant-font-heading overrides heading typography. If unset, the canonical Inter + Space Grotesk contract applies.

​

Spacing

​

Button Usage

​

Icons

<AppIcon icon={Check} size="md" className="text-success" />
<AppIcon icon={Trash2} size="sm" decorative={false} aria-label="Delete" />

​

Component Variants

​

Badge Variants

• default - Primary actions, highlights
• secondary - Secondary information
• destructive - Errors, deletions
• outline - Subtle indicators
• success - Success states
• warning - Warning states
• info - Informational states (in progress, new)
• Light variants: success-light, warning-light, destructive-light, primary-light
• Specialty: accentGlow, glass, ai (non-status use cases)

<Badge variant="success">Published</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="destructive">Failed</Badge>
<Badge variant="info">In Progress</Badge>
<Badge variant="outline">Draft</Badge>

​

Button Variants

• default - Neutral elevated (card-like surface); use for secondary emphasis, not the single main CTA
• accent - Brand primary CTA (accent teal); default choice for “Save”, “Submit”, “Continue” when one action dominates
• destructive - Destructive actions
• outline - Secondary actions, toolbars
• secondary - Tertiary / muted actions
• ghost - Subtle actions
• link - Link-style buttons
• success, warning, soft, glass, ai - See JSDoc on src/shared/ui/button.tsx

• default - h-10 px-4 py-2
• sm - h-9 px-3
• lg - h-11 px-8
• icon / icon-touch - h-11 w-11 min 44×44px (square icon buttons; use icon-touch for icon-only actions to meet touch target size)

Note (2026-04-18 audit): The Button size tokens shipped in code currently differ slightly from the table above (default h-9, sm h-8, lg h-10, icon size-11, plus an undocumented xs h-7). Reconciliation is tracked in reports/ux/ux-implementation-plan-20260418.md § Phase 1.2. Until that PR lands, prefer Button size="default" and trust the variant defaults rather than asserting on the height.

​

Tabs

​

Variant decision table

​

What AI must NEVER do (tabs)

• ❌ <TabsList className="grid w-full grid-cols-N"> — equal-width cells break at narrow viewports, no scroll affordance. Wrap with ScrollableTabsList tabsListClassName="sm:grid sm:grid-cols-N".
• ❌ <TabsList className="flex-wrap h-auto"> — wrapping creates uneven heights and breaks the page’s vertical rhythm. Use ScrollableTabsList and let it scroll horizontally instead.
• ❌ Inline h-N overrides on <TabsList> (h-8, h-10, h-11). Use size="compact" only when you need denser controls (e.g. inside a card).
• ❌ Inline (${count}) in trigger labels. Use <TabBadge count={n} /> for the canonical pill style and the aria-label="${count} items" accessibility contract.
• ❌ <TabsList> without aria-label (or aria-labelledby). Pass an explicit label when there is no visible heading.
• ❌ Mobile collapse to icon-only that drops the visible label. At <sm, tabs MUST scroll horizontally OR collapse into a Sheet picker.

​

Quick recipes

import { useTabUrlState } from '@/platform/tabs';
import { ScrollableTabsList } from '@/shared/components/ScrollableTabsList';
import { Tabs, TabsTrigger } from '@/shared/ui/tabs';

const VALID_TABS = ['accounts', 'statements', 'reconciliations', 'transactions'] as const;
const [tab, setTab] = useTabUrlState('tab', VALID_TABS, 'accounts');

<Tabs value={tab} onValueChange={(v) => setTab(v as (typeof VALID_TABS)[number])}>
  <ScrollableTabsList tabsListClassName="sm:grid sm:grid-cols-4" aria-label="Banking sections">
    {VALID_TABS.map((t) => (
      <TabsTrigger key={t} value={t} className="snap-start">{labelFor(t)}</TabsTrigger>
    ))}
  </ScrollableTabsList>
</Tabs>

import { SettingsTabs } from '@/platform/settings/components/SettingsTabs';

<SettingsTabs
  defaultValue="configuration"
  tabsListClassName="sm:grid sm:grid-cols-5"
  items={[
    { value: 'configuration', label: <><Settings className="size-4" aria-hidden="true" /> Configuration</>, content: <ConfigurationTab /> },
    { value: 'transaction-rules', label: <><Filter className="size-4" aria-hidden="true" /> Transaction Rules</>, content: <TransactionRulesTab /> },
    // ...
  ]}
/>

import { TabsTrigger, TabBadge } from '@/shared/ui/tabs';

<TabsTrigger value="pending">
  Pending <TabBadge count={pendingCount} variant="destructive" />
</TabsTrigger>

​

Page Templates

​

Required Page States

​

1. Loading State

// ✅ CORRECT
if (loading) return <PageSkeleton />;

// ❌ WRONG
if (loading) return null;

• List Pages: Grid of skeleton cards/rows
• Detail Pages: Skeleton header + content sections
• Dashboards: Skeleton stat cards + chart placeholders
• Forms: Skeleton form fields

• Route-level: RouteLoadingSkeleton (already implemented)
• Component-level: Use Skeleton component from @/shared/ui/skeleton

​

2. Error State

if (error) {
  return (
    <ErrorState
      title="Failed to load data"
      message={error.message}
      action={<Button onClick={retry}>Try Again</Button>}
    />
  );
}

• Use Alert component with destructive variant
• Include retry/refresh action when applicable
• Show specific error message (not generic “Something went wrong”)

​

3. Empty State

if (items.length === 0) {
  return (
    <EmptyState
      icon={FileText}
      title="No forms yet"
      description="Create your first form to get started"
      action={<Button onClick={createForm}>Create Form</Button>}
    />
  );
}

• Include icon, title, description, and primary action
• Use friendly, helpful copy
• Provide clear next steps

​

Page Template Primitives

• PageContainer - Responsive page wrapper with padding (src/shared/components/PageContainer.tsx)
• OverviewPageWrapper - Standardized wrapper for module overview pages with pull-to-refresh (src/shared/components/OverviewPageWrapper.tsx)
• ResponsiveFormLayout - Form field layout with responsive columns (src/shared/components/ResponsiveFormLayout.tsx)
• MobileTableWrapper - Responsive table wrapper for mobile (src/shared/components/MobileTableWrapper.tsx)

<PageContainer spacing="md">
  <PageHeader title="Page Title" description="Page description" />
  <Card>
    <CardContent>
      {/* Page content */}
    </CardContent>
  </Card>
</PageContainer>

​

Overview Pages

import { OverviewPageWrapper, PageHeader, StatCard } from '@/shared/components';

export default function HROverview() {
  return (
    <OverviewPageWrapper refreshQueryKeys={['hr']} spacing="md">
      <PageHeader
        title="Workforce & HR"
        description="Manage employees and departments"
        icon={Users}
      />
      
      <QuickActionsSection moduleId="hr" ... />
      
      <div className="grid gap-3 md:gap-4 lg:gap-6 md:grid-cols-3">
        {/* Stat cards */}
      </div>
      
      {/* Area navigation cards or widgets */}
    </OverviewPageWrapper>
  );
}

• Automatic mobile pull-to-refresh with query invalidation
• Consistent responsive padding and spacing
• Standardized page structure

• Overview Pages: OverviewPageWrapper for module landing pages
• List Pages: PageContainer + Card for filters + table/list
• Detail Pages: PageContainer + Card sections for different data groups
• Dashboards: PageContainer + grid of stat cards + widgets
• Forms: PageContainer + ResponsiveFormLayout for form fields

​

Navigation & Information Architecture

​

Route Taxonomy

• Module Overview: /{module}/dashboard (e.g., /hr/dashboard)
• Module List: /{module}/{entity} (e.g., /hr/employees)
• Module Detail: /{module}/{entity}/:id (e.g., /hr/employees/123)
• Sub-Module: /{module}/{sub-module}/{entity} (e.g., /hr/ats/jobs)

• Use kebab-case: /hr/employee-directory not /hr/employeeDirectory
• Use plural nouns for list routes: /hr/employees not /hr/employee
• Use singular for detail routes when appropriate: /hr/employees/:id

​

Breadcrumbs

• Detail pages (3+ route segments)
• Nested sub-module pages
• Settings pages with hierarchy

• Module overview pages (/hr/dashboard)
• Top-level list pages (/hr/employees)
• Home/dashboard (/)

• Desktop: Full breadcrumb trail in header (via Breadcrumbs.tsx)
• Mobile: Truncated to last 2 segments (via MobileBreadcrumbs.tsx)
• Depth Limit: Maximum 5 segments (truncate if deeper)

• Auto-generated from route (via route-labels.ts)
• Explicit breadcrumbs via PageContainer breadcrumbs prop for dynamic entity names

​

Module/Sub-Module Navigation

1. All Modules: Shows all available modules (home, module switcher)
2. In Module: Shows module-specific navigation (sidebar with nav items)
3. In Sub-Module: Shows sub-module navigation with “Back to Parent” button

• Sub-modules have overviewRoute (e.g., /hr/ats)
• Sub-modules have navGroups or navItems for sub-navigation
• Sub-modules show context indicator in mobile header

• Navigation items filtered by minRole (V1) or permission (V2)
• Use useFilteredNavItems hook for permission-aware filtering

• docs/architecture/standards/NAVIGATION_STANDARD.md - Navigation patterns and policies
• docs/development/mobile-navigation-guide.md - Mobile navigation patterns
• docs/development/breadcrumb-implementation-guide.md - Breadcrumb implementation
• src/platform/navigation/README.md - Navigation component documentation

​

Mobile-First Requirements

​

Touch Targets

// ✅ CORRECT: Meets minimum
<Button size="icon" className="h-10 w-10"> {/* 40px, but padding makes it 44px+ */}
  <Icon />
</Button>

// ✅ CORRECT: Explicit minimum
<div className="min-h-[44px] min-w-[44px] flex items-center justify-center">
  <Icon />
</div>

// ❌ WRONG: Too small
<button className="h-8 w-8"> {/* 32px - too small */}
  <Icon />
</button>

• Navigation items: min-h-[44px]
• Icon buttons: h-10 w-10 (40px + padding = 44px+)
• Bottom nav items: min-w-[56px] min-h-[56px] (generous for thumb reach)

​

Safe Areas

// ✅ CORRECT: Use safe area utilities
<header className="fixed top-0 safe-area-top">
  {/* Header content */}
</header>

<nav className="fixed bottom-0 safe-area-bottom">
  {/* Bottom nav */}
</nav>

• --safe-area-inset-top - iOS notch, Android status bar
• --safe-area-inset-bottom - iOS home indicator, Android nav bar
• --safe-area-inset-left / --safe-area-inset-right - Landscape safe areas

• .safe-area-top - Adds top padding
• .safe-area-bottom - Adds bottom padding
• .safe-area-left / .safe-area-right - Adds side padding

​

Mobile Header Density

1. Main header (64px) - Logo, menu, actions
2. Org switcher (48px) - Organization/site selector
3. Sub-module indicator (~40px, conditional) - Current sub-module context
4. Breadcrumbs (~40px) - Navigation path

• Collapse When Possible: Combine org switcher into header row when space allows
• Conditional Display: Show breadcrumbs only on 3+ depth routes
• Sub-Module Indicator: Show only when in sub-module context

​

Bottom Navigation

• Fixed bottom position with safe area inset
• 4-5 primary shortcuts (configurable per user/role)
• Long-press for module menu (if implemented)
• Active state indicator

• Minimum 56x56px per nav item (generous for thumb reach)
• Adequate spacing between items

• docs/development/mobile-navigation-guide.md - Complete mobile navigation guide

​

Performance UX

​

Skeleton Loaders

​

List Pages

<div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
  {Array.from({ length: 6 }).map((_, i) => (
    <Card key={i}>
      <CardHeader>
        <Skeleton className="h-6 w-3/4" />
      </CardHeader>
      <CardContent>
        <Skeleton className="h-4 w-full mb-2" />
        <Skeleton className="h-4 w-2/3" />
      </CardContent>
    </Card>
  ))}
</div>

​

Detail Pages

<div className="space-y-6">
  <Skeleton className="h-8 w-1/3" /> {/* Title */}
  <Card>
    <CardHeader>
      <Skeleton className="h-6 w-1/4" />
    </CardHeader>
    <CardContent>
      <Skeleton className="h-4 w-full mb-4" />
      <Skeleton className="h-4 w-3/4" />
    </CardContent>
  </Card>
</div>

​

Dashboards

<div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
  {Array.from({ length: 4 }).map((_, i) => (
    <Card key={i}>
      <CardContent className="p-6">
        <Skeleton className="h-4 w-1/2 mb-2" />
        <Skeleton className="h-8 w-3/4" />
      </CardContent>
    </Card>
  ))}
</div>

​

Route Code Splitting

// ✅ CORRECT: Lazy load route
const Dashboard = lazy(() => import("./platform/dashboard/Dashboard"));

// ❌ WRONG: Direct import
import Dashboard from "./platform/dashboard/Dashboard";

<Suspense fallback={<RouteLoadingSkeleton />}>
  <Routes>
    <Route path="/" element={<Dashboard />} />
  </Routes>
</Suspense>

​

QueryClient Configuration

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,  // 5 minutes
      gcTime: 10 * 60 * 1000,    // 10 minutes (formerly cacheTime)
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
});

​

Performance Targets

• Performance: 85+ (target: 90+)
• Accessibility: 95+ (target: 100)
• Best Practices: 90+ (target: 95+)
• SEO: 90+ (target: 95+)

• First Contentful Paint (FCP): < 2s
• Largest Contentful Paint (LCP): < 2.5s
• Cumulative Layout Shift (CLS): < 0.1
• Time to Interactive (TTI): < 3.5s (on 3G)

• constitution.md §[Performance Requirements] - Non-negotiable performance rules

​

Form UX Standards

​

Form Layout

import { ResponsiveFormLayout } from '@/shared/components';

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
    {/* Full-width field */}
    <FormField name="title" ... />
    
    {/* Two-column layout */}
    <ResponsiveFormLayout columns={2} spacing="md">
      <FormField name="firstName" ... />
      <FormField name="lastName" ... />
    </ResponsiveFormLayout>
    
    {/* Form actions */}
    <div className="flex justify-end gap-3 pt-4">
      <Button variant="outline">Cancel</Button>
      <Button type="submit">Save</Button>
    </div>
  </form>
</Form>

​

Shared Field Pilot

<FieldGroup>
  <Field>
    <FieldLabel htmlFor="tenant-id">Tenant ID</FieldLabel>
    <Input id="tenant-id" value={tenantId} onChange={handleChange} />
    <FieldDescription>Used for Microsoft Entra ID single sign-on.</FieldDescription>
  </Field>
</FieldGroup>

​

Help Text (FormDescription)

• Sensitive data fields (account numbers, passwords)
• Masked/transformed displays (“Will be masked as XXX-7890”)
• Optional fields with non-obvious purpose
• Fields requiring specific formats

• Self-explanatory labels (Name, Email, Phone)
• Required fields with obvious purpose

<FormField name="accountNumber" render={({ field }) => (
  <FormItem>
    <FormLabel>Account Number *</FormLabel>
    <FormControl><Input {...field} /></FormControl>
    <FormDescription>Will be masked in displays (XXX-7890)</FormDescription>
    <FormMessage />
  </FormItem>
)} />

​

Error Presentation

• Errors appear immediately below the field
• Use FormMessage component (styled with text-destructive)
• No error summary at form top (too noisy for most forms)
• For complex forms with many errors, consider scrolling to first error

<FormField name="email" render={({ field }) => (
  <FormItem>
    <FormLabel>Email *</FormLabel>
    <FormControl><Input type="email" {...field} /></FormControl>
    <FormMessage /> {/* Shows error inline */}
  </FormItem>
)} />

​

Progressive Disclosure

<Accordion type="single" collapsible>
  <AccordionItem value="advanced">
    <AccordionTrigger>Advanced Options</AccordionTrigger>
    <AccordionContent>
      <ResponsiveFormLayout columns={2} spacing="md">
        <FormField name="advancedOption1" ... />
        <FormField name="advancedOption2" ... />
      </ResponsiveFormLayout>
    </AccordionContent>
  </AccordionItem>
</Accordion>

​

Form Actions

<div className="flex justify-end gap-3 pt-4">
  <Button type="button" variant="outline" onClick={onCancel} disabled={isSubmitting}>
    Cancel
  </Button>
  <Button type="submit" disabled={isSubmitting}>
    {isSubmitting ? 'Saving...' : 'Save'}
  </Button>
</div>

• Right-aligned buttons (LTR layouts)
• Cancel on left, Submit on right
• Show loading state during submission
• Disable buttons during submission
• Use descriptive labels: “Create Account” vs “Submit”

​

Accessibility

​

Tabbed Hub Accessibility Checklist

• Tab panels have correct ARIA: role="tabpanel" and aria-labelledby linking to the corresponding trigger (Radix/shadcn Tabs provide these by default).
• Focus moves to the active panel on tab change when appropriate (Radix handles this).
• Keyboard navigation: arrow keys move between tabs (Radix/shadcn support this).
• Touch targets: tab triggers meet 44px minimum height (see src/shared/ui/tabs.tsx).
• Hub routes are in scope for accessibility audits (e.g. axe-core); see ACCESSIBILITY_TESTING.md.

​

Keyboard Navigation

• Use semantic HTML (<button>, <a>, <input>, etc.)
• Maintain logical tab order
• Provide skip links for main content
• Support arrow key navigation for lists/menus

• Visible focus indicators on all interactive elements
• Focus trap in modals/dialogs
• Return focus to trigger after closing modal

​

Focus Indicators

// ✅ CORRECT: Visible focus ring
<Button className="focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2">
  Click me
</Button>

// ✅ CORRECT: Custom focus styles
.nav-focus-ring:focus-visible {
  outline: 2px solid hsl(var(--ring));
  outline-offset: 2px;
}

• 2px solid outline
• Use --ring color token
• 2px offset from element
• Only visible on keyboard focus (:focus-visible)

​

ARIA Usage

<label htmlFor="email">Email</label>
<input id="email" type="email" aria-describedby="email-help" />
<span id="email-help">We'll never share your email</span>

<div role="alert" aria-live="polite">
  {errorMessage}
</div>

• aria-live="polite" - Non-urgent updates
• aria-live="assertive" - Urgent updates
• aria-atomic="true" - Announce entire region

​

Contrast Requirements

• Normal Text: 4.5:1 against background
• Large Text (18pt+): 3:1 against background
• UI Components: 3:1 for non-text elements (icons, borders)

• Use browser DevTools contrast checker
• Use tools like WebAIM Contrast Checker
• Test in both light and dark themes

• WCAG 2.1 Guidelines
• WebAIM Contrast Checker

​

Related Documentation

​

Deep Dives

• Navigation Patterns: Navigation Guide Index - Complete navigation documentation index
• Mobile Navigation: docs/development/mobile-navigation-guide.md - Mobile-specific patterns
• Breadcrumbs: docs/development/breadcrumb-implementation-guide.md - Breadcrumb standards
• Spacing & Layout: Spacing & UX Standards - Complete spacing system guide
• Sidebar Adaptive: Spacing & UX Standards - Sidebar patterns and adaptive layout

​

Implementation References

• Design Tokens: src/index.css - CSS variable definitions
• Tailwind token mapping: src/index.css (@theme inline) - Token mappings
• Shared Components: src/shared/components/ - Page templates and layouts
• UI Components: src/shared/ui/ - Base UI component library
• Navigation Components: src/platform/navigation/ - Navigation system

​

Constitution & Guidelines

• Constitution: constitution.md - Non-negotiable engineering guardrails
• AI Guide: AI_GUIDE.md - AI contribution guidelines
• Quick Reference: AGENTS.md - Condensed cross-platform reference

​

Shared Component Primitives

​

PageHeader

import { PageHeader } from '@/shared/components/PageHeader';

<PageHeader
  title="Employees"
  description="Manage your organization's workforce"
  actions={<Button>Add Employee</Button>}
/>

• title (required) - Page title (h1)
• description (optional) - Page subtitle
• actions (optional) - Action buttons/components
• breadcrumbs (optional) - Custom breadcrumb items

​

StatCard

import { StatCard } from '@/shared/components/StatCard';

<StatCard
  title="Total Employees"
  value={142}
  icon={Users}
  trend={{ value: 12, direction: 'up' }}
/>

• title (required) - Metric label
• value (required) - Metric value (number or string)
• icon (optional) - Lucide icon component
• trend (optional) - Trend indicator with value and direction
• description (optional) - Additional context

​

EmptyState

import { EmptyState } from '@/shared/components/EmptyState';

<EmptyState
  icon={FileText}
  title="No forms yet"
  description="Create your first form to get started"
  action={<Button onClick={createForm}>Create Form</Button>}
/>

​

CardActionsMenu

import { CardActionsMenu } from '@/shared/components/CardActionsMenu';

<CardActionsMenu
  actions={[
    { label: 'Edit', icon: Edit, onClick: handleEdit },
    { label: 'Delete', icon: Trash, onClick: handleDelete, variant: 'destructive' },
  ]}
/>

• Minimum 44x44px touch target
• Always visible (not hover-only)
• Uses DropdownMenu for mobile-friendly interaction

​

Color Mapping Utilities

​

Import Pattern

import { 
  getStatusColors, 
  getScoreColor,
  semanticColorClasses,
  type SemanticStatus 
} from '@/shared/lib/semantic-colors';

​

Status Color Mapping

const statusMap: Record<string, SemanticStatus> = {
  active: 'success',
  pending: 'warning',
  expired: 'destructive',
  draft: 'muted',
};

const colors = getStatusColors(statusMap[status] || 'muted');
// Returns: { bg, bgSubtle, text, border, full }

​

Anti-Patterns

const getColor = (status: string) => {
  switch (status) {
    case 'active': return 'bg-green-100 text-green-800';
    case 'pending': return 'bg-yellow-100 text-yellow-800';
    default: return 'bg-gray-100 text-gray-800';
  }
};

import { getStatusColors } from '@/shared/lib/semantic-colors';

const statusMap = { active: 'success', pending: 'warning' } as const;
const colors = getStatusColors(statusMap[status] || 'muted');

​

Touch-Safe Action Patterns

​

Requirements

1. Always visible actions - Never hide actions behind hover-only states
2. 44x44px minimum - All touch targets must meet minimum size
3. Menu for multiple actions - Use CardActionsMenu or DropdownMenu for 2+ actions
4. Single primary action visible - Show most common action directly, others in menu

​

Hover-Only Anti-Pattern

<Card className="group">
  <CardActions className="opacity-0 group-hover:opacity-100">
    <Button size="icon" className="h-8 w-8">
      <Edit className="h-4 w-4" />
    </Button>
  </CardActions>
</Card>

<Card>
  <CardActionsMenu
    actions={[
      { label: 'Edit', icon: Edit, onClick: handleEdit },
      { label: 'Delete', icon: Trash, onClick: handleDelete },
    ]}
  />
</Card>

​

Mobile Considerations

• Use DropdownMenu instead of hover menus
• Ensure action buttons are at least 44x44px
• Place actions in consistent locations (top-right corner)
• Use swipe gestures sparingly and always provide alternatives

​

Dialog vs Native Browser Dialogs

​

CRITICAL: Never Use Native Dialogs

• Not accessible
• Not stylable
• Inconsistent across browsers
• Not mobile-friendly
• Cannot be canceled properly

​

Use Custom Dialogs Instead

import { AlertDialog } from '@/shared/ui/alert-dialog';

<AlertDialog>
  <AlertDialogTrigger>Delete</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

import { Dialog } from '@/shared/ui/dialog';
import { Input } from '@/shared/ui/input';

<Dialog>
  <DialogTrigger>Rename</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Rename Document</DialogTitle>
    </DialogHeader>
    <Input
      value={newName}
      onChange={(e) => setNewName(e.target.value)}
      placeholder="Enter new name"
    />
    <DialogFooter>
      <Button variant="outline" onClick={close}>Cancel</Button>
      <Button onClick={handleRename}>Rename</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

import { toast } from 'sonner';

// Success
toast.success('Document saved successfully');

// Error
toast.error('Failed to save document');

// Info
toast.info('Processing your request...');

​

Mobile Gestures

​

Required Gesture Patterns

​

Implementation

import { SwipeableListItem, PullToRefresh } from '@/platform/gestures';

// List with swipe actions and pull-to-refresh
<PullToRefresh onRefresh={handleRefresh}>
  <ul>
    {items.map(item => (
      <SwipeableListItem
        key={item.id}
        leftActions={[
          { id: 'delete', label: 'Delete', colorClass: 'destructive', onClick: () => onDelete(item.id) }
        ]}
      >
        <ItemContent item={item} />
      </SwipeableListItem>
    ))}
  </ul>
</PullToRefresh>

​

Accessibility Requirements

• All gestures MUST have keyboard alternatives
• Escape closes sheets/dialogs
• Delete triggers destructive actions
• Tap/click fallback always available

​

Troubleshooting Common UI/UX Issues

​

Colors Not Applying Correctly

// ❌ WRONG: Hardcoded colors
<div className="text-green-500">Success</div>

// ✅ CORRECT: Use semantic tokens
<div className="text-success">Success</div>
<Badge variant="success">Active</Badge>

1. Verify token exists in src/index.css under @theme inline and/or root CSS variables
2. Check CSS variables in src/index.css
3. Ensure proper variant usage for components

​

Loading States Showing Blank Screen

// ❌ WRONG: Return null
if (isLoading) return null;

// ✅ CORRECT: Use skeleton loader
if (isLoading) return <AppLoadingSkeleton />;

​

Components Not Responsive

1. Check for fixed widths: Remove w-{fixed} classes
2. Use responsive utilities: md:, lg: breakpoints
3. Verify mobile-first approach: Start with mobile, enhance for desktop
4. Test on actual devices: Use browser dev tools mobile emulation

​

Accessibility Issues

// ❌ WRONG: Missing labels
<button onClick={handleDelete}>
  <Trash2 />
</button>

// ✅ CORRECT: Include accessibility attributes
<button 
  onClick={handleDelete}
  aria-label="Delete item"
>
  <Trash2 />
</button>

​

Performance Issues

1. Check lazy loading: Ensure routes use React.lazy()
2. Verify code splitting: Check bundle sizes
3. Optimize images: Use appropriate formats and sizes
4. Check query optimization: Review TanStack Query configuration
5. See Performance Optimization Guide for detailed guidance

​

Design System Tokens Not Found

1. Verify token exists in src/index.css under @theme inline and/or root CSS variables
2. Check TypeScript types: Ensure Tailwind types are generated
3. Restart TypeScript server: Reload VS Code window
4. Check import paths: Verify @/ alias configuration

​

Mobile Touch Targets Too Small

// ❌ WRONG: Small touch target
<button className="p-2">Action</button>

// ✅ CORRECT: Minimum 44x44px
<button className="min-w-[44px] min-h-[44px] p-3">Action</button>

​

Inconsistent Component Variants

1. Use standard variants: variant="success", variant="destructive"
2. Avoid custom styling: Don’t override component styles
3. Check design system: Verify variant exists in component definition
4. Use semantic tokens: Don’t hardcode colors