design-patterns:
  version: 1
  patterns:
    - id: task-entry
      state: stable
      surfaces: [public-web, product-app]
      components: [button, field]
      use-when: 사용자가 한 가지 핵심 작업을 시작한다.
      avoid-when: 비교·탐색이 핵심인 다중 선택 화면이다.
      anti-examples: [cta-before-value, competing-primary-actions]
    - id: resilient-status
      state: candidate
      surfaces: [product-app, developer-platform]
      components: [status-panel, button]
      use-when: 비동기 또는 부분 성공 작업의 상태를 설명하고 회복 경로를 제공한다.
      avoid-when: 즉시 완료되는 로컬 조작이다.
      anti-examples: [generic-error-toast-only, indefinite-spinner]
    - id: content-discovery
      state: candidate
      surfaces: [interactive-learning]
      components: [button]
      use-when: 사용자가 전체 학습 지도에서 현재·다음 메커니즘의 관계를 파악하고 진입한다.
      avoid-when: 단일 작업을 즉시 수행하는 운영 화면이다.
      anti-examples: [single-article-dead-end, topic-list-without-status, decorative-catalog]
    - id: causal-learning-loop
      state: candidate
      surfaces: [interactive-learning]
      components: [button, status-panel]
      use-when: Predict→Observe→Compare→Explain→Transfer의 동일 시나리오를 단계별 상태와 함께 진행한다.
      avoid-when: 읽기 전용 참고 문서이거나 단계 간 상태·증거 결속이 없다.
      anti-examples: [stepper-with-unrelated-content, answer-before-prediction, progress-without-evidence]
    - id: learning-feedback-recovery
      state: candidate
      surfaces: [interactive-learning]
      components: [status-panel, button]
      use-when: 오답·부분 완료·힌트·복귀 상태에서 다음 학습 행동과 근거를 제시한다.
      avoid-when: 단순 성공 알림처럼 복구 행동이 필요 없는 순간이다.
      anti-examples: [wrong-answer-only, spoiler-first-hint, lost-return-state]