CODITECT Pattern Library: Quick Reference Card

Print this page for fast pattern lookup

ATOMS (Building Blocks)

Pattern	Usage	Code Snippet	Test ID
Button	Actions, submit	`<button class="btn btn-primary">Create</button>`	`btn-primary`
Input	Text entry	`<input type="text" class="input" />`	`input-text`
Status Dot	Visual indicator	`<div class="status-dot status-success"></div>`	`dot-success`
Avatar	User identity	`<img src="..." class="avatar" alt="Name" />`	`avatar-image`
Badge	Count/label	`<span class="badge badge-count">3</span>`	`badge-count`
Progress Bar	Completion %	`<div class="progress-bar"><div class="progress-fill" style="width: 65%"></div></div>`	`progress-basic`
Skeleton	Loading state	`<div class="skeleton skeleton-text"></div>`	`skeleton-text`

MOLECULES (Simple Combos)

Pattern	Atoms Used	When to Use	Example
Status Indicator	Dot + Text	Show entity state	`<div class="status-indicator"><div class="status-dot status-success"></div><span>Active</span></div>`
Avatar Stack	Multiple Avatars	Team members	`<div class="avatar-stack"><img class="avatar avatar-stacked" />...</div>`
Search Input	Input + Icon + Button	Site/page search	`<div class="search-input">...</div>`
Form Field	Label + Input + Error	User input	`<div class="form-field"><label>...</label><input />...</div>`
Progress Indicator	Bar + Label	Task completion	`<div class="progress-indicator">...</div>`
Button Group	Multiple Buttons	Related actions	`<div class="button-group"><button>...</button>...</div>`

ORGANISMS (Complex Sections)

Pattern	Molecules Used	Purpose	Key Features
Card	Status, Progress, Avatar Stack	Entity container	Clickable, hover state, sections
Modal	Form Fields, Button Group	Focused interaction	Backdrop, focus trap, ESC closes
Data Table	Status Indicator, Button Group	Tabular data	Sortable, selectable, responsive
Navigation Bar	Search Input, Avatar	Primary nav	Sticky, active state, responsive
Empty State	Button	No content placeholder	Encouraging, actionable
Toast	Badge, Button	Feedback message	Auto-dismiss, stacking

TEMPLATES (Page Layouts)

Template	Organisms	Use Case	Structure
Dashboard Grid	Navbar + Card Grid	Overview	`navbar → page-header → card-grid`
Detail View	Navbar + Content + Sidebar	Single entity	`navbar → breadcrumb → main + sidebar`
Form	Navbar + Form Sections	Data entry	`navbar → form-header → sections → actions`
Kanban	Navbar + Column Grid	Workflow	`navbar → page-header → column-grid`

QUICK DECISION TREE

"Which pattern should I use?"

Need to trigger action?
├─ Yes → BUTTON atom
└─ No → Continue

Need to display status?
├─ Visual only → STATUS DOT atom
├─ With label → STATUS INDICATOR molecule
└─ No → Continue

Need to show progress?
├─ With label → PROGRESS INDICATOR molecule
├─ Without label → PROGRESS BAR atom
└─ No → Continue

Need to display entity?
├─ Multiple entities → CARD GRID in Dashboard template
├─ Single entity → DETAIL VIEW template
└─ No → Continue

Need user input?
├─ Single field → INPUT atom
├─ Multiple fields → FORM FIELD molecule
├─ Complete form → FORM template
└─ No → Continue

Need to show team?
├─ Individual → AVATAR atom
├─ Multiple → AVATAR STACK molecule
└─ No → Continue

Need feedback?
├─ Temporary → TOAST organism
├─ Modal → MODAL organism
├─ Inline → Form error in FORM FIELD
└─ No → Continue

Loading state?
├─ Fast (<1s) → Spinner (CSS)
├─ Slow (>1s) → SKELETON atom
└─ No → Continue

COLOR REFERENCE

/* Copy-paste into :root */
--white: #FFFFFF;
--gray-50: #F9FAFB;    /* Page background */
--gray-100: #F3F4F6;   /* Subtle backgrounds */
--gray-200: #E5E7EB;   /* Borders */
--gray-400: #9CA3AF;   /* Secondary text */
--gray-600: #6B7280;   /* Tertiary text */
--gray-700: #374151;   /* Labels */
--gray-900: #111827;   /* Primary text */

--blue-500: #3B82F6;   /* Primary actions */
--blue-600: #2563EB;   /* Hover states */

--green-500: #10B981;  /* Success */
--yellow-500: #F59E0B; /* Warning */
--red-500: #EF4444;    /* Error */

Semantic Usage:

Success/Active/Healthy → Green
Warning/In Progress → Yellow
Error/Blocked/Critical → Red
Inactive/Disabled → Gray

SPACING SCALE

/* 8px grid system */
--space-xs: 4px;   /* Tight: icon + label */
--space-sm: 8px;   /* Related items */
--space-md: 16px;  /* Component padding */
--space-lg: 24px;  /* Section spacing */
--space-xl: 32px;  /* Major sections */
--space-2xl: 48px; /* Page margins */

When to use:

XS (4px): Icon to adjacent text
SM (8px): List items, flex gap
MD (16px): Card padding, form field spacing
LG (24px): Between sections
XL (32px): Page sections
2XL (48px): Page margins

TYPOGRAPHY SCALE

--text-display: 32px / 600;  /* Page titles (rare) */
--text-headline: 24px / 600; /* Section headers */
--text-title: 18px / 600;    /* Card titles */
--text-body: 16px / 400;     /* Primary content */
--text-secondary: 14px / 400; /* Metadata */
--text-caption: 12px / 400;  /* Labels, hints */

Hierarchy:

H1: 24px (page title in content)
H2: 18px (section headers)
H3: 16px (subsections)
Body: 16px (paragraphs)
Meta: 14px (timestamps, counts)
Caption: 12px (labels, hints)

RESPONSIVE BREAKPOINTS

/* Mobile first */
@media (min-width: 768px)  { /* Tablet */ }
@media (min-width: 1024px) { /* Desktop */ }
@media (min-width: 1280px) { /* Wide */ }

Grid Columns:

Mobile (< 768px): 1 column
Tablet (768-1024px): 2 columns
Desktop (1024-1280px): 3 columns
Wide (> 1280px): 4 columns

ACCESSIBILITY CHECKLIST

Before shipping any pattern:

Keyboard: Tab, Enter, Escape work
Focus: Visible indicator (blue outline)
ARIA: Proper role, label, state
Contrast: 4.5:1 text, 3:1 UI
Touch: 44x44px minimum target
Alt: Images have descriptions
Labels: Inputs have labels
Hierarchy: H1 → H2 → H3 (no skips)

COMMON COMBINATIONS

User Profile Header

<div class="profile-header">
  <div class="avatar avatar-lg">👤</div>
  <div>
    <h2>User Name</h2>
    <div class="status-indicator">
      <div class="status-dot status-success"></div>
      <span>Online</span>
    </div>
  </div>
</div>

Search + Filters

<div class="search-controls">
  <div class="search-input">...</div>
  <select class="input">...</select>
  <button class="btn btn-secondary">Filter</button>
</div>

<div class="page-header">
  <div>
    <h1 class="page-title">Page Title</h1>
    <p class="page-subtitle">Description</p>
  </div>
  <div class="button-group">
    <button class="btn btn-secondary">Secondary</button>
    <button class="btn btn-primary">Primary</button>
  </div>
</div>

Card with All Features

<article class="card">
  <div class="card-header">
    <div class="card-icon">🏢</div>
    <div class="card-title-group">
      <h3 class="card-title">Title</h3>
      <div class="status-indicator">
        <div class="status-dot status-success"></div>
        <span>Active</span>
      </div>
    </div>
  </div>
  <div class="card-content">
    <p class="card-meta">Metadata</p>
    <div class="avatar-stack">
      <img class="avatar avatar-stacked" src="..." />
    </div>
  </div>
  <div class="card-footer">
    <div class="progress-indicator">
      <div class="progress-bar">
        <div class="progress-fill" style="width: 75%;"></div>
      </div>
      <span class="progress-label">75%</span>
    </div>
  </div>
</article>

TEST COMMANDS

# Run all tests
npm test

# Unit tests only
npm run test:unit

# Accessibility tests
npm run test:a11y

# Visual regression
npm run test:visual

# Update snapshots
npm run test:update-snapshots

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

PATTERN USAGE STATS

Pattern	Frequency	Priority
Button	Very High	P0
Input	Very High	P0
Card	High	P1
Status Indicator	High	P1
Progress Bar	Medium	P2
Modal	Medium	P2
Toast	Medium	P2
Data Table	Medium	P2
Empty State	Low	P3
Avatar Stack	Low	P3

ANTI-PATTERNS (What NOT to Do)

❌ Multiple Headers

<!-- BAD -->
<header>
  <nav></nav>
  <div class="breadcrumb"></div>
  <div class="page-title"></div>
</header>

✅ Single Header

<!-- GOOD -->
<header>Logo + Nav + Actions</header>
<main>
  <h1>Page Title</h1>
</main>

❌ Status as Text Only

<!-- BAD -->
<span>Status: Active and Running</span>

✅ Visual Indicator

<!-- GOOD -->
<div class="status-indicator">
  <div class="status-dot status-success"></div>
  <span>Active</span>
</div>

❌ Percentage as Text

<!-- BAD -->
<p>Progress: 65 percent complete</p>

✅ Progress Bar

<!-- GOOD -->
<div class="progress-indicator">
  <div class="progress-bar">
    <div class="progress-fill" style="width: 65%;"></div>
  </div>
  <span>65%</span>
</div>

❌ Table for Layout

<!-- BAD -->
<table>
  <tr>
    <td>Card 1</td>
    <td>Card 2</td>
  </tr>
</table>

✅ Grid Layout

<!-- GOOD -->
<div class="card-grid">
  <div class="card">...</div>
  <div class="card">...</div>
</div>

DEBUGGING CHECKLIST

Pattern not working? Check:

Data-testid present? Every pattern needs data-testid="pattern-name"
CSS classes correct? Check for typos
Nesting correct? Atoms → Molecules → Organisms
Variables defined? CSS custom properties in :root
Responsive? Test in mobile/tablet/desktop
Accessible? Run axe DevTools
Visual match? Compare to reference screenshots

GETTING HELP

Documentation:

Pattern Library Part 1: Atoms & Molecules
Pattern Library Part 2: Organisms & Templates
Testing Specification: Test criteria for each pattern
Implementation Guide: How to integrate

Resources:

Component Storybook: /storybook
Visual Examples: /examples
Test Results: /test-results

Support:

Slack: #coditect-design
Email: design@coditect.ai
Office Hours: Tue 2pm, Thu 10am EST

VERSION HISTORY

v1.0 (Current)

Initial pattern library
Atoms: 7 patterns
Molecules: 6 patterns
Organisms: 6 patterns
Templates: 4 layouts
100% test coverage
WCAG 2.1 AA compliant

QUICK START (30 SECONDS)

Copy design tokens (colors, spacing, typography) to :root
Copy pattern code from reference
Add data-testid attribute
Test accessibility with browser DevTools
Ship it ✓

Print this page | Keep at desk | Reference daily

ATOMS (Building Blocks)​

MOLECULES (Simple Combos)​

ORGANISMS (Complex Sections)​

TEMPLATES (Page Layouts)​

QUICK DECISION TREE​

"Which pattern should I use?"​

COLOR REFERENCE​

SPACING SCALE​

TYPOGRAPHY SCALE​

RESPONSIVE BREAKPOINTS​

ACCESSIBILITY CHECKLIST​

COMMON COMBINATIONS​

User Profile Header​

Search + Filters​

Page Header with Actions​

Card with All Features​

TEST COMMANDS​

PATTERN USAGE STATS​

ANTI-PATTERNS (What NOT to Do)​

DEBUGGING CHECKLIST​

GETTING HELP​

VERSION HISTORY​

QUICK START (30 SECONDS)​