UI Design

UI Design

Contract-first static UI methodology using TypeScript interfaces and compound components.

Purpose

UI Design is the second step in the UI development workflow, following wireframing. Define TypeScript interfaces first (the "contract"), then implement compound components with Tailwind CSS styling. Server Components are the default.

When to Use

• After wireframes are approved (WIREFRAME.md exists)
• When implementing new UI components
• When creating reusable component libraries
• When defining component APIs with TypeScript

Core Principles

Contract-First Development

Define TypeScript interfaces before implementation:

// 1. Define the contract first
interface FeatureCardProps {
  title: string;
  description: string;
  icon: IconName;
  href?: string;
}

// 2. Then implement the component
function FeatureCard({ title, description, icon, href }: FeatureCardProps) {
  // Implementation
}

Server Components by Default

All components are React Server Components unless they need:

• Event handlers (onClick, onChange)
• Browser APIs (localStorage, window)
• React hooks (useState, useEffect)

// Server Component (default) - no "use client" directive
export function FeatureCard({ title, description }: FeatureCardProps) {
  return (
    <article className="rounded-lg border p-6">
      <h3 className="text-lg font-semibold">{title}</h3>
      <p className="text-muted-foreground">{description}</p>
    </article>
  );
}

Compound Component Pattern

Structure complex components with composable parts:

// Root component provides context
function Card({ children, className }: CardProps) {
  return (
    <div className={cn("rounded-lg border bg-card", className)}>
      {children}
    </div>
  );
}

// Sub-components for each section
function CardHeader({ children, className }: CardHeaderProps) {
  return (
    <div className={cn("flex flex-col space-y-1.5 p-6", className)}>
      {children}
    </div>
  );
}

function CardTitle({ children, className }: CardTitleProps) {
  return (
    <h3 className={cn("text-2xl font-semibold", className)}>
      {children}
    </h3>
  );
}

function CardContent({ children, className }: CardContentProps) {
  return (
    <div className={cn("p-6 pt-0", className)}>
      {children}
    </div>
  );
}

function CardFooter({ children, className }: CardFooterProps) {
  return (
    <div className={cn("flex items-center p-6 pt-0", className)}>
      {children}
    </div>
  );
}

// Export compound component
export { Card, CardHeader, CardTitle, CardContent, CardFooter };