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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

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

$ 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

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

## 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

@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