# Progressive Disclosure

> **Definition**: A design pattern that sequences information and actions across multiple screens to reduce cognitive load and improve user experience.

**Navigation**: [← Back to Best Practices](../README.md) | [Next: Dynamic Manifests →](./dynamic-manifests.md)

---

## Table of Contents

- [What Is It?](#what-is-it) ← Start here
- [Why Use It?](#why-use-it)
- [Simple Examples](#simple-examples)
- [Implementation Patterns](#implementation-patterns) ← For practitioners
- [Architectural Principles](#architectural-principles) ← For architects
- [UI Patterns](#ui-patterns)
- [Related Concepts](#related-concepts)

---

## What Is It?

Progressive disclosure is revealing information **gradually** rather than all at once.

### The Core Idea

```
❌ Bad: Show everything immediately
User sees: [100 buttons] [50 options] [20 menus]
Result: Overwhelmed, confused

✅ Good: Show essentials, reveal more as needed
User sees: [5 core actions]
User clicks "More": [15 additional options appear]
User clicks "Advanced": [Advanced features panel opens]
Result: Focused, confident
```

### Real-World Analogy

**Restaurant Menu**
```
1. Main categories (Appetizers, Entrees, Desserts) ← Level 1
   └─ Click "Entrees"
      2. Entree types (Pasta, Seafood, Steak) ← Level 2
         └─ Click "Pasta"
            3. Specific dishes with details ← Level 3
```

This prevents menu overwhelm while still providing complete information.

---

## Why Use It?

### Benefits

| Benefit | Description | Impact |
|---------|-------------|--------|
| **Reduced Cognitive Load** | Users process less information at once | Less confusion, faster decisions |
| **Improved Discoverability** | Users find relevant features easier | Better feature adoption |
| **Faster Performance** | Load only what's needed now | Quicker startup, less memory |
| **Adaptive Complexity** | Beginners see simple, experts see advanced | Serves all skill levels |

### When to Use

✅ **Use progressive disclosure when:**
- Users don't need all features/info immediately
- Feature set is large or complex
- Users have varying skill levels
- Performance/load time matters

❌ **Don't use when:**
- All information is equally critical
- Users need to compare all options at once
- Feature set is small (< 7 items)
- Extra clicks harm the experience

---

## Simple Examples

### Example 1: Settings Panel

**Traditional Approach:**
```
Settings
├── Profile Name: _______
├── Email: _______
├── Password: _______
├── Theme: [ Dark | Light ]
├── Language: [ English ▼ ]
├── Timezone: [ UTC-5 ▼ ]
├── Date Format: [ MM/DD/YYYY ▼ ]
├── Currency: [ USD ▼ ]
├── API Keys: _______
├── Webhook URL: _______
├── Debug Mode: [ ]
├── Log Level: [ Info ▼ ]
└── ... (20 more settings)
```
Result: Users scrolls, scans, feels lost.

**Progressive Disclosure:**
```
Settings
├── Profile Name: _______
├── Email: _______
├── Theme: [ Dark | Light ]
│
├── [▼ Advanced Settings]
│   └── (collapsed by default)
│
└── [▼ Developer Settings]
    └── (collapsed by default)
```
Click "Advanced Settings":
```
Advanced Settings
├── Language: [ English ▼ ]
├── Timezone: [ UTC-5 ▼ ]
├── Date Format: [ MM/DD/YYYY ▼ ]
└── Currency: [ USD ▼ ]
```

### Example 2: MCP Skills

**Traditional: All Skills Loaded**
```python
# Load everything at startup
available_skills = [
    "basic-search",
    "file-operations",
    "web-scraping",
    "data-analysis",
    "machine-learning",
    "blockchain-analysis",
    "video-processing",
    # ... 50 more skills
]
```
Result: Slow startup, high memory, overwhelming list.

**Progressive Disclosure:**
```python
# Level 1: Always available
tier_1_skills = ["basic-search", "file-operations"]

# Level 2: Loaded when project type detected
if is_data_project():
    tier_2_skills = ["data-analysis", "visualization"]

# Level 3: Loaded on explicit request
if user_requests("machine-learning"):
    tier_3_skills = ["ml-training", "model-deployment"]
```

### Example 3: Command Line Tool

**Traditional:**
```bash
$ mytool --help

Usage: mytool [OPTIONS] COMMAND [ARGS]...

Options:
  --config PATH          Configuration file path
  --verbose              Verbose output
  --debug                Debug mode
  --log-file PATH        Log file path
  --log-level LEVEL      Logging level
  --timeout SECONDS      Operation timeout
  --retry-count N        Number of retries
  --parallel N           Parallel workers
  --cache-dir PATH       Cache directory
  --no-cache             Disable caching
  --format FORMAT        Output format
  ... (30 more options)

Commands:
  init      Initialize project
  build     Build project
  deploy    Deploy project
  test      Run tests
  ... (20 more commands)
```

**Progressive Disclosure:**
```bash
$ mytool --help

Usage: mytool [OPTIONS] COMMAND

Common Commands:
  init      Initialize project
  build     Build project
  deploy    Deploy project

Run 'mytool COMMAND --help' for command-specific options
Run 'mytool --help-all' for complete documentation

$ mytool build --help

Usage: mytool build [OPTIONS]

Essential Options:
  --output PATH    Output directory (default: ./dist)
  --watch          Watch for changes

Advanced Options (mytool build --help-advanced):
  --parallel N     Parallel workers
  --cache-dir PATH Cache directory
  ... (more advanced options)
```

---

## Implementation Patterns

### Pattern 1: Tiered Information Architecture

Organize content into logical tiers:

```
Tier 1: Essentials (80% of users need this)
├── Core functionality
├── Most common tasks
└── Critical information

Tier 2: Intermediate (30% of users need this)
├── Advanced features
├── Customization options
└── Detailed documentation

Tier 3: Expert (5% of users need this)
├── Edge cases
├── Debug/diagnostic tools
└── API reference
```

**Implementation:**
```markdown
# My API Documentation

## Quick Start (Tier 1)
Basic usage examples that work for most cases.

<details>
<summary>Advanced Usage (Tier 2)</summary>

## Authentication Options
Detailed authentication flows...

## Rate Limiting
How to handle rate limits...

</details>

[Expert Guide](./expert-guide.md) (Tier 3) →
```

### Pattern 2: Context-Aware Disclosure

Show features based on user context:

```python
class FeatureDisclosure:
    def get_available_features(self, user_context):
        features = ["core_feature_1", "core_feature_2"]  # Always available

        # Intermediate features
        if user_context.skill_level >= "intermediate":
            features.extend(["advanced_search", "bulk_operations"])

        # Expert features
        if user_context.has_permission("admin"):
            features.extend(["system_config", "user_management"])

        # Contextual features
        if user_context.project_type == "data_science":
            features.extend(["ml_tools", "visualization"])

        return features
```

### Pattern 3: Progressive Enhancement

Start minimal, add capabilities:

```javascript
// Level 1: Basic functionality works everywhere
function saveData(data) {
    localStorage.setItem('data', JSON.stringify(data));
}

// Level 2: Enhanced with sync (if available)
if (navigator.onLine && hasCloudSync()) {
    function saveData(data) {
        localStorage.setItem('data', JSON.stringify(data));
        cloudSync.upload(data);  // Progressive enhancement
    }
}

// Level 3: Real-time collaboration (if enabled)
if (hasFeature('realtime_collaboration')) {
    function saveData(data) {
        localStorage.setItem('data', JSON.stringify(data));
        cloudSync.upload(data);
        websocket.broadcast(data);  // Further enhancement
    }
}
```

### Pattern 4: Lazy Loading

Defer initialization until needed:

```python
class SkillManager:
    def __init__(self):
        self._skills = {}
        self._skill_registry = {
            'basic': ['search', 'files'],
            'advanced': ['ml', 'data_analysis'],
            'expert': ['custom_models']
        }

    def get_skill(self, skill_name):
        # Progressive disclosure: Load on first access
        if skill_name not in self._skills:
            self._skills[skill_name] = self._load_skill(skill_name)
        return self._skills[skill_name]

    def _load_skill(self, skill_name):
        # Deferred loading happens here
        module = import_module(f'skills.{skill_name}')
        return module.SkillClass()
```

---

## Architectural Principles

### Principle 1: Information Hierarchy

Design with clear levels:

```
Level 0: Critical (always visible, < 5 items)
  └─ Things users MUST see/do immediately

Level 1: Primary (visible by default, < 10 items)
  └─ Core functionality, 80% use case

Level 2: Secondary (behind 1 click, < 20 items)
  └─ Advanced features, configuration

Level 3: Tertiary (behind 2+ clicks, unlimited)
  └─ Expert features, detailed docs, edge cases
```

### Principle 2: Cognitive Load Management

**Miller's Law**: Humans can hold 7±2 items in working memory.

**Application:**
- Level 1 UI: Show ≤ 7 primary actions
- Menus: Group into ≤ 7 categories
- Forms: Break into ≤ 7 fields per step

**Bad Example:**
```
[Button1] [Button2] [Button3] [Button4] [Button5]
[Button6] [Button7] [Button8] [Button9] [Button10]
[Button11] [Button12] [Button13] [Button14] [Button15]
```

**Good Example:**
```
[Common Actions ▼]
  ├─ Action 1
  ├─ Action 2
  └─ Action 3

[Advanced ▼]
  ├─ Action 4
  └─ Action 5

[Expert ▼]
  └─ More...
```

### Principle 3: Discoverability vs. Visibility

Balance showing enough vs. hiding too much:

```
High Discoverability
↑
│   Ideal Zone:
│   Core features visible,
│   Advanced features discoverable
│
│       ┌─────────────┐
│       │  ✓ Sweet    │
│       │    Spot     │
│       └─────────────┘
│
└──────────────────────────→ High Visibility
  Hidden features           Feature overload
```

**Techniques:**
- Visual cues: "▼ More options" "⚙ Advanced"
- Tooltips: Hint at hidden features
- Progressive help: "New features available!"
- Analytics: Track if users find features

### Principle 4: Reversible Disclosure

Users should control disclosure:

```
✅ Good: User-controlled
[▼ Show Advanced Options] ← User clicks to expand
[▲ Hide Advanced Options] ← User clicks to collapse

❌ Bad: Forced progression
Step 1 → Step 2 → Step 3 (can't go back)
```

**Implementation:**
- Persistent state: Remember user's disclosure preferences
- Keyboard shortcuts: Power users want quick access
- Breadcrumbs: Show where user is in hierarchy

---

## UI Patterns

### Pattern: Accordion/Collapsible Sections

```html
<details>
  <summary>Basic Configuration</summary>
  <p>Essential settings here...</p>
</details>

<details>
  <summary>Advanced Configuration</summary>
  <p>Advanced settings here...</p>
</details>
```

### Pattern: Tabs

```
┌─────────┬──────────┬──────────┐
│ Basic   │ Advanced │ Expert   │
├─────────┴──────────┴──────────┤
│                                │
│  [Content for selected tab]   │
│                                │
└────────────────────────────────┘
```

### Pattern: Modal/Dialog

```
Main Screen (Simple)
[Click "Advanced Settings" button]
    ↓
┌─────────────────────────┐
│ Advanced Settings       │
│                         │
│ [Complex options here]  │
│                         │
│ [Cancel]  [Apply]       │
└─────────────────────────┘
```

### Pattern: Progressive Form

```
Step 1: Basic Info          Step 2: Details         Step 3: Preferences
┌─────────────────┐        ┌─────────────────┐     ┌─────────────────┐
│ Name: _______   │   →    │ Address: ____   │  →  │ Theme: [ ]      │
│ Email: ______   │        │ Phone: ______   │     │ Notifications:  │
│                 │        │                 │     │   [ ] Email     │
│ [Next]          │        │ [Back] [Next]   │     │   [ ] SMS       │
└─────────────────┘        └─────────────────┘     │ [Back] [Finish] │
                                                    └─────────────────┘
```

### Pattern: Contextual Help

```
Setting Name  [?]  ← Hover shows basic help
   ↓
Hover: "Controls the display theme"
Click [?]: Opens detailed documentation
```

---

## Related Concepts

### Progressive Disclosure → [Dynamic Manifests](./dynamic-manifests.md)

Progressive disclosure = **design philosophy**
Dynamic manifests = **technical implementation**

Example:
- Progressive disclosure says: "Show basic tools first"
- Dynamic manifests implement: Runtime query of available tools based on context

See: [Dynamic Manifests: Configuration](./dynamic-manifests.md#configuration)

### Progressive Disclosure → [Deferred Loading](./deferred-loading.md)

Progressive disclosure = **what to show**
Deferred loading = **when to load**

Example:
- Progressive disclosure: "Advanced feature hidden until clicked"
- Deferred loading: "Advanced feature code loaded on first access"

See: [Deferred Loading: Strategies](./deferred-loading.md#strategies)

### Progressive Disclosure in MCP

MCP Skills use progressive disclosure:
```
User starts → Basic skills available
  ↓
User works with Python files → Python skills appear
  ↓
User requests ML feature → ML skills loaded
```

Implemented via:
- Metadata scanning (what's available)
- Lazy loading (when to load)
- Context awareness (what to show)

See: [Best Practices: MCP Applications](../README.md#real-world-applications)

---

## Measurement & Testing

### Key Metrics

Track these to validate progressive disclosure:

| Metric | Good | Bad |
|--------|------|-----|
| Time to first action | < 5s | > 30s |
| Feature discovery rate | > 70% | < 30% |
| User confusion (support tickets) | Decreasing | Increasing |
| Task completion rate | > 85% | < 60% |

### A/B Testing

```
Group A: Everything visible (control)
Group B: Progressive disclosure (test)

Measure:
- Time to complete common task
- Number of clicks
- Error rate
- User satisfaction
```

---

## Anti-Patterns

### ❌ Hiding Critical Information

```
❌ Bad: Hide error messages in collapsed section
✅ Good: Show errors prominently, hide resolution steps
```

### ❌ Too Many Levels

```
❌ Bad: Menu → Submenu → Submenu → Submenu → Action
✅ Good: Menu → Submenu → Action (max 3 levels)
```

### ❌ Inconsistent Disclosure

```
❌ Bad: Some settings in tabs, others in accordions, others in modals
✅ Good: Consistent pattern throughout app
```

### ❌ No Visual Cues

```
❌ Bad: Hidden features with no hint they exist
✅ Good: "⚙ Advanced settings" or "▼ Show more"
```

---

## Further Reading

- [Jakob Nielsen: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)
- [Information Architecture Basics](https://www.usability.gov/what-and-why/information-architecture.html)
- [Cognitive Load Theory](https://en.wikipedia.org/wiki/Cognitive_load)

---

**Navigation**: [← Back to Best Practices](../README.md) | [Next: Dynamic Manifests →](./dynamic-manifests.md)

**Last Updated**: 2025-10-20