# Module 12: Functional Components

## Lesson 1: When Patterns Emerge

**Identifying reusable elements across your specifications**

---

## The Natural Progression

You've written specifications for multiple pages. And something happens:

You're specifying a button on page 3... and realize it's identical to the button on page 1.

Same states. Same behavior. Same styling. Different label.

**A pattern has emerged.**

---

## Why Extract Functional Components?

### Consistency

Same Functional Component = same behavior everywhere.

When the button on the signup form works like the button on the settings page, users don't have to relearn anything.

### Efficiency

Specify once, reference many times.

Instead of copying the full button specification to every page, you define it once and reference it.

### Maintainability

Change once, update everywhere.

Need to update the loading state? Change the component definition. Every instance inherits the update.

### Communication

Shared vocabulary with developers.

"Use the primary Button component" is clearer than "make a blue button that does this specific thing."

---

## When to Extract

Not everything should be a component. Look for:

**Appears more than once**

Once is an instance. Twice or more is a pattern worth considering.

**Consistent behavior**

The element behaves the same way everywhere. If behavior differs, they're different elements.

**Worth centralizing**

The extraction provides value. Sometimes inline is simpler.

**Meaningful abstraction**

"Button" is meaningful. "Blue rectangle with text" is not.

---

## What IS a Functional Component?

A **Functional Component** is a reusable widget with defined functionality:

- **Variants** — Different configurations (detailed, compact, minimal)
- **States** — Behavioral states (loading, loaded, error, refreshing)
- **Props** — Configurable options (location, maxResults, onSelect)
- **Behavior** — What the widget does (fetches data, handles input, manages state)

**Key distinction:** Functional Components are specification-level widgets, not implementation-level UI components (React, Vue, etc.).

### Examples

| Functional Component | What It Does |
|---------------------|--------------|
| Weather Widget | Fetches weather, displays forecast, handles location, refresh |
| Search Widget | Accepts input, fetches suggestions, handles selection, keyboard nav |
| Login Form | Validates fields, manages auth flow, handles errors |
| Comment Section | Manages comment input, character count, submission, validation |
| Task Card | Displays task, handles status changes, actions, completion |

---

## What Is NOT a Functional Component

Not everything needs extraction:

| Functional Component | NOT a Functional Component |
|---------------------|---------------------------|
| Weather Widget | A single temperature display |
| Search Widget | A single input field |
| Login Form | A single button |
| Task Card | A checkbox element |
| Comment Section | A color value or margin |

**Functional Components have functionality and behavior.** Simple elements and styles don't.

If the thing doesn't have complex behavior, states, and reusable functionality, it's probably just an element or style token, not a Functional Component.

---

## Functional Component vs. Instance

**Functional Component:** The widget definition

```markdown
## Weather Widget (Functional Component)
Variants: compact, detailed, minimal
States: loading, loaded, error, refreshing
Props: location, variant, autoRefresh, units
```

**Instance:** A specific usage

```markdown
### Homepage Hero Weather
- Functional Component: Weather Widget
- Variant: detailed
- Location: User's city
- AutoRefresh: true
- OnLoad: Fetch forecast data
```

The Functional Component defines the possibilities. The instance applies them.

---

## The Extraction Process

When you notice a pattern:

### 1. Identify the Pattern

"This button appears in signup, settings, and checkout..."

### 2. Document the Variations

- Primary (blue, white text)
- Secondary (white, blue border)
- Ghost (transparent, text only)

### 3. List All States

- Default
- Hover
- Active
- Loading
- Disabled

### 4. Define the Props

| Prop | Type | Default | Options |
|------|------|---------|---------|
| variant | string | primary | primary, secondary, ghost |
| size | string | md | sm, md, lg |
| disabled | boolean | false | |

### 5. Create the Component Document

Goes in `C-UX-Scenarios/Functional-Components/weather-widget.md`

### 6. Update Page Specs

Replace inline definitions with component references.

### Visual Extraction Flow

```
STEP 1: IDENTIFY PATTERN
┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  Signup Page     │   │  Settings Page   │   │  Checkout Page   │
├──────────────────┤   ├──────────────────┤   ├──────────────────┤
│ Button (primary) │   │ Button (primary) │   │ Button (primary) │
│ States: default, │   │ States: default, │   │ States: default, │
│  hover, loading  │   │  hover, loading  │   │  hover, loading  │
└──────────────────┘   └──────────────────┘   └──────────────────┘
        ↓                      ↓                      ↓
        └──────────────────────┴──────────────────────┘
                              ↓
                   PATTERN RECOGNIZED
                              ↓

STEP 2-4: DOCUMENT COMPONENT
┌────────────────────────────────────────────────────────────┐
│ C-UX-Scenarios/Functional-Components/weather-widget.md                       │
├────────────────────────────────────────────────────────────┤
│ Variants: primary, secondary, ghost                        │
│ States: default, hover, active, loading, disabled          │
│ Props: variant, size, disabled, loading                    │
└────────────────────────────────────────────────────────────┘
                              ↓

STEP 5-6: UPDATE PAGE SPECS
┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  Signup Page     │   │  Settings Page   │   │  Checkout Page   │
├──────────────────┤   ├──────────────────┤   ├──────────────────┤
│ Component:       │   │ Component:       │   │ Component:       │
│   Button         │   │   Button         │   │   Button         │
│   (primary, lg)  │   │   (primary, md)  │   │   (primary, lg)  │
│ Label: "Sign Up" │   │ Label: "Save"    │   │ Label: "Pay Now" │
└──────────────────┘   └──────────────────┘   └──────────────────┘
        ↑                      ↑                      ↑
        └──────────────────────┴──────────────────────┘
                              ↑
                 ALL REFERENCE SAME DEFINITION
```

---

## Design System

How you handle components depends on your mode:

| Mode | Component Handling |
|------|-------------------|
| **None** | Keep inline in page specs |
| **Building** | Extract to C-UX-Scenarios/Functional-Components/ |
| **Library** | Reference external (shadcn, etc.) |
| **Existing** | Import from previous project |

If you're in Mode 1 (None), you can still document patterns — just keep them inline rather than extracting to separate files.

---

## What's Next

In the next lesson, you'll learn the component anatomy in detail — how to document variants, states, props, and usage rules.

---

**[Continue to Lesson 2: Component Anatomy →](lesson-02-component-anatomy.md)**

---

[← Back to Module Overview](module-12-functional-components-overview.md)

*Part of Module 12: Functional Components*