CODITECT Component Library Standard

Version: 1.0.0 Status: ACTIVE Last Updated: 2026-01-19 Related ADR: ADR-085-atomic-design-component-library.md

Overview

The CODITECT Component Library follows Atomic Design methodology to create a systematic, composable UI system. This standard defines the component hierarchy, naming conventions, and composition rules.

Atomic Design Hierarchy

┌─────────────────────────────────────────────────────────────────┐
│                         TEMPLATES (7)                           │
│         Page layouts that arrange organisms                     │
│         DashboardGrid, DetailView, KanbanBoard, AuthPage, etc. │
├─────────────────────────────────────────────────────────────────┤
│                         ORGANISMS (12)                          │
│         Complex UI sections with distinct purpose               │
│         Header, Card, Modal, DataTable, Drawer, TreeView, etc. │
├─────────────────────────────────────────────────────────────────┤
│                         MOLECULES (17)                          │
│         Groups of atoms working together                        │
│         FormField, Alert, Tabs, Dropdown, DatePicker, etc.     │
├─────────────────────────────────────────────────────────────────┤
│                          ATOMS (18)                             │
│         Basic building blocks (indivisible)                     │
│         Button, Input, Select, Textarea, Tooltip, etc.         │
└─────────────────────────────────────────────────────────────────┘

Total Components: 54 (Updated January 20, 2026)

Component Classification

Decision Tree

Is it a single, indivisible element?
├── YES → ATOM (Button, Input, Icon)
└── NO → Does it combine 2-3 atoms for one purpose?
    ├── YES → MOLECULE (FormField, StatusIndicator)
    └── NO → Is it a distinct UI section?
        ├── YES → ORGANISM (Card, Modal, Header)
        └── NO → TEMPLATE (DashboardGrid, FormPage)

Atoms (18 Components)

Atoms are the fundamental building blocks that cannot be broken down further.

Complete Atom Inventory

Atom	Purpose	Variants
Button	Primary interaction	primary, secondary, ghost, danger
Input	Text entry	text, email, password, number, search
Label	Form field label	default, required, optional
Badge	Count/status indicator	default, success, warning, error
Avatar	User profile image	sm, md, lg, xl
Icon	SVG icon	12+ icons in library
Dot	Status indicator	success, warning, error, info
ProgressBar	Progress visualization	default, success, warning
Checkbox	Multi-select	default, indeterminate, disabled
Radio	Single-select	default, disabled
Toggle	On/off switch	default, disabled
Spinner	Loading indicator	sm, md, lg
Divider	Content separator	horizontal, vertical
Select	Dropdown selection	sm, md, lg, disabled, error
Textarea	Multiline text entry	resize modes, character count
Skeleton	Loading placeholder	text, circular, rectangular, rounded
Link	Styled anchor	default, muted, underline, external
Tooltip	Hover information	top, bottom, left, right positions

Atom Specification Pattern

// atoms/Button/Button.tsx
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  children: React.ReactNode;
  onClick?: () => void;
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  disabled = false,
  loading = false,
  children,
  onClick,
}) => {
  return (
    <button
      className={cn(
        'coditect-button',
        `coditect-button--${variant}`,
        `coditect-button--${size}`,
        { 'coditect-button--loading': loading }
      )}
      disabled={disabled || loading}
      onClick={onClick}
    >
      {loading && <Spinner size="sm" />}
      {children}
    </button>
  );
};

Molecules (11 Components)

Molecules combine atoms to create simple, functional units.

Complete Molecule Inventory

Molecule	Composition	Purpose
FormField	Label + Input + Error	Form data entry
SearchInput	Input + Icon	Search functionality
StatusIndicator	Dot + Label	Status display
ProgressIndicator	ProgressBar + Label + Percentage	Progress with details
AvatarGroup	Avatar[] + Overflow	Team display
ButtonGroup	Button[]	Related actions
TagList	Badge[] + Add/Remove	Multiple tags
Breadcrumb	Link[] + Separator	Navigation trail
Pagination	Button[] + Input	Page navigation
EmptyState	Icon + Title + Description + Action	No data placeholder
Toast	Icon + Message + Action	Notification popup

Molecule Specification Pattern

// molecules/FormField/FormField.tsx
interface FormFieldProps {
  label: string;
  name: string;
  type?: string;
  required?: boolean;
  error?: string;
  hint?: string;
  value: string;
  onChange: (value: string) => void;
}

export const FormField: React.FC<FormFieldProps> = ({
  label,
  name,
  type = 'text',
  required = false,
  error,
  hint,
  value,
  onChange,
}) => {
  const inputId = `field-${name}`;
  const errorId = `${inputId}-error`;
  const hintId = `${inputId}-hint`;

  return (
    <div className={cn('coditect-form-field', { 'coditect-form-field--error': error })}>
      <Label htmlFor={inputId} required={required}>
        {label}
      </Label>
      <Input
        id={inputId}
        type={type}
        value={value}
        onChange={(e) => onChange(e.target.value)}
        aria-invalid={!!error}
        aria-describedby={error ? errorId : hint ? hintId : undefined}
      />
      {error && (
        <span id={errorId} className="coditect-form-field__error" role="alert">
          {error}
        </span>
      )}
      {hint && !error && (
        <span id={hintId} className="coditect-form-field__hint">
          {hint}
        </span>
      )}
    </div>
  );
};

Organisms (9 Components)

Organisms are complex UI sections that serve a distinct purpose.

Complete Organism Inventory

Organism	Composition	Purpose
Header	Logo + NavMenu + UserMenu	Navigation bar
Card	Header + Body + Footer	Content container
Modal	Overlay + Header + Body + Footer	Dialog overlay
DataTable	Header Row + Body Rows + Pagination	Data display
Form	FormField[] + ButtonGroup	Complex form layout
KanbanColumn	Header + Card[] + Add	Board column
Sidebar	Logo + NavItems + Footer	Side navigation
UserMenu	Avatar + Dropdown	User actions menu
FilterPanel	SearchInput + Filters + Actions	Search/filter controls

Organism Specification Pattern

// organisms/Card/Card.tsx
interface CardProps {
  title?: string;
  subtitle?: string;
  actions?: React.ReactNode;
  footer?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
}

export const Card: React.FC<CardProps> = ({
  title,
  subtitle,
  actions,
  footer,
  children,
  onClick,
}) => {
  const isClickable = !!onClick;

  return (
    <article
      className={cn('coditect-card', { 'coditect-card--clickable': isClickable })}
      onClick={onClick}
      tabIndex={isClickable ? 0 : undefined}
      role={isClickable ? 'button' : undefined}
      onKeyDown={isClickable ? (e) => e.key === 'Enter' && onClick() : undefined}
    >
      {(title || actions) && (
        <header className="coditect-card__header">
          <div className="coditect-card__header-text">
            {title && <h3 className="coditect-card__title">{title}</h3>}
            {subtitle && <p className="coditect-card__subtitle">{subtitle}</p>}
          </div>
          {actions && <div className="coditect-card__actions">{actions}</div>}
        </header>
      )}
      <div className="coditect-card__body">{children}</div>
      {footer && <footer className="coditect-card__footer">{footer}</footer>}
    </article>
  );
};

Templates (6 Components)

Templates define page layouts that arrange organisms.

Complete Template Inventory

Template	Composition	Use Case
DashboardGrid	Header + Sidebar + CardGrid	Main dashboard
DetailView	Header + Sidebar + Main + Related	Entity detail page
KanbanBoard	Header + KanbanColumn[]	Task management
ListDetail	Header + List + DetailPanel	Master-detail layout
FormPage	Header + Form + Sidebar	Data entry page
EmptyPage	Header + EmptyState	No data/onboarding

Template Specification Pattern

// templates/DashboardGrid/DashboardGrid.tsx
interface DashboardGridProps {
  header: React.ReactNode;
  sidebar?: React.ReactNode;
  children: React.ReactNode;
  columns?: { sm: number; md: number; lg: number };
}

export const DashboardGrid: React.FC<DashboardGridProps> = ({
  header,
  sidebar,
  children,
  columns = { sm: 1, md: 2, lg: 3 },
}) => {
  return (
    <div className="coditect-dashboard">
      {header}
      <div className="coditect-dashboard__body">
        {sidebar && (
          <aside className="coditect-dashboard__sidebar">{sidebar}</aside>
        )}
        <main
          className="coditect-dashboard__content"
          style={{
            '--columns-sm': columns.sm,
            '--columns-md': columns.md,
            '--columns-lg': columns.lg,
          } as React.CSSProperties}
        >
          {children}
        </main>
      </div>
    </div>
  );
};

Naming Conventions

File Structure

packages/ui/
├── atoms/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.styles.css
│   │   ├── Button.test.tsx
│   │   └── index.ts
│   └── ...
├── molecules/
│   └── ...
├── organisms/
│   └── ...
├── templates/
│   └── ...
└── index.ts

Naming Rules

Element	Convention	Example
Component file	PascalCase	`Button.tsx`
Component name	PascalCase	`export const Button`
CSS class	BEM kebab-case	`coditect-button--primary`
Props interface	PascalCase + Props	`ButtonProps`
Test file	Component.test.tsx	`Button.test.tsx`

CSS BEM Naming

/* Block */
.coditect-button { }

/* Element */
.coditect-button__icon { }
.coditect-button__text { }

/* Modifier */
.coditect-button--primary { }
.coditect-button--loading { }
.coditect-button--sm { }

Composition Rules

1. Atoms Can Only Use Design Tokens

// ✅ CORRECT: Atom uses tokens
const Button = styled.button`
  padding: var(--coditect-padding-button);
  background: var(--coditect-color-primary-500);
`;

// ❌ WRONG: Atom hardcodes values
const Button = styled.button`
  padding: 8px 16px;
  background: #0ea5e9;
`;

2. Molecules Compose Atoms Only

// ✅ CORRECT: Molecule uses atoms
export const FormField = ({ label, error, ...inputProps }) => (
  <div>
    <Label>{label}</Label>
    <Input {...inputProps} />
    {error && <Badge variant="error">{error}</Badge>}
  </div>
);

// ❌ WRONG: Molecule renders raw HTML
export const FormField = ({ label }) => (
  <div>
    <span className="label">{label}</span>  {/* Should be <Label> */}
  </div>
);

3. Organisms Can Compose Atoms, Molecules, or Other Organisms

// ✅ CORRECT: Organism composes multiple levels
export const Header = () => (
  <header>
    <Avatar src={user.avatar} />           {/* Atom */}
    <SearchInput onSearch={handleSearch} /> {/* Molecule */}
    <UserMenu user={user} />               {/* Organism */}
  </header>
);

4. Templates Arrange Organisms

Templates MUST NOT contain business logic - they only define layout:

// ✅ CORRECT: Template defines layout only
export const DashboardGrid = ({ header, sidebar, children }) => (
  <div className="layout">
    <div className="layout__header">{header}</div>
    <div className="layout__sidebar">{sidebar}</div>
    <div className="layout__main">{children}</div>
  </div>
);

// ❌ WRONG: Template has business logic
export const DashboardGrid = ({ userId }) => {
  const data = useQuery(userId);  // NO business logic
  return <div>{data.map(...)}</div>;
};

Required Props & Types

Common Prop Patterns

// Size variants
type Size = 'sm' | 'md' | 'lg' | 'xl';

// Status variants
type Status = 'default' | 'success' | 'warning' | 'error' | 'info';

// Base interactive props
interface InteractiveProps {
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
}

// Base form props
interface FormInputProps {
  name: string;
  value: string;
  onChange: (value: string) => void;
  error?: string;
  required?: boolean;
}

Export Pattern

// atoms/index.ts
export { Button, type ButtonProps } from './Button';
export { Input, type InputProps } from './Input';
// ... all atoms

// packages/ui/index.ts
export * from './atoms';
export * from './molecules';
export * from './organisms';
export * from './templates';

Testing Requirements

Test Coverage by Level

Level	Unit Tests	Integration Tests	Visual Tests
Atoms	All variants	N/A	Storybook snapshots
Molecules	Composition	Atom integration	Storybook snapshots
Organisms	Interactions	Multi-molecule	Storybook snapshots
Templates	Layout	Full organism	Storybook snapshots

Required Test Categories

Visual Tests - Appearance matches design
Functional Tests - Interactions work correctly
Accessibility Tests - WCAG compliance
Integration Tests - Components compose correctly

Quality Gates

Components MUST pass before merge:

Uses design tokens exclusively (no hardcoded values)
Follows BEM naming convention
Has complete TypeScript types
Has Storybook documentation
Passes accessibility audit
Has 80%+ test coverage
Follows composition rules for its level

Related Documents:

Version: 1.0.0 Last Updated: 2026-01-19 Maintained by: AZ1.AI Inc.

Overview​

Atomic Design Hierarchy​

Component Classification​

Decision Tree​

Atoms (18 Components)​

Complete Atom Inventory​

Atom Specification Pattern​

Molecules (11 Components)​

Complete Molecule Inventory​

Molecule Specification Pattern​

Organisms (9 Components)​

Complete Organism Inventory​

Organism Specification Pattern​

Templates (6 Components)​

Complete Template Inventory​

Template Specification Pattern​

Naming Conventions​

File Structure​

Naming Rules​

CSS BEM Naming​

Composition Rules​

1. Atoms Can Only Use Design Tokens​

2. Molecules Compose Atoms Only​

3. Organisms Can Compose Atoms, Molecules, or Other Organisms​

4. Templates Arrange Organisms​

Required Props & Types​

Common Prop Patterns​

Export Pattern​

Testing Requirements​

Test Coverage by Level​

Required Test Categories​

Quality Gates​