Skip to main content

Component Kit: React Implementation Guide

Complete code examples for production use

Setup Instructions​

1. Project Structure​

mkdir -p src/components/{atoms,molecules,organisms,H.P.008-TEMPLATES}
mkdir -p src/design-tokens
mkdir -p src/tests/{unit,integration,visual,accessibility}

2. Design Tokens (Foundation)​

src/design-tokens/index.css

:root {
  /* Colors */
  --color-white: #FFFFFF;
  --color-gray-50: #F9FAFB;
  --color-gray-100: #F3F4F6;
  --color-gray-200: #E5E7EB;
  --color-gray-300: #D1D5DB;
  --color-gray-400: #9CA3AF;
  --color-gray-500: #6B7280;
  --color-gray-600: #4B5563;
  --color-gray-700: #374151;
  --color-gray-800: #1F2937;
  --color-gray-900: #111827;
  
  --color-blue-50: #EFF6FF;
  --color-blue-500: #3B82F6;
  --color-blue-600: #2563EB;
  --color-blue-700: #1D4ED8;
  
  --color-green-50: #ECFDF5;
  --color-green-500: #10B981;
  --color-green-700: #047857;
  
  --color-yellow-50: #FFFBEB;
  --color-yellow-500: #F59E0B;
  --color-yellow-700: #B45309;
  
  --color-red-50: #FEF2F2;
  --color-red-500: #EF4444;
  --color-red-700: #B91C1C;
  
  /* Spacing (8px grid) */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;
  --space-16: 64px;
  
  /* Typography */
  --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-size-xs: 12px;
  --font-size-sm: 14px;
  --font-size-base: 16px;
  --font-size-lg: 18px;
  --font-size-xl: 20px;
  --font-size-2xl: 24px;
  --font-size-3xl: 32px;
  
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
  
  --line-height-tight: 1.2;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.6;
  
  /* Borders */
  --border-radius-sm: 4px;
  --border-radius-md: 6px;
  --border-radius-lg: 8px;
  --border-radius-xl: 12px;
  --border-radius-full: 9999px;
  
  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
  --shadow-md: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --shadow-xl: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
  
  /* Transitions */
  --transition-fast: 150ms ease;
  --transition-base: 200ms ease;
  --transition-slow: 300ms ease;
  
  /* Z-index */
  --z-dropdown: 1000;
  --z-modal: 1100;
  --z-toast: 1200;
}

/* Dark theme support */
[data-theme="dark"] {
  --color-gray-50: #1F2937;
  --color-gray-100: #374151;
  --color-gray-900: #F9FAFB;
  /* ... more dark theme overrides */
}

ATOMS - Complete Implementations​

Button Component​

src/components/atoms/Button/Button.jsx

import React from 'react';
import PropTypes from 'prop-types';
import './Button.css';

/**
 * Button component - Primary action trigger
 * 
 * Test Requirements:
 * - Height: 40px minimum (44px for accessibility)
 * - Border radius: 6px
 * - Font weight: 500
 * - Keyboard accessible
 * - Focus visible
 * - Color contrast: 4.5:1 minimum
 */
export const Button = ({
  children,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  loading = false,
  icon,
  iconPosition = 'left',
  fullWidth = false,
  onClick,
  type = 'button',
  className = '',
  ...props
}) => {
  const baseClass = 'btn';
  const variantClass = `btn--${variant}`;
  const sizeClass = `btn--${size}`;
  const loadingClass = loading ? 'btn--loading' : '';
  const fullWidthClass = fullWidth ? 'btn--full-width' : '';
  const iconOnlyClass = icon && !children ? 'btn--icon-only' : '';
  
  const classes = [
    baseClass,
    variantClass,
    sizeClass,
    loadingClass,
    fullWidthClass,
    iconOnlyClass,
    className
  ].filter(Boolean).join(' ');
  
  const handleClick = (e) => {
    if (!disabled && !loading && onClick) {
      onClick(e);
    }
  };
  
  return (
    <button
      type={type}
      className={classes}
      disabled={disabled || loading}
      onClick={handleClick}
      data-testid="button"
      {...props}
    >
      {loading && (
        <span className="btn__spinner" data-testid="button-spinner">
          <svg className="spinner" viewBox="0 0 24 24">
            <circle
              className="spinner__circle"
              cx="12"
              cy="12"
              r="10"
              fill="none"
              strokeWidth="3"
            />
          </svg>
        </span>
      )}
      
      {!loading && icon && iconPosition === 'left' && (
        <span className="btn__icon btn__icon--left">{icon}</span>
      )}
      
      {children && <span className="btn__text">{children}</span>}
      
      {!loading && icon && iconPosition === 'right' && (
        <span className="btn__icon btn__icon--right">{icon}</span>
      )}
    </button>
  );
};

Button.propTypes = {
  children: PropTypes.node,
  variant: PropTypes.oneOf(['primary', 'secondary', 'danger', 'ghost']),
  size: PropTypes.oneOf(['small', 'medium', 'large']),
  disabled: PropTypes.bool,
  loading: PropTypes.bool,
  icon: PropTypes.node,
  iconPosition: PropTypes.oneOf(['left', 'right']),
  fullWidth: PropTypes.bool,
  onClick: PropTypes.func,
  type: PropTypes.oneOf(['button', 'submit', 'reset']),
  className: PropTypes.string
};

src/components/atoms/Button/Button.css

.btn {
  /* Base styles */
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--space-2);
  height: 44px; /* Minimum touch target */
  padding: 0 var(--space-5);
  border: none;
  border-radius: var(--border-radius-md);
  font-family: var(--font-family);
  font-size: var(--font-size-sm);
  font-weight: var(--font-weight-medium);
  line-height: 1;
  cursor: pointer;
  transition: all var(--transition-base);
  user-select: none;
  white-space: nowrap;
}

/* Variants */
.btn--primary {
  background: var(--color-blue-500);
  color: var(--color-white);
}

.btn--primary:hover:not(:disabled) {
  background: var(--color-blue-600);
}

.btn--primary:active:not(:disabled) {
  background: var(--color-blue-700);
}

.btn--secondary {
  background: var(--color-gray-200);
  color: var(--color-gray-900);
}

.btn--secondary:hover:not(:disabled) {
  background: var(--color-gray-300);
}

.btn--danger {
  background: var(--color-red-50);
  color: var(--color-red-700);
}

.btn--danger:hover:not(:disabled) {
  background: var(--color-red-500);
  color: var(--color-white);
}

.btn--ghost {
  background: transparent;
  color: var(--color-gray-700);
}

.btn--ghost:hover:not(:disabled) {
  background: var(--color-gray-100);
}

/* Sizes */
.btn--small {
  height: 36px;
  padding: 0 var(--space-3);
  font-size: var(--font-size-xs);
}

.btn--large {
  height: 52px;
  padding: 0 var(--space-8);
  font-size: var(--font-size-base);
}

/* States */
.btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

.btn:focus-visible {
  outline: 2px solid var(--color-blue-500);
  outline-offset: 2px;
}

.btn--loading {
  pointer-events: none;
}

.btn--full-width {
  width: 100%;
}

.btn--icon-only {
  width: 44px;
  padding: 0;
}

.btn--icon-only.btn--small {
  width: 36px;
}

.btn--icon-only.btn--large {
  width: 52px;
}

/* Elements */
.btn__spinner {
  display: inline-flex;
  width: 16px;
  height: 16px;
}

.spinner {
  animation: spin 0.6s linear infinite;
}

.spinner__circle {
  stroke: currentColor;
  stroke-linecap: round;
  stroke-dasharray: 60;
  stroke-dashoffset: 45;
  transform-origin: center;
}

@keyframes spin {
  to {
    transform: rotate(360deg);
  }
}

.btn__icon {
  display: inline-flex;
  width: 16px;
  height: 16px;
}

.btn__icon svg {
  width: 100%;
  height: 100%;
}

src/components/atoms/Button/Button.test.js

import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  describe('Rendering', () => {
    test('renders with text', () => {
      render(<Button>Click me</Button>);
      expect(screen.getByText('Click me')).toBeInTheDocument();
    });
    
    test('renders with icon', () => {
      const icon = <svg data-testid="icon" />;
      render(<Button icon={icon}>Click</Button>);
      expect(screen.getByTestId('icon')).toBeInTheDocument();
    });
    
    test('renders loading state', () => {
      render(<Button loading>Click</Button>);
      expect(screen.getByTestId('button-spinner')).toBeInTheDocument();
    });
    
    test('renders disabled state', () => {
      render(<Button disabled>Click</Button>);
      expect(screen.getByTestId('button')).toBeDisabled();
    });
  });
  
  describe('Interactions', () => {
    test('calls onClick when clicked', () => {
      const handleClick = jest.fn();
      render(<Button onClick={handleClick}>Click</Button>);
      
      fireEvent.click(screen.getByTestId('button'));
      expect(handleClick).toHaveBeenCalledTimes(1);
    });
    
    test('does not call onClick when disabled', () => {
      const handleClick = jest.fn();
      render(<Button disabled onClick={handleClick}>Click</Button>);
      
      fireEvent.click(screen.getByTestId('button'));
      expect(handleClick).not.toHaveBeenCalled();
    });
    
    test('does not call onClick when loading', () => {
      const handleClick = jest.fn();
      render(<Button loading onClick={handleClick}>Click</Button>);
      
      fireEvent.click(screen.getByTestId('button'));
      expect(handleClick).not.toHaveBeenCalled();
    });
  });
  
  describe('Variants', () => {
    test('renders primary variant', () => {
      render(<Button variant="primary">Click</Button>);
      expect(screen.getByTestId('button')).toHaveClass('btn--primary');
    });
    
    test('renders secondary variant', () => {
      render(<Button variant="secondary">Click</Button>);
      expect(screen.getByTestId('button')).toHaveClass('btn--secondary');
    });
    
    test('renders danger variant', () => {
      render(<Button variant="danger">Click</Button>);
      expect(screen.getByTestId('button')).toHaveClass('btn--danger');
    });
  });
  
  describe('Accessibility', () => {
    test('has correct type attribute', () => {
      render(<Button type="submit">Submit</Button>);
      expect(screen.getByTestId('button')).toHaveAttribute('type', 'submit');
    });
    
    test('is keyboard accessible', () => {
      const handleClick = jest.fn();
      render(<Button onClick={handleClick}>Click</Button>);
      
      const button = screen.getByTestId('button');
      button.focus();
      fireEvent.keyDown(button, { key: 'Enter' });
      
      expect(document.activeElement).toBe(button);
    });
  });
});

src/components/atoms/Button/Button.stories.jsx

import { Button } from './Button';

export default {
  title: 'Atoms/Button',
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger', 'ghost']
    },
    size: {
      control: 'select',
      options: ['small', 'medium', 'large']
    }
  }
};

export const Primary = {
  args: {
    variant: 'primary',
    children: 'Primary Button'
  }
};

export const Secondary = {
  args: {
    variant: 'secondary',
    children: 'Secondary Button'
  }
};

export const WithIcon = {
  args: {
    variant: 'primary',
    icon: <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
      <path d="M8 2v12M2 8h12" stroke="currentColor" strokeWidth="2"/>
    </svg>,
    children: 'Add Project'
  }
};

export const Loading = {
  args: {
    variant: 'primary',
    loading: true,
    children: 'Loading...'
  }
};

export const Disabled = {
  args: {
    variant: 'primary',
    disabled: true,
    children: 'Disabled'
  }
};

export const FullWidth = {
  args: {
    variant: 'primary',
    fullWidth: true,
    children: 'Full Width Button'
  }
};

MOLECULES - Status Indicator​

src/components/molecules/StatusIndicator/StatusIndicator.jsx

import React from 'react';
import PropTypes from 'prop-types';
import './StatusIndicator.css';

/**
 * StatusIndicator - Combines dot + label for status display
 * 
 * Test Requirements:
 * - Dot and text aligned center
 * - Gap: 8px
 * - Color consistency (dot matches semantic meaning)
 * - Accessible (role="img" on dot, aria-label with full status)
 */
export const StatusIndicator = ({
  status = 'inactive',
  label,
  size = 'medium',
  showPulse = false,
  className = '',
  ...props
}) => {
  const statusColors = {
    success: 'var(--color-green-500)',
    warning: 'var(--color-yellow-500)',
    error: 'var(--color-red-500)',
    info: 'var(--color-blue-500)',
    inactive: 'var(--color-gray-400)'
  };
  
  const statusLabels = {
    success: 'Success',
    warning: 'Warning',
    error: 'Error',
    info: 'Info',
    inactive: 'Inactive'
  };
  
  const displayLabel = label || statusLabels[status];
  const dotColor = statusColors[status];
  
  return (
    <div
      className={`status-indicator status-indicator--${size} ${className}`}
      role="status"
      aria-label={displayLabel}
      data-testid="status-indicator"
      {...props}
    >
      <span
        className={`status-indicator__dot ${showPulse ? 'status-indicator__dot--pulse' : ''}`}
        style={{ backgroundColor: dotColor }}
        role="img"
        aria-label={`${status} status`}
        data-testid="status-dot"
      />
      <span className="status-indicator__label" data-testid="status-label">
        {displayLabel}
      </span>
    </div>
  );
};

StatusIndicator.propTypes = {
  status: PropTypes.oneOf(['success', 'warning', 'error', 'info', 'inactive']),
  label: PropTypes.string,
  size: PropTypes.oneOf(['small', 'medium', 'large']),
  showPulse: PropTypes.bool,
  className: PropTypes.string
};

src/components/molecules/StatusIndicator/StatusIndicator.css

.status-indicator {
  display: inline-flex;
  align-items: center;
  gap: var(--space-2);
}

.status-indicator__dot {
  width: 8px;
  height: 8px;
  border-radius: var(--border-radius-full);
  flex-shrink: 0;
}

.status-indicator__dot--pulse {
  animation: pulse 2s ease-in-out infinite;
}

@keyframes pulse {
  0%, 100% {
    opacity: 1;
  }
  50% {
    opacity: 0.5;
  }
}

.status-indicator__label {
  font-size: var(--font-size-sm);
  color: var(--color-gray-700);
  line-height: 1;
}

/* Size variants */
.status-indicator--small .status-indicator__dot {
  width: 6px;
  height: 6px;
}

.status-indicator--small .status-indicator__label {
  font-size: var(--font-size-xs);
}

.status-indicator--large .status-indicator__dot {
  width: 12px;
  height: 12px;
}

.status-indicator--large .status-indicator__label {
  font-size: var(--font-size-base);
}

src/components/molecules/StatusIndicator/StatusIndicator.test.js

import { render, screen } from '@testing-library/react';
import { StatusIndicator } from './StatusIndicator';

describe('StatusIndicator', () => {
  test('renders dot and label', () => {
    render(<StatusIndicator status="success" />);
    
    expect(screen.getByTestId('status-dot')).toBeInTheDocument();
    expect(screen.getByTestId('status-label')).toBeInTheDocument();
  });
  
  test('uses correct color for status', () => {
    render(<StatusIndicator status="success" />);
    
    const dot = screen.getByTestId('status-dot');
    const styles = window.getComputedStyle(dot);
    
    expect(styles.backgroundColor).toBeTruthy();
  });
  
  test('shows custom label', () => {
    render(<StatusIndicator status="success" label="All Systems Operational" />);
    
    expect(screen.getByText('All Systems Operational')).toBeInTheDocument();
  });
  
  test('has proper ARIA attributes', () => {
    render(<StatusIndicator status="success" />);
    
    const container = screen.getByTestId('status-indicator');
    expect(container).toHaveAttribute('role', 'status');
    expect(container).toHaveAttribute('aria-label');
  });
});

ORGANISMS - Card Component​

src/components/organisms/Card/Card.jsx

import React from 'react';
import PropTypes from 'prop-types';
import './Card.css';

/**
 * Card - Reusable content container
 * 
 * Test Requirements:
 * - Semantic HTML (article/section)
 * - Proper heading hierarchy
 * - Hover state (if clickable)
 * - Shadow elevation
 */
export const Card = ({
  title,
  subtitle,
  children,
  header,
  footer,
  metadata,
  clickable = false,
  onClick,
  className = '',
  ...props
}) => {
  const handleClick = (e) => {
    if (clickable && onClick) {
      onClick(e);
    }
  };
  
  const handleKeyDown = (e) => {
    if (clickable && onClick && (e.key === 'Enter' || e.key === ' ')) {
      e.preventDefault();
      onClick(e);
    }
  };
  
  return (
    <article
      className={`card ${clickable ? 'card--clickable' : ''} ${className}`}
      onClick={handleClick}
      onKeyDown={handleKeyDown}
      tabIndex={clickable ? 0 : undefined}
      role={clickable ? 'button' : undefined}
      data-testid="card"
      {...props}
    >
      {header && (
        <div className="card__header" data-testid="card-header">
          {header}
        </div>
      )}
      
      {(title || subtitle) && (
        <div className="card__title-group">
          {title && (
            <h3 className="card__title" data-testid="card-title">
              {title}
            </h3>
          )}
          {subtitle && (
            <div className="card__subtitle" data-testid="card-subtitle">
              {subtitle}
            </div>
          )}
        </div>
      )}
      
      {metadata && (
        <div className="card__metadata" data-testid="card-metadata">
          {metadata}
        </div>
      )}
      
      {children && (
        <div className="card__content" data-testid="card-content">
          {children}
        </div>
      )}
      
      {footer && (
        <div className="card__footer" data-testid="card-footer">
          {footer}
        </div>
      )}
    </article>
  );
};

Card.propTypes = {
  title: PropTypes.node,
  subtitle: PropTypes.node,
  children: PropTypes.node,
  header: PropTypes.node,
  footer: PropTypes.node,
  metadata: PropTypes.node,
  clickable: PropTypes.bool,
  onClick: PropTypes.func,
  className: PropTypes.string
};

src/components/organisms/Card/Card.css

.card {
  background: var(--color-white);
  border-radius: var(--border-radius-lg);
  padding: var(--space-5);
  box-shadow: var(--shadow-md);
  transition: all var(--transition-base);
}

.card--clickable {
  cursor: pointer;
}

.card--clickable:hover {
  box-shadow: var(--shadow-lg);
  transform: translateY(-2px);
}

.card--clickable:focus-visible {
  outline: 2px solid var(--color-blue-500);
  outline-offset: 2px;
}

.card__header {
  margin-bottom: var(--space-4);
}

.card__title-group {
  margin-bottom: var(--space-4);
}

.card__title {
  font-size: var(--font-size-lg);
  font-weight: var(--font-weight-semibold);
  color: var(--color-gray-900);
  margin: 0 0 var(--space-2) 0;
  line-height: var(--line-height-tight);
}

.card__subtitle {
  font-size: var(--font-size-sm);
  color: var(--color-gray-600);
  margin: 0;
}

.card__metadata {
  display: flex;
  align-items: center;
  gap: var(--space-3);
  margin-bottom: var(--space-4);
  font-size: var(--font-size-sm);
  color: var(--color-gray-600);
}

.card__content {
  margin-bottom: var(--space-4);
}

.card__content:last-child {
  margin-bottom: 0;
}

.card__footer {
  padding-top: var(--space-4);
  border-top: 1px solid var(--color-gray-200);
}

Composition Example: Dashboard​

src/pages/Dashboard.jsx

import React from 'react';
import { Button } from '../components/atoms/Button';
import { StatusIndicator } from '../components/molecules/StatusIndicator';
import { Card } from '../components/organisms/Card';

export const Dashboard = () => {
  const projects = [
    {
      id: 1,
      title: 'Website Redesign',
      status: 'success',
      progress: 75,
      team: ['Alice', 'Bob', 'Charlie']
    },
    // ... more projects
  ];
  
  return (
    <div className="dashboard">
      <div className="dashboard__header">
        <div>
          <h1>Projects</h1>
          <p>{projects.length} active projects</p>
        </div>
        <Button variant="primary">+ New Project</Button>
      </div>
      
      <div className="dashboard__grid">
        {projects.map(project => (
          <Card
            key={project.id}
            title={project.title}
            subtitle={
              <StatusIndicator
                status={project.status}
                label="Active"
              />
            }
            clickable
            onClick={() => console.log('Navigate to project', project.id)}
          >
            <div className="project-card__content">
              {/* Card content */}
            </div>
          </Card>
        ))}
      </div>
    </div>
  );
};

This implementation guide provides production-ready, test-driven components that can be copied directly into your codebase. Each component includes complete implementation, styles, tests, and Storybook stories.