@neurocle/synapse-react 0.0.0-bootstrap

package/skills/synapse/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: synapse
+description: '@neurocle/synapse-react에 의존하는 프로젝트에서 UI를 작성할 때 사용합니다. 상태, 키보드 동작, 포커스 관리, ARIA 역할, floating 배치, 로케일에 따른 서식이 필요한 마크업을 만들기 전에 읽습니다. 어떤 패턴을 다루는 컴포넌트를 찾는 법, 그 패턴을 다루는 컴포넌트가 없음을 확인하는 법, part가 조합되는 방식, 공통 prop 어휘, 토큰과 접근성 규약, 그리고 한 컴포넌트에 고유한 모든 것을 설치된 Registry에서 읽는 법을 알려 줍니다.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: 0.3.0
+  layer: authored-cross-cutting
+---
+
+# Synapse
+
+이 프로젝트는 `@neurocle/synapse-react`를 설치합니다. 이 패키지는 정해진 범위의 인터랙티브 패턴을
+다루며, 그 하나하나를 기계가 읽을 수 있는 기록으로 함께 배포합니다.
+
+아래 내용은 그 모든 패턴에 공통인 부분입니다. 개별 컴포넌트에 대해서는 prop, part, 기본값, 키 그
+무엇도 일부러 적지 않습니다. 그런 사실은 설치된 Registry에 있고, Registry는 옆에 있는 코드와 어긋나는
+일이 없지만 이 문서는 어긋날 수 있습니다. 이 문서는 한 번 읽고, Registry는 작업마다 읽습니다.
+
+## 언제 꺼내 쓰는가
+
+작성하려는 마크업에 한 가지를 물어봅니다. 내부 상태, `Tab`을 넘어서는 키보드 동작, 포커스 관리, ARIA
+역할이나 관계, floating 배치, 로케일이나 텍스트 방향에 따라 달라지는 서식 가운데 하나라도 필요한가?
+
+하나라도 그렇다면 디자인 시스템이 이미 다루고 있을 가능성이 높습니다. 만들기 전에 먼저 찾아봅니다. 직접
+구현하게 되는 것은 눈에 보이는 모양이 아니라 접근성 계약이며, 직접 만든 계약은 가장 알아채기 어려운
+방식으로 실패합니다. 마우스로는 동작하지만 키보드와 스크린 리더에서는 망가져 있고, 이는 내 테스트에서도
+리뷰에서도 드러나지 않습니다.
+
+모두 아니라면, 즉 문단, 레이아웃 요소, 제목, 페이지를 이동하는 링크, 맞춤 제작한 시각적 섹션이라면
+원시 마크업이 정답입니다. 정적 콘텐츠를 컴포넌트로 감싸면 간접 계층만 늘고 얻는 것은 없습니다.
+
+## 컴포넌트를 찾거나, 없다는 것을 확인하기
+
+구체적인 모든 것은 `node_modules/@neurocle/synapse-react/dist/registry/index.json`에 설치된 Registry
+인덱스에서 시작합니다. 이 파일을 읽습니다. 이 디자인 시스템의 API를 웹에서 검색하지 않습니다.
+
+1. **part보다 패턴 전체를 먼저 찾습니다.** `capabilityIndex.terms`를 용어로, 그리고 `definition`에 쓰인
+   단어로 검색하고, 사람들이 실제로 부르는 비공식 이름을 담은 `components[].capabilities.commonNames`를
+   훑습니다. 이미 쪼개 놓은 메커니즘이 아니라 목표를 가리키는 사용자의 단어로 검색합니다. 두세 개의
+   컴포넌트가 만들려는 것의 메커니즘을 하나씩 다루는 것처럼 보인다면, 전체를 다루는 컴포넌트를 지나칠
+   만큼 잘게 쪼갰다는 신호로 받아들입니다. 인덱스는 조각 하나하나를 기꺼이 따로 확인해 주므로, part를
+   조합하기 전에 전체를 다시 검색합니다.
+2. **결과는 두 가지가 아니라 반드시 세 가지 중 하나로 읽습니다.** `claimedBy`가 비어 있지 않은 용어는 그
+   패턴을 다루는 컴포넌트를 가리킵니다. 그 컴포넌트들의 항목을 읽고 그중에서 고릅니다. **빈** `claimedBy`와
+   함께 올라 있는 용어는 확정된 부재입니다. 디자인 시스템이 이것을 하지 않는다는 뜻입니다. **인덱스에 아예
+   없는** 용어는 어휘의 빈틈일 뿐이며, 디자인 시스템이 무엇을 다루는지에 대해서는 아무것도 말해 주지
+   않습니다.
+3. 세 번째 경우를 두 번째 경우처럼 보고하는 것이야말로 인덱스가 막으려고 존재하는 단 하나의 실패입니다.
+   그렇게 하면 "이 디자인 시스템에는 X가 없습니다"는 자신만만하지만 그냥 틀린 말이 나옵니다. 찾는 용어가
+   없다면 결론을 내리기 전에 `seeAlso`에 있는 인접 용어, `commonNames`, 그리고 65개의 `components` 행을
+   살펴봅니다.
+4. **진짜 부재라면 검색은 거기서 끝납니다.** 더 찾지 말고, 컴포넌트 이름을 지어내지 말고, 패턴을 직접
+   만들거나 프로젝트에 이미 있는 것으로 만듭니다. **이를 보고하는 것은 별개의 의무이며, 그 의무는 지금이
+   아니라 작업이 끝날 때 이행합니다.** [끝내기 전에](#끝내기-전에)를 봅니다. 그것을 만들었다고 해서 이
+   의무가 사라지지 않습니다.
+
+그 행을 쓰기로 정하기 전에 `lifecycle`을 확인합니다. `active`가 아니라면 항목이 `successor`를 가리킵니다.
+그쪽을 쓰고, 무엇이 다른지는 `migrationNote`에서 읽습니다. 은퇴한 컴포넌트도 여전히 존재하고 여전히
+컴파일되므로, 다른 어떤 것도 이 사실을 알려 주지 않습니다.
+
+행을 찾았으면 그 행의 `path` 필드를 `dist/registry/` 기준으로 해석해 해당 컴포넌트의 항목으로 갑니다.
+`path`는 주어진 그대로 씁니다. 규칙으로 조립한 경로는 그 규칙이 바뀌는 날 깨집니다.
+
+그 항목은 이 문서가 답하지 않는 모든 것에 답합니다. part, prop과 그 타입, variant 축, 키보드 동작, 역할,
+폼 참여, 로케일 의존성, 의도적으로 **하지 않는** 일, 그리고 언제 알맞은 선택이고 언제 아닌지에 대한
+안내까지. 쓰기로 정하기 전에 `guidance.whenNotToUse`와 `relatedComponents`를 읽습니다. 두 컴포넌트가
+겹칠 때는 먼저 손이 가는 쪽이 틀린 쪽인 경우가 많습니다.
+
+## 그 컴포넌트의 스킬 불러오기
+
+컴포넌트마다 같은 항목에서 생성된 전용 스킬이
+`node_modules/@neurocle/synapse-react/skills/components/<id>/SKILL.md`에 있습니다. `<id>`는 방금 읽은 행의
+`id` 필드입니다. 필요한 스킬 하나만 불러오고 나머지는 불러오지 않습니다. 스킬은 한 번에 하나씩 읽도록
+쓰였고, 전부 합치면 어떤 단일 컨텍스트보다도 훨씬 큽니다.
+
+그 경로가 없다면 `skills/components/`를 나열해 id로 맞춰 봅니다. 그래도 없다면 항목만으로 충분합니다.
+스킬은 항목을 재배열한 것이지 추가 지식이 아니며, 이 문서의 어떤 내용도 스킬을 불러왔는지에 의존하지
+않습니다.
+
+## 임포트
+
+모든 컴포넌트는 한 패키지, `@neurocle/synapse-react`가 제공합니다. 짝을 이루는 패키지도, 별도의 토큰이나
+스타일 패키지도, 함께 설치해야 할 peer 컴포넌트 라이브러리도 없습니다. 빈틈을 메우려고 두 번째 UI 의존성을
+추가하고 있다면, 그것은 덮어 둘 일이 아니라 보고할 빈틈입니다.
+
+컴포넌트마다 같은 id를 쓰는 전용 진입점 `@neurocle/synapse-react/<id>`도 있으며, 하나를 임포트해도
+관련 없는 컴포넌트는 딸려 오지 않습니다. 항목의 `publicExport` 필드가 패키지와 정확한 export 이름을
+알려 줍니다. 대소문자를 추측하지 말고 이 값을 씁니다.
+
+절대 쓰지 말아야 할 임포트가 두 가지 있습니다. `dist/` 경로로 파고들지 않습니다. 빌드 결과물이며 지원되는
+인터페이스가 아니다. 의존성 트리에 있더라도 `@zag-js/*`를 직접 임포트하지 않습니다. 그것은 밑에 깔린
+동작 계층이며, 직접 쓰면 컴포넌트를 올바르게 만드는 prop 병합, 구조 검사, 스타일링이 빠진, 배선되지
+않은 machine만 손에 쥐게 됩니다.
+
+애플리케이션을 `SynapseProvider`로 한 번 감쌉니다. 테마, 로케일, 텍스트 방향, 번역된 접근성 문자열을
+하나의 범위로 전달합니다. 이 넷은 언제나 같은 하위 트리에 적용되기 때문입니다. 컴포넌트는 provider
+없이도 기본 테마로 렌더링되므로, provider가 빠져도 티가 나지 않습니다. 나중에 잘못된 로케일로 서식이
+지정된 날짜나 오른쪽에서 왼쪽 방향을 무시하는 레이아웃으로 드러납니다.
+
+## part가 조합되는 방식
+
+컴포넌트는 하나의 export이며, part는 그 export의 속성입니다. 모델은 모든 컴포넌트에서 같습니다.
+
+```tsx
+import { Collapsible } from '@neurocle/synapse-react/collapsible'
+
+export function Details() {
+  return (
+    <Collapsible.Root defaultOpen>
+      <Collapsible.Trigger>Details</Collapsible.Trigger>
+      <Collapsible.Content>…</Collapsible.Content>
+    </Collapsible.Root>
+  )
+}
+```
+
+이 문서가 이름을 댈 수 있는 컴포넌트는 이것 하나뿐이고, 여기서는 모양을 보여 주는 용도로만 씁니다. 이
+예에서 네 가지를 읽어 내어 어디에나 적용합니다.
+
+**`Root`가 상태를 소유하며, 모든 part는 그 안에 있어야 합니다.** 루트 밖에서 렌더링된 part는 개발
+환경에서뿐 아니라 프로덕션에서도 예외를 던집니다. 붙을 동작이 없기 때문이며, 그렇지 않으면 겉보기엔
+멀쩡하지만 아무 일도 하지 않는 요소를 렌더링하게 됩니다.
+
+**중첩은 장식이 아니라 구조입니다.** part가 어디에 놓이느냐가 그 part가 하는 일을 바꿉니다. 구조는 part
+이름이 알려 줍니다. 다른 part의 이름으로 시작하는 part는 그 part 안에 들어가고, 무언가를 배치하는 part는
+자신이 배치하는 대상을 감쌉니다.
+
+**위 예는 이 컴포넌트가 가진 part 하나를 생략했습니다.** 어떤 예도 완전한 구조로 여기지 않습니다. 완전한
+목록은 항목의 part 목록입니다. 빠뜨린 part는 잃어버린 기능이며, 대개 조용히 사라집니다. 레이블 part를
+빼면 화면에서는 아무 문제 없어 보이지만 접근 가능한 이름이 없는 컨트롤이 남습니다.
+
+**part가 렌더링하는 요소를 바꾸는 방법은 `asChild`뿐입니다.** `as`나 `component` prop은 없습니다. 두 번째
+메커니즘은 접근성이 빠질 수 있는 두 번째 자리가 되기 때문입니다. `asChild`는 정확히 하나의 자식 요소에
+병합됩니다. 자식이 없거나 여럿이면 구조 오류입니다. 그리고 part를 동작하게 만드는 속성에서는 자식이 이길 수
+없습니다.
+
+## Props와 variant
+
+**하나의 개념에는 모든 컴포넌트에 걸쳐 하나의 이름만 씁니다.** 값에는 `value` / `defaultValue` /
+`onValueChange`, 열림 상태에는 `open` / `defaultOpen` / `onOpenChange`, 그리고 `disabled`, `readOnly`,
+`invalid`, `required`, `orientation`, `direction`, `size`. `onChange`, `checked`, `defaultChecked`,
+`initialValue`, `onSelect`, `onSelectionChange`를 쓰려 한다면 다른 라이브러리의 철자를 쓰고 있는 것이고,
+타입 검사를 통과하지 못합니다. 옮겨 적습니다.
+
+**컨트롤의 `value`는 폼이 받는 값이 아니라 컨트롤의 상태입니다.** `name` 아래 제출되는 문자열은
+`formValue`다. 켜고 끄는 컨트롤에서는 둘이 서로 다른 것이기 때문에 분리되어 있으며, 제출할 문자열을
+뜻하면서 `value`를 설정하면 상태가 바뀌어 버립니다.
+
+**제어 여부는 값이 아니라 키가 있느냐로 결정됩니다.** `value={undefined}`는 비제어이고, `value={null}`은
+아무것도 선택되지 않은 제어 상태입니다. `value`와 `defaultValue`를 둘 다 넘기면 제어 쪽이 이기고 기본값은
+무시되며, 크래시 대신 개발 경고가 나옵니다. 마운트 이후 둘 사이를 오가도 경고가 나옵니다. 마운트 시점에
+정하고 유지합니다.
+
+**크기는 하나의 척도, `xs`, `sm`, `md`, `lg`, `xl`이며 기본값은 `md`다.** 어디서나 같은 뜻입니다.
+컴포넌트는 그중 연속된 일부만 제공할 수 있습니다. 코드에서 필요하면 `SIZE_SCALE`과 `DEFAULT_SIZE`가
+export되어 있습니다.
+
+**강조 축은 기본적으로 없으며, 없는 것은 실수가 아니다.** 강조는 컴포넌트가 이미 쓰는 시맨틱 토큰과
+페이지에서 놓인 위치에서 나옵니다. 컨트롤을 다시 칠하는 `className`으로 이를 되살리지 않습니다. 예외로
+강조 축을 받는 컴포넌트는 항목의 `variants`에 그 축이 나열되어 있으며, 항목에 없는 축은 추측하지 않습니다.
+
+그 밖의 어떤 prop도 추측하지 않습니다. 항목에는 모든 prop이 타입과 설명과 함께 나열되어 있습니다. prop에는
+`default` 필드가 없습니다. 타입 선언에는 기본값을 둘 자리가 없기 때문입니다. 그래서 기본값이 중요한 경우에는
+그 prop의 설명에 적혀 있습니다.
+
+## 토큰과 테마
+
+디자인 값은 두 계층에 있습니다. **Primitive**는 원시 척도입니다. 번호가 붙은 뉴트럴, 번호가 붙은 간격 단계
+같은 것입니다. **시맨틱 토큰**은 역할에 이름을 붙입니다. 모든 것 뒤의 캔버스, 올라온 표면, 포커스 테두리,
+컨트롤 높이 같은 것입니다. 컴포넌트는 시맨틱 토큰만 쓰며, 그 주변에 작성하는 마크업도 그래야 합니다.
+
+리터럴 값은 테마가 바뀌어도 움직이지 않는 것입니다. 컴포넌트 옆에 hex 색이나 픽셀 높이를 하드코딩하면
+테마가 바뀌어도 그대로 남고, 그렇게 어두운 표면 위의 어두운 글자가 생깁니다. 빌드 오류도 런타임 오류도
+없는 실패입니다. primitive 참조는 한 단계 늦게 나타나는 같은 버그입니다. primitive 역시 테마에 따라 달라지지
+않으며, 바로 그 점이 primitive를 primitive로 만듭니다.
+
+**테마는 prop이 아니라 범위입니다.** 테마를 받는 컴포넌트는 없습니다. 테마는 provider의 속성 하나이고 나머지는
+CSS 커스텀 프로퍼티가 처리하므로, 테마를 바꿔도 어떤 컴포넌트의 인터페이스도 바뀌지 않습니다. 한
+영역에만 다른 테마를 쓰려면 그 영역을 두 번째 provider로 감쌉니다.
+
+시맨틱 계층에 필요한 것의 이름이 없다면, 그것은 보고하고 확장할 어휘의 빈틈이지 그 계층을 건너뛰어
+primitive를 가져다 써도 된다는 허가가 결코 아니다.
+
+## 접근성
+
+역할, ARIA 관계, 포커스 관리, 키보드 상호작용, 안내되는 위치는 컴포넌트가 제공합니다. 할 일은 이것을
+추가하는 것이 아니다. 이것을 무력화하지 않는 것입니다.
+
+**part에 `role`, `aria-*`, `id`, `tabIndex`를 넣지 않습니다.** 이것들은 컴포넌트가 소유하며, 병합 규칙이
+넣은 값을 버립니다. 오류도 효과도 없습니다. 무언가를 개선했다고 믿으면서, 수고만 들이고 아무것도 바꾸지 못한
+셈입니다.
+
+**part에 `disabled`, `readOnly`, `required`, `checked`, `hidden`도 설정하지 않습니다.** 이것들은
+컴포넌트 자신의 상태에서 나옵니다. 요소에서 하나를 덮어쓰면 machine과 모순되는 DOM이 만들어집니다. 활성화된
+것처럼 읽히면서 입력을 거부하는 컨트롤이 됩니다. 대신 `Root`에 prop을 넘기면 둘이 일치한 채로 유지됩니다.
+
+**이벤트 핸들러는 컴포넌트의 핸들러 다음에 실행됩니다.** 동작을 관찰할 수는 있지만 앞질러 막을 수는 없고,
+`preventDefault`로 이미 일어난 일을 되돌릴 수도 없습니다. 개입해야 할 때는 컴포넌트 자체의 콜백이나 상태
+prop을 씁니다.
+
+**컴포넌트 주변에 포커스 관리를 추가하지 않습니다.** 떠 있는 요소 주변에 포커스 트랩을 더 두지 않고,
+part에 도달하게 하려고 `tabIndex`를 넣지 않고, 순서 문제처럼 보이는 것을 고치려고 `.focus()`를 직접
+호출하지 않습니다. 이 모두가 이미 그 일을 하고 있는 machine과 경쟁하며, 하나의 포커스를 두 관리자가 다루는
+것은 어느 하나만 있는 것보다 나쁩니다.
+
+**Synapse가 의도적으로 충족하지 않는 기준이 있습니다.** 고치려 들지 말고, 유의점을 지켜서 씁니다. 모든
+컴포넌트에 걸친 것은 세 가집니다. 컨트롤의 평소 테두리(`border.default`)와 떠 있는 레이어의
+테두리(`border.overlay`)는 WCAG 1.4.11의 3:1에 못 미치므로, 테두리만으로 입력 영역을 알리지 말고 항상
+보이는 라벨을 둡니다. 투명한 배경 위 글자는 대비를 스스로 갖지 않으므로, 투명한 컨트롤을 이미지나 색
+위에 놓을 때는 대비를 직접 확인합니다. 한 컴포넌트에만 해당하는 예외는 항목의 `knownExceptions`에 있으며,
+그 컴포넌트의 스킬에서 "알려진 예외 — 사용 전에 확인" 섹션으로 나옵니다. 컴포넌트를 쓰기 전에 이 섹션부터
+읽습니다.
+
+접근성이 정말로 입력을 필요로 하는 곳에서는 그 입력이 평범한 prop으로 들어오며, 각 컴포넌트의 이름과
+설명이 어디서 오는지는 항목의 `accessibility` 섹션에 나와 있습니다.
+
+## 컴포넌트 조합하기
+
+어떤 컴포넌트도 다른 컴포넌트를 렌더링하지 않으며, 서로에 대해 알지도 못합니다. 조합은 직접 작성한
+마크업을 중첩해서 하고, 각 컴포넌트는 자신의 `Root`와 자신의 상태를 유지합니다.
+
+제품에 정말로 그 자리에 하나의 값만 있는 것이 아니라면, 두 컴포넌트를 맞춰 두려고 한 컴포넌트의 변경
+콜백을 다른 컴포넌트의 값에 연결하지 않습니다. 둘이 같은 틱에 바뀔 때만 드러나는 동기화 버그를 만들게
+됩니다.
+
+떠 있는 컴포넌트는 다른 컴포넌트 안에서 열릴 때를 포함해, 배치와 레이어링을 스스로 소유하게 둡니다.
+`z-index`, 바깥 클릭, 닫힘 순서를 직접 관리하면 이미 돌아가고 있는 로직과 경쟁하게 되고, 중첩 상황에서
+순서가 틀어집니다.
+
+provider는 애플리케이션 최상단에 하나 둡니다. 하위 트리의 테마, 로케일, 방향을 바꿀 때만 또 하나를
+중첩합니다.
+
+폼의 경우, 참여하는 컨트롤은 `name`과 폼 값으로 참여하며, 참여 여부와 어떤 요소를 제출하는지는 항목의
+`formParticipation` 필드에 나와 있습니다. 컨트롤 옆에 직접 만든 숨은 input을 추가하지 않습니다. 필드가 두 번
+제출됩니다.
+
+## 모든 컴포넌트에 적용되는 Anti-patterns
+
+**이미 시작했으니 직접 만듭니다.** 작성 도중에 컴포넌트가 그것을 다룬다는 것을 알아차리는 것은 실패가
+아니라 흔한 일입니다. 지우고 찾아봅니다.
+
+**컴포넌트가 하지 않는다고 선언한 것을 다시 구현합니다.** 항목에는 컴포넌트가 의도적으로 갖지 않는
+상태와 그 이유를 나열한 `declaredAbsences` 필드가 있습니다. 이것은 빈틈이 아니라 답입니다. 대개 그 상태가
+컴포넌트를 둘러싼 화면에 속한다는 뜻이며, 그래도 컴포넌트 안에 만들면 사용자가 볼 수 없는 곳에
+메시지를 두게 됩니다.
+
+**안으로 파고들어 스타일링합니다.** 내부 클래스 이름이나 data 속성을 직접 작성한 셀렉터로 겨냥하면
+공개 인터페이스가 아닌 출력에 묶이게 되고, 패치 릴리스에서 깨지는 변경이 바로 이것입니다.
+
+**커스터마이즈하려고 컴포넌트가 렌더링한 마크업을 자신의 요소로 복사합니다.** 겉모습은 남고 동작은 모두
+잃습니다. 두 결과 가운데 더 나쁘고, 리뷰에서 가장 알아채기 어렵습니다.
+
+**현재 렌더링된 것에서 식별자, 위치, 크기를 도출합니다.** 컬렉션을 기반으로 하는 컴포넌트는 이 값들을
+데이터에서 답합니다. 렌더링 루프에서 계산하면 목록이 가상화되거나 필터링되는 순간 조용히 깨집니다.
+
+## Registry와 이 문서가 다를 때
+
+**언제나 설치된 Registry가 이깁니다.** Registry는 실제로 `node_modules`에 있는 코드에서 생성되지만, 이
+문서는 이전 어느 시점에 쓰인 산문입니다. 위 front matter의 `packageVersion`은 이 문서가 기준으로 삼은
+버전을 기록합니다. 이를 `node_modules/@neurocle/synapse-react/package.json`의 `version`과 비교합니다. 다르다면
+여기 있는 모든 규약을 사실이 아니라 확인할 주장으로 대하고, 항목과 타입 선언을 진실로 받아들입니다.
+
+`dist/registry/index.json`이 없거나 읽을 수 없다면, 이름이나 prop을 추측하는 쪽으로 물러서지 않습니다.
+배포된 타입 선언(`dist/**/*.d.mts`)이나 패키지 `package.json`의 `exports` 맵을 읽습니다. 둘 다 설치된
+코드가 스스로를 설명하는 것입니다. 그래도 컴포넌트가 존재한다는 것을 확인할 수 없다면 그렇다고 말합니다.
+해석되지 않는 임포트는 사용자에게 넘겨진 실패입니다.
+
+## 끝내기 전에
+
+**이 작업의 조회 가운데 하나라도 부재로 끝났는가? 빈 `claimedBy`와 함께 올라 있는 용어였든, 패턴 전체를
+다루는 컴포넌트가 없었든 말입니다. 그렇다면 마지막 메시지에서 반드시 그렇다고 말해야 합니다. 디자인 시스템과
+그것이 다루지 않는 것을 명시하는 한 문장으로.** 예를 들면 이렇습니다. "이 디자인 시스템에는 정렬 가능한
+데이터 테이블 컴포넌트가 없으므로, 여기의 테이블과 정렬은 직접 작성했습니다." 실제로 마주친 패턴을
+적습니다. 이 예는 형태일 뿐, 그대로 옮길 문구가 아니다.
+
+**보고할 의무는 조회 결과가 정하지, 그 뒤에 어떻게 만들었는지가 정하지 않습니다.** 여기가 함정입니다. 실제로
+임포트한 컴포넌트로 그것을 조립하고 나면, 선의로 "직접 만든 것은 없습니다"고 답하게 되고, 그 문장이 가장
+필요한 경우가 바로 스스로 그 문장을 생략하도록 설득하는 경우입니다. 만든 것의 일부를 다루는 컴포넌트는 그
+부분에 쓰는 것이 맞습니다. 그러나 다뤄지는 part를 조립한다고 다뤄지지 않는 패턴이 다뤄지게 되지는 않으며,
+안내되는 역할과 모순되는 용도로 쓴 컴포넌트는 스크린 리더 사용자에게 평범한 요소보다 나쁩니다. 발견한
+부재에는, 그 주변이 직접 작성한 것이든 조립한 것이든 둘 다든, 그 문장이 따라야 합니다.
+
+그 문장은 파일과 똑같이 결과물입니다. 코드 주석이나 작업 중간 어딘가가 아니라 마지막 메시지에 씁니다.
+아무도 열지 않는 파일의 주석은 보고가 아니기 때문입니다.
+
+지금 서 있는 자리에서는 보이지 않는 것이 있습니다. **확인했든 하지 않았든 코드는 똑같습니다.** 꼼꼼한 조회와
+아예 찾아보지 않은 것이 같은 파일을 만들어 내므로, 작성한 어떤 것도 둘 중 무엇이 일어났는지 기록하지
+않습니다. 그 문장을 빼면 답은 조건 없는 성공으로 읽히고, 사용자는 이 코드의 키보드 동작, 접근성, 유지보수를
+자신이 떠맡았다는 사실을 그것이 필요해진 순간에야 알게 됩니다.
+
+그러니 결과물이 좋을수록 그 문장은 더 필요해집니다. 조잡한 결과물은 스스로를 드러냅니다. 좋은 결과물은
+그렇지 않습니다.
+
+## 이 문서가 하지 않는 것
+
+이 문서는 안냅니다. 이를 강제하는 것은 없습니다. 사람이든 에이전트든 이미 다뤄지는 패턴을 직접 만드는 것을
+막는 검사는 없으며, 계획된 것도 없습니다. 이 문서의 효과는 오직 다음에 하는 일에 미칩니다.
+
+또한 이 패키지가 제공하지 않는 UI에 대해서는 아무것도 주장하지 않습니다. 프로젝트가 다른 UI 라이브러리도
+함께 쓴다면 위의 어떤 내용도 그 라이브러리에는 적용되지 않으며, 이 디자인 시스템이 다루지 않는 패턴은
+가장 가까운 컴포넌트로 흉내 낼 것이 아니라 보고하고 다른 곳에서 해결할 것입니다.