Data to UI

Overview

Patterns for transforming static data into type-safe React components. This skill covers JSON → TypeScript → React pipelines with emphasis on semantic color systems, derived types, and formatting utilities.

Workflows

1. JSON Schema → TypeScript Types

• Read JSON schema/data structure
• Create base TypeScript interfaces matching JSON shape
• Export union types for enums (e.g.,

  type Severity = 'safety_hazard' | 'repair_needed'

  )
• Use optional properties (

  ?

  ) for nullable/missing fields
• Add JSDoc comments for complex types

2. Derived Types for UI

• Create composed types extending base types with

  extends

• Use

  Pick<T, K>

  and

  Omit<T, K>

  for component props
• Build intersection types with

  &

  for joined data (e.g.,

  FindingWithAsset

  )
• Create aggregate interfaces for statistics/summaries

3. Color Mapping Systems

• Define

  Record<EnumType, ColorValue>

  for semantic colors
• Provide multiple color formats: badge, bg, text, border, dot
• Use Tailwind utility classes (e.g.,

  'bg-red-500 text-red-600'

  )
• Export accessor functions (e.g.,

  getSeverityColors()

  )
• Document color choices with comments

4. Icon Mapping

• Create

  Record<EnumType, string>

  mapping to lucide-react icon names
• Use PascalCase icon names (e.g.,

  'AlertTriangle'

  ,

  'Thermometer'

  )
• Export accessor function (e.g.,

  getSeverityIcon()

  )

5. Formatting Utilities

• Currency: Use

  Intl.NumberFormat

  with USD, no decimals
• Dates: Use

  toLocaleDateString

  with short month format
• Calculations: Create helpers for years, percentages, lifespans
• Labels: Create human-readable label maps

6. Aggregation & Grouping

• Implement

  groupBy

  patterns using reduce or forEach
• Sort with custom comparators using severity/priority order
• Calculate summary statistics (min, max, avg, count)
• Return strongly-typed aggregates

Reference Implementation

Color Mapping System

// Single source of truth for semantic colors
export interface SeverityColors {
  badge: string;  // 'text-red-600 bg-red-100'
  bg: string;     // 'bg-red-500'
  text: string;   // 'text-red-600'
  border: string; // 'border-red-500'
  dot: string;    // 'bg-red-500'
}

const SEVERITY_COLOR_MAP: Record<Severity, SeverityColors> = {
  safety_hazard: {
    badge: 'text-red-600 bg-red-100',
    bg: 'bg-red-500',
    text: 'text-red-600',
    dot: 'bg-red-500',
    border: 'border-red-500',
  },
  // ... other severities
};

export function getSeverityColors(severity: Severity): SeverityColors {
  return SEVERITY_COLOR_MAP[severity];
}

Icon Mapping

export function getSeverityIcon(severity: Severity): string {
  const icons: Record<Severity, string> = {
    safety_hazard: 'AlertTriangle',
    repair_needed: 'Wrench',
    maintenance_item: 'Settings',
    monitor: 'Eye',
    informational: 'Info'
  };
  return icons[severity];
}

Derived Types

// Base type
export interface Finding {
  id: string;
  assetId?: string | null;
  severity: Severity;
  title: string;
}

// Derived type with relationship
export interface FindingWithAsset extends Finding {
  asset?: Asset;
}

// Aggregate type
export interface PropertyWithDetails {
  property: Property;
  inspectionReport: InspectionReport;
  findings: Finding[];
  assets: Asset[];
}

Formatting Utilities

export function formatCurrency(value: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
    minimumFractionDigits: 0,
    maximumFractionDigits: 0
  }).format(value);
}

export function formatDate(dateString: string): string {
  return new Date(dateString).toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'short',
    day: 'numeric'
  });
}

export function yearsSince(dateString: string): number {
  const date = new Date(dateString);
  const now = new Date();
  return Math.floor((now.getTime() - date.getTime()) / (365.25 * 24 * 60 * 60 * 1000));
}

Aggregation Patterns

// Group by enum value
export function groupFindingsBySeverity(findings: Finding[]): Record<Severity, Finding[]> {
  const grouped: Record<Severity, Finding[]> = {
    safety_hazard: [],
    repair_needed: [],
    maintenance_item: [],
    monitor: [],
    informational: []
  };

  findings.forEach(f => grouped[f.severity].push(f));
  return grouped;
}

// Sort by priority
export function sortFindingsBySeverity(findings: Finding[]): Finding[] {
  const severityOrder: Record<Severity, number> = {
    safety_hazard: 0,
    repair_needed: 1,
    maintenance_item: 2,
    monitor: 3,
    informational: 4
  };
  return [...findings].sort((a, b) =>
    severityOrder[a.severity] - severityOrder[b.severity]
  );
}

Best Practices

• Single Source of Truth: All color/icon mappings in one place with accessor functions
• Multi-Format Colors: Provide badge, bg, text, border, dot variants for flexibility
• Type Safety: Use

  Record<EnumType, Value>

  instead of plain objects
• Intl APIs: Use

  Intl.NumberFormat

  and

  Intl.DateTimeFormat

  for localization
• Immutability: Use spread operator when sorting/filtering arrays
• Documentation: Add JSDoc comments explaining color choices and data structures
• Colocate Utilities: Keep types and utilities in same file for easy import

Anti-Patterns

• DO NOT use generic color names without semantic meaning (e.g.,

  'red'

  instead of

  'safety_hazard'

  )
• DO NOT inline color classes in components; always use mapping functions
• DO NOT use

  any

  types; prefer

  unknown

  and type guards
• DO NOT mutate input arrays in sort/filter functions; always create copies
• DO NOT hardcode date formats; use

  Intl.DateTimeFormat

  for consistency
• DO NOT create separate files for simple utilities; colocate with types
• DO NOT forget to handle null/undefined in optional fields
• DO NOT use snake_case or kebab-case for TypeScript file names; use camelCase

Feedback Loops

1. Type Checking: Run

   tsc --noEmit

   to validate types
2. Runtime Validation: Consider Zod for JSON schema validation at runtime
3. Visual Testing: Build Storybook stories to verify color systems
4. Data Consistency: Compare aggregated stats with source data counts
5. Import Verification: Ensure all utilities are exported and importable

Related Skills

• interface-design

  - Use color systems in React components

• refactoring-code

  - Consolidate duplicate color/formatting logic