2nd/10_Wiki/Topics/Domain_Programming/Architecture/Progressive-Disclosure.md

---
id: wiki-2026-0508-progressive-disclosure
title: Progressive Disclosure
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Progressive Disclosure, 점진적 공개, layered UI]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [ux, ui-design, information-architecture, api-design]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: design
  framework: ux
---

# Progressive Disclosure

## 매 한 줄
> **"매 default는 매 simple, 매 advanced는 매 on-demand"**. Progressive Disclosure는 매 사용자에게 매 즉시 필요한 매 핵심 정보/control만 매 노출하고 매 advanced option은 매 명시적 trigger로 매 펼치는 매 UX/API 설계 원칙. Nielsen (1995) 정의 이후 매 모든 modern UI/CLI/API의 매 cornerstone.

## 매 핵심

### 매 두 layer
- **매 Primary**: 매 80% 사용 사례 매 cover.
- **매 Secondary**: 매 power user / edge case 매 expand 시 노출.
- **매 Tertiary** (옵션): 매 expert flag (`--debug`, `verbose=True`).

### 매 Cognitive 근거
- Hick's law: 매 choice ↑ → decision time ↑.
- Miller 7±2: 매 simultaneous option 매 7개 이하.
- Recognition > Recall: 매 expand 가능한 hint가 매 hidden API보다 낫다.

### 매 응용
1. Settings UI ("More options" toggle).
2. CLI subcommand depth (`git stash` vs `git stash push --keep-index`).
3. API: required + optional kwargs.
4. LLM: default vs advanced sampling params.

## 💻 패턴

### Python kwargs disclosure
```python
def generate(
    prompt: str,
    *,
    # 매 Primary layer
    max_tokens: int = 1024,
    # 매 Secondary layer (advanced)
    temperature: float = 1.0,
    top_p: float = 1.0,
    # 매 Tertiary (expert)
    logit_bias: dict[int, float] | None = None,
    seed: int | None = None,
) -> str: ...

generate("hi")                          # 매 simple path
generate("hi", temperature=0.2)         # 매 secondary
generate("hi", logit_bias={50256: -100}) # 매 expert
```

### CLI subcommand depth
```bash
$ git stash                       # 매 80%-case
$ git stash push -m "wip"         # 매 secondary
$ git stash push --keep-index --include-untracked --pathspec-from-file=- -- '*.py'
                                  # 매 expert
```

### React: collapsible advanced
```tsx
function Settings() {
  const [adv, setAdv] = useState(false);
  return (
    <form>
      <Field name="email" required />
      <Field name="password" required />
      <button type="button" onClick={() => setAdv(!adv)}>
        {adv ? "Hide" : "Show"} advanced
      </button>
      {adv && (
        <>
          <Field name="2fa_backup" />
          <Field name="webauthn_keys" />
        </>
      )}
    </form>
  );
}
```

### Documentation tier
```markdown
## Quickstart
client.chat("hello")

## Common options
client.chat("hello", model="claude-opus-4-7", max_tokens=2048)

## Advanced
<details><summary>Tool use, caching, streaming</summary>
... 매 deep dive ...
</details>
```

### Config schema with smart defaults
```python
@dataclass
class TrainerConfig:
    model: str
    data_path: str
    # 매 sensible defaults — 매 expert 만 매 override
    lr: float = 3e-4
    batch_size: int = 32
    grad_accum: int = 1
    optimizer: str = "adamw"
    scheduler: str = "cosine"
    mixed_precision: str = "bf16"
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Consumer app | 2-layer (primary / advanced toggle) |
| Developer tool | 3-layer (primary / flags / debug) |
| API library | required + kwarg defaults |
| Documentation | Quickstart → Guide → Reference |

**기본값**: 2-layer + 매 sensible defaults + 매 escape hatch.

## 🔗 Graph
- 응용: [[API-Design]]
- Adjacent: [[Affordance]]

## 🤖 LLM 활용
**언제**: API/CLI/UI surface 설계, 매 docs 구조화.
**언제 X**: 매 expert-only tool 매 모든 control 매 first-class.

## ❌ 안티패턴
- **매 모든 옵션 매 펼침**: 매 100개 settings 매 한 화면.
- **매 Hidden gem**: 매 핵심 기능 매 4-deep menu에 매 매장.
- **매 No escape hatch**: 매 advanced 매 아예 unreachable.
- **매 매 인자 required**: 매 default 없이 매 user에게 매 모든 결정 떠넘김.

## 🧪 검증 / 중복
- Verified (Nielsen NN/g 1995, Krug "Don't Make Me Think" 3rd ed.).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — 2/3-layer model + UI/CLI/API examples |