@neurocle/synapse-react 0.0.0-bootstrap

package/skills/components/scroll-area/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: 'scroll-area'
+description: 'ScrollArea — 제품이 스크롤바에 스타일을 입힐 수 있는 스크롤 컨테이너로, 그 아래에서는 브라우저 자체의 스크롤을 유지하므로 페이지 내 찾기, 앵커 링크, 스크롤 복원이 모두 그대로 동작합니다. 다른 이름: scroll area, scrollbar, custom scrollbar, overflow box, scroll container, 스크롤 영역, 커스텀 스크롤바, 스크롤 컨테이너.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/scroll-area.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/scroll-area.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# ScrollArea
+
+> 제품이 스크롤바에 스타일을 입힐 수 있는 스크롤 컨테이너로, 그 아래에서는 브라우저 자체의 스크롤을 유지하므로 페이지 내 찾기, 앵커 링크, 스크롤 복원이 모두 그대로 동작합니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `ScrollArea`
+- 분류: `disclosure-layout-display`
+- 수명 주기: `active`
+
+## 알려진 예외 — 사용 전에 확인
+
+이 컴포넌트는 아래 기준 2개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
+
+### WCAG 2.2 SC 1.4.11 비텍스트 대비 (AA)
+
+- 대상 part: `thumb`
+- 충족하지 못하는 것: 스크롤바 썸은 평소 `border.default`로 그려져 3:1에 못 미칩니다. 스크롤바를 직접 가리키거나 드래그할 때만 `border.strong`(3:1)으로 진해집니다. 스크롤바 자체도 영역을 가리키거나 포커스가 있거나 스크롤하는 동안에만 보입니다.
+- 의도한 이유: 스크롤바는 역할이 없는 포인터 편의 기능이며, viewport는 휠·터치·키보드로 이미 스크롤됩니다. 항상 진하게 보이는 막대는 콘텐츠보다 눈에 띄었습니다. `contrast-pairs.json`에 `hairline` 용도로 기록되어 있습니다.
+- 사용 시 유의점: 영역에 스크롤할 내용이 더 있다는 사실을 스크롤바에만 맡기지 마세요. 필요하면 가장자리 페이드나 "더 보기" 같은 단서를 콘텐츠 쪽에 두세요.
+
+### WCAG 2.2 SC 2.5.8 대상 크기(최소) (AA)
+
+- 대상 part: `scrollbar`
+- 충족하지 못하는 것: 스크롤바의 폭은 `icon.sm`으로 최소 대상 크기보다 좁습니다.
+- 의도한 이유: SC 2.5.8의 동등 대안 예외에 기댑니다. 같은 스크롤을 viewport에서 휠·터치·키보드로 할 수 있습니다.
+- 사용 시 유의점: viewport의 키보드 포커스와 이름(`aria-label`)을 제거하지 마세요. 동등 대안이 사라지면 예외도 성립하지 않습니다.
+
+## Do
+
+> 콘텐츠가 넘치는 경계 있는 영역에서, 스크롤바가 운영 체제가 아니라 제품의 모양과 맞아야 할 때 쓰세요. 네이티브 스크롤바가 화면에서 유일하게 테마를 입힐 수 없는 부분이고, 대안이 벤더 의사 요소로 스크롤바를 숨기는 것뿐일 때 이것을 고르세요.
+
+## Don't
+
+> 페이지 자체에는 쓰지 마세요. 문서 자체의 스크롤바는 스크롤 복원, 브라우저 찾기, 모바일에서 주소창이 접히는 동작처럼 컴포넌트가 재현할 수 없는 동작을 지니며, 이를 대체하면 그 모든 것을 겉모습과 맞바꾸게 됩니다. 작은 오버플로를 감추는 데에도 쓰지 마세요. 스크롤되는데 스크롤되는 것처럼 보이지 않는 영역은 사용자가 끝내 찾지 못하는 콘텐츠가 됩니다. 윈도잉해야 하는 긴 목록에도 쓰지 마세요. 스크롤 영역은 주어진 것을 모두 렌더링합니다.
+
+## Anti-patterns
+
+> 콘텐츠를 오버플로시키는 대신 transform으로 옮겨 스크롤하는 것. 이동된 상자는 스크롤된 것이 아닙니다. 페이지 내 찾기가 일치 항목을 화면에 가져오지 못하고, 앵커 탐색은 아무 곳에도 닿지 않으며, 뒤로 가기 시 브라우저가 복원할 것이 없습니다. 이 machine의 설계 전체는 스크롤을 네이티브로 유지하고 스크롤바만 그린다는 데 있습니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `Splitter` (`splitter`)
+- `Toc` (`toc`)
+- `Marquee` (`marquee`)
+
+## 가져오기
+
+```tsx
+import { ScrollArea } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 6개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<ScrollArea.Root>
+  <ScrollArea.Viewport>
+    <ScrollArea.Content />
+  </ScrollArea.Viewport>
+  <ScrollArea.Scrollbar>
+    <ScrollArea.Thumb />
+  </ScrollArea.Scrollbar>
+  <ScrollArea.Corner />
+</ScrollArea.Root>
+```
+
+- `ScrollArea.Root` — 최상위에 놓입니다
+- `ScrollArea.Viewport` — `Root` 안에 놓입니다
+- `ScrollArea.Content` — `Viewport` 안에 놓입니다
+- `ScrollArea.Scrollbar` — `Root` 안에 놓입니다
+- `ScrollArea.Thumb` — `Scrollbar` 안에 놓입니다
+- `ScrollArea.Corner` — `Root` 안에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 2개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. 여기서 크기 축은 스크롤바의 두께만을 뜻합니다. 스크롤 영역 자체의 크기는 레이아웃이 정합니다. 자기 상자의 크기를 스스로 정하는 컴포넌트는 자신이 놓인 그리드나 플렉스 컨테이너와 다투게 되는데, 스크롤 영역의 크기가 실제로 정해지는 곳이 바로 그 컨테이너입니다.
+
+## 폼
+
+폼 참여: 아니요.
+
+> 폼에 제출하는 값이 없습니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 컴포넌트는 주어진 콘텐츠를 무엇이든 렌더링합니다. 컬렉션을 읽지 않으므로 보여줄 것이 없는 상태도 없습니다. 콘텐츠가 없는 스크롤 영역은 그저 스크롤되지 않는 상자일 뿐입니다.
+- `loading-state` — 아직 도착 중인 콘텐츠는 사용처의 것입니다. machine이 실제로 소유하는 것은 콘텐츠의 크기가 바뀔 때 다시 측정하는 일이므로, 스크롤 영역에 콘텐츠 로딩이 끝났다고 알려줄 필요가 없습니다.
+- `error-state` — 컴포넌트가 실패할 수 있는 일이 없습니다. 측정과 그리기를 소유할 뿐이며, 둘 다 사용자가 대응할 수 있는 실패를 갖지 않습니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> 스크롤할 수 있는 동안 뷰포트는 번역 가능한 'scrollArea.viewport.label'로 이름이 붙은 group입니다. 이름 없는 탭 정지 지점은 아무것도 아닌 것으로 알려지기 때문입니다. region이 아니라 group인 이유는 스크롤 영역이 여럿 있는 페이지가 똑같은 이름의 항목으로 랜드마크 목록을 채우지 않게 하기 위해서입니다. 더 나은 이름이 있는 제품은 aria-labelledby로 자신의 제목을 가리킵니다.
+
+### 포커스
+
+> 어느 한 축이라도 넘치는 동안 뷰포트가 tabindex를 받습니다. machine은 두 축이 모두 넘칠 때만 그렇게 해서, 한 방향으로만 스크롤되는 목록에는 도달할 수 없었습니다. 스크롤할 수 없는 스크롤 영역은 탭 정지 지점이 아니므로, 아무 일도 일어나지 않는 상자들로 탭 순서가 채워지지 않습니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 예. 세로 스크롤바는 논리적 인라인 끝 가장자리에 놓이고 모서리도 이를 따르므로, 오른쪽에서 왼쪽으로 쓰는 로케일에서는 둘 다 반대쪽으로 옮겨갑니다. 방향은 prop이 아니라 provider에서 옵니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `custom-scrollbar`, `overflow-container`, `native-scrolling`.
+- 다른 이름: `scroll area`, `scrollbar`, `custom scrollbar`, `overflow box`, `scroll container`, `스크롤 영역`, `커스텀 스크롤바`, `스크롤 컨테이너`.
+- 어휘 상태: `controlled`.

package/skills/components/select/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: 'select'
+description: 'Select — 선택지 목록을 여는 trigger로, 고른 값 하나 또는 여러 개를 폼과 함께 제출합니다. 렌더링된 요소가 아니라 컬렉션이 동작을 이끕니다. 다른 이름: select, dropdown, picker, combo, option list, listbox, 셀렉트 박스, 드롭다운, 선택 상자, 콤보 박스.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/select.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/select.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# Select
+
+> 선택지 목록을 여는 trigger로, 고른 값 하나 또는 여러 개를 폼과 함께 제출합니다. 렌더링된 요소가 아니라 컬렉션이 동작을 이끕니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `Select`
+- 분류: `collection-data-entry`
+- 수명 주기: `active`
+
+## 알려진 예외 — 사용 전에 확인
+
+이 컴포넌트는 아래 기준 1개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
+
+### WCAG 2.2 SC 1.4.11 비텍스트 대비 (AA)
+
+- 대상 part: `item`
+- 충족하지 못하는 것: Select의 강조된 항목은 `secondary.default` 배경만으로 표시되며, overlay 배경 대비 1.16:1(밝은 테마), 1.46:1(어두운 테마)로 3:1에 못 미칩니다. 포인터와 키보드 모두 링을 그리지 않습니다.
+- 의도한 이유: 모든 강조 행에 링을 그리면 시스템의 다른 어떤 hover보다 무겁게 보였습니다. 포커스는 목록에 머물고 강조된 항목은 `aria-activedescendant`로 보조 기술에 전달되며, 선택된 항목은 파란 글자와 체크 표시로 따로 구분됩니다. `contrast-pairs.json`에 `highlight` 용도로 기록되어 있습니다.
+- 사용 시 유의점: 저시력 사용자에게 강조 위치가 잘 보이지 않을 수 있습니다. 접근성 감사 대상 제품이라면 이 예외를 감사 문서에 포함하세요. 항목을 직접 그릴 때는 선택 상태의 글자색과 체크 표시를 지워 강조와 선택을 같은 모양으로 만들지 마세요.
+
+## Do
+
+> 사용자가 한 번에 모두 볼 필요는 없는 알려진 집합에서 고를 때, 그리고 모든 선택지를 보여주면 페이지가 복잡해질 만큼 집합이 길 때 쓰세요. 선택지가 데이터일 때, 곧 서버에서 가져오거나 그룹으로 묶이거나 수백 개에 이를 때 알맞은 컨트롤입니다. 컬렉션이 탐색, 타입어헤드, 안내되는 위치를 우연히 렌더링된 것이 아니라 그 데이터로부터 답하기 때문입니다.
+
+## Don't
+
+> 페이지에 다 들어가는 몇 개의 상호 배타적인 선택지에는 쓰지 마세요. RadioGroup은 모든 선택지를 한 번에 보여주며, 사용자가 읽는 데 아무 조작도 필요 없습니다. 사용자가 입력해서 집합을 좁히거나 집합에 없는 값을 입력해야 할 때도 쓰지 마세요. 그것은 Combobox이며, Select에 검색 필드를 덧붙이면 접근성 계약 없는 Combobox를 다시 만드는 셈입니다. 명령이나 탐색에도 쓰지 마세요. listbox는 항목을 현재 값이 있는 선택지로 알리는데, 하나를 고르는 순간 다른 곳으로 이동한다면 그 안내는 거짓이 됩니다.
+
+## Anti-patterns
+
+> 렌더링된 항목으로부터 위치나 크기를 도출하는 것. aria-setsize는 컬렉션 전체여야 하고 항목의 식별자는 그 값으로부터 도출되므로, 한 번도 DOM에 들어간 적 없는 항목도 안정적인 id와 올바른 안내 위치를 가집니다. 둘 중 하나라도 렌더링 루프에서 계산하면 목록이 윈도잉되는 순간 깨지며, 그것도 조용히 깨집니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `Combobox` (`combobox`)
+- `Listbox` (`listbox`)
+- `RadioGroup` (`radio-group`)
+- `Menu` (`menu`)
+- `CascadeSelect` (`cascade-select`)
+
+## 가져오기
+
+```tsx
+import { Select } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 15개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<Select.Root>
+  <Select.Label />
+  <Select.Positioner>
+    <Select.Content>
+      <Select.List>
+        <Select.ItemGroup>
+          <Select.Item>
+            <Select.ItemText />
+            <Select.ItemIndicator />
+          </Select.Item>
+          <Select.ItemGroupLabel />
+        </Select.ItemGroup>
+      </Select.List>
+    </Select.Content>
+  </Select.Positioner>
+  <Select.Control>
+    <Select.Trigger>
+      <Select.Indicator />
+      <Select.ValueText />
+    </Select.Trigger>
+    <Select.ClearTrigger />
+  </Select.Control>
+</Select.Root>
+```
+
+- `Select.Root` — 최상위에 놓입니다
+- `Select.Label` — `Root` 안에 놓입니다
+- `Select.Positioner` — `Root` 안에 놓입니다
+- `Select.Trigger` — `Control` 안에 놓입니다
+- `Select.Indicator` — `Trigger` 안에 놓입니다
+- `Select.ClearTrigger` — `Control` 안에 놓입니다
+- `Select.Item` — `ItemGroup` 안, 또는 `List` 안에 놓입니다
+- `Select.ItemText` — `Item` 안에 놓입니다
+- `Select.ItemIndicator` — `Item` 안에 놓입니다
+- `Select.ItemGroup` — `List` 안에 놓입니다
+- `Select.ItemGroupLabel` — `ItemGroup` 안에 놓입니다
+- `Select.List` — `Content` 안에 놓입니다
+- `Select.Content` — `Positioner` 안에 놓입니다
+- `Select.Control` — `Root` 안에 놓입니다
+- `Select.ValueText` — `Trigger` 안에 놓입니다
+
+### part가 렌더링하고 소유하는 요소
+
+- `hiddenSelect`, `Select.Root`가 렌더링합니다 — 폼과 함께 제출되고 초기화되는 네이티브 select입니다. 컬렉션만 제공할 수 있는 option 자식이 필요하므로, Root가 팩토리의 렌더링 탈출구를 통해 렌더링합니다. 일부러 part로 두지 않았습니다. anatomy 키가 없는 part는 이 Registry의 part 검사에 실패하며, 사용처가 폼이 의존하는 요소를 옮기거나 빠뜨릴 수 있게 되기 때문입니다.
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 24개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+### 필수
+
+- `collection` — `SynapseCollection<TItem>`, 필수. `createCollection`으로 만든 전체 컬렉션. 윈도잉은 이것을 바꾸지 않습니다.
+
+### 선택
+
+- `value` — `readonly string[]`, 선택. 제어되는 선택.
+- `defaultValue` — `readonly string[]`, 선택. 비제어 모드의 초기 선택. `value`를 주면 무시됩니다.
+- `onValueChange` — `(details: SelectValueChangeDetails) => void`, 선택. 제어 여부와 무관하게 선택이 바뀔 때마다 호출됩니다.
+- `highlightedValue` — `string | null`, 선택. 제어되는 하이라이트 아이템. `aria-activedescendant`가 가리키는 대상입니다.
+- `defaultHighlightedValue` — `string | null`, 선택. 비제어 모드에서 처음 하이라이트되는 아이템.
+- `onHighlightChange` — `(details: SelectHighlightChangeDetails) => void`, 선택. 하이라이트가 옮겨 갈 때 호출됩니다.
+- `open` — `boolean`, 선택. 제어되는 목록의 열림 상태.
+- `defaultOpen` — `boolean`, 선택. 비제어 모드의 초기 열림 상태.
+- `onOpenChange` — `(details: { open: boolean; }) => void`, 선택. 목록이 열리거나 닫힐 때마다 호출됩니다.
+- `multiple` — `boolean`, 선택. 둘 이상을 선택할 수 있게 합니다. 값마다 폼 항목을 하나씩 제출합니다.
+- `deselectable` — `boolean`, 선택. 이미 선택된 아이템을 다시 선택하면 선택이 해제됩니다.
+- `closeOnSelect` — `boolean`, 선택. 선택하면 목록을 닫습니다. 단일 Select에서는 기본값이 true입니다.
+- `loopFocus` — `boolean`, 선택. 키보드 이동이 양 끝을 넘어가면 반대쪽으로 돌아옵니다.
+- `positioning` — `SelectPositioning`, 선택. 목록이 놓이는 위치.
+- `name` — `string`, 선택. 폼 필드 이름. 이 값이 없으면 컨트롤은 아무것도 제출하지 않습니다.
+- `form` — `string`, 선택. 폼 바깥에 렌더된 Select를 id로 그 폼에 연결합니다.
+- `disabled` — `boolean`, 선택. 비활성화된 Select는 제출하지도, 반응하지도 않습니다.
+- `readOnly` — `boolean`, 선택. 읽기 전용 Select는 값을 제출하지만 바꿀 수는 없습니다.
+- `invalid` — `boolean`, 선택. 보조 기술에 `aria-invalid`로 알립니다.
+- `required` — `boolean`, 선택. 제약 검증. 폼이 제출되려면 무언가가 선택돼 있어야 합니다.
+- `translations` — `TranslationOverrides`, 선택. 이 Select에만 적용되는 접근성 문자열로, provider의 값보다 우선합니다.
+- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`.
+
+## 폼
+
+폼 참여: 예.
+
+- `select`로 제출합니다.
+- 제출 값은 `value`에서 옵니다.
+- 항목은 사용처가 아무것도 설정하지 않았을 때 제출되는 값을 기록하지 않습니다.
+
+> `multiple`이면 값마다 하나씩 같은 이름으로 항목을 제출합니다. 숨겨진 요소가 단일 텍스트 필드가 아니라 option을 가진 네이티브 select인 이유가 이것입니다. `disabled`이면 제출되지 않습니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — Select는 넘겨받은 컬렉션을 보여줄 뿐 스스로 아무것도 좁히지 않으므로, 사용자가 작업하는 동안 비게 되는 일이 없습니다. 사용자가 입력하는 대로 컬렉션이 줄어들어 비어 있음 자체가 새로운 소식이 되는 Combobox와는 다릅니다. trigger가 렌더링되기 전부터 이미 빈 컬렉션은 이 컴포넌트가 존재하기 전에 제품이 아는 사실이며, 이에 대한 올바른 답은 열면 메시지가 나오는 목록이 아니라 다른 컨트롤입니다.
+- `loading-state` — Select는 요청을 보내지 않습니다. 사용처가 컬렉션을 만들어 넘기므로, 진행 중인 데이터 요청은 이 컨트롤이 아니라 주변 화면의 상태입니다. 게다가 클릭해야만 열리는 목록 안의 스피너는 그것이 중요한 시간 내내 보이지 않습니다.
+- `error-state` — 유효하지 않음은 컨트롤의 상태이며, `invalid`로 전달되고 aria-invalid로 알려집니다. 컬렉션을 불러오지 못한 실패는 데이터 요청을 수행한 사용처의 몫입니다. 이를 목록 안에서 알리면, 바로 그 실패 때문에 비어 버린 컨트롤을 열어야만 사용자가 메시지를 보게 됩니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> aria-labelledby를 통해 Label part에서 옵니다. 지우기 trigger의 이름은 provider의 번역에서 오며 Select마다 덮어쓸 수 있습니다. machine이 제공하는 aria-label은 제품이 바꿀 수 없는 문자열이 되기 때문입니다.
+
+### 포커스
+
+> 목록이 열려 있는 동안에도 포커스는 trigger에 머물며, 활성 항목은 aria-activedescendant로 가리킵니다. Select의 어떤 부분도 DOM 포커스를 목록 안으로 옮기지 않으며, 그 덕분에 타입어헤드가 한 요소에서 유지됩니다.
+
+### 알려 주는 위치
+
+> aria-posinset과 aria-setsize는 우연히 DOM에 있는 행이 아니라 컬렉션 전체를 기준으로 합니다. 이 값들은 컬렉션 자체에서 답을 얻으므로, 목록이 어떤 방식으로 렌더링되든 안내가 사실대로 유지됩니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 예. 목록의 배치는 논리적이므로 `bottom-start`는 텍스트 방향을 따릅니다. 타입어헤드는 제품이 제공하는 항목 레이블과 대조하며, 그 레이블은 해당 로케일의 것입니다.
+- 컬렉션 윈도잉: 아니요. Select는 사용처가 매핑한 항목을 렌더링하며 윈도잉을 제공하지 않습니다. 기반이 되는 컬렉션 인터페이스는 위치, 크기, 타입어헤드를 데이터만으로 답하므로(`packages/react/src/shared/collection.ts`), 나중에 이 컴포넌트의 공개 인터페이스를 바꾸지 않고도 윈도잉을 추가할 수 있습니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `choose-from-list`, `single-select`, `multi-select`, `grouped-options`, `typeahead`, `form-value`, `floating-layer`, `readonly-display`, `translatable-strings`.
+- 다른 이름: `select`, `dropdown`, `picker`, `combo`, `option list`, `listbox`, `셀렉트 박스`, `드롭다운`, `선택 상자`, `콤보 박스`.
+- 어휘 상태: `controlled`.

package/skills/components/separator/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: 'separator'
+description: 'Separator — 인접한 콘텐츠 사이에 가로나 세로로 선을 그어 구획을 나누는 컴포넌트입니다. 기본으로 장식이라 보조 기술에 드러나지 않으며, 선이 문서의 구획을 나눌 때만 `separator` 역할을 줍니다. 다른 이름: separator, divider, horizontal rule, hr, vertical divider, 구분선, 가로선, 세로 구분선.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/separator.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/separator.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# Separator
+
+> 인접한 콘텐츠 사이에 가로나 세로로 선을 그어 구획을 나누는 컴포넌트입니다. 기본으로 장식이라 보조 기술에 드러나지 않으며, 선이 문서의 구획을 나눌 때만 `separator` 역할을 줍니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `Separator`
+- 분류: `disclosure-layout-display`
+- 수명 주기: `active`
+
+## Do
+
+> 관련된 콘텐츠 무리 사이의 경계를 선으로 보여 줄 때 쓰세요 — 설정 목록의 묶음 사이, 카드 안의 머리와 본문 사이, 툴바 안의 버튼 묶음 사이처럼 말입니다. 선이 시각적 정리일 뿐이면 기본값(장식)으로 두고, 스크린 리더 사용자도 구획이 바뀐다는 사실을 알아야 할 때만 `decorative={false}`로 `separator` 역할을 주세요.
+
+## Don't
+
+> 간격을 만들려고 쓰지 마세요 — 요소 사이의 공간은 레이아웃의 `gap`이 정합니다. 사용자가 드래그해 영역 크기를 바꾸는 경계는 Splitter이며, Separator는 포커스도 값도 없습니다. Menu 안에서 항목 묶음을 나누는 선은 Menu 자체의 separator part를 쓰세요. 메뉴의 키보드 이동과 구조는 그 part만 압니다.
+
+## Anti-patterns
+
+> 모든 구분선에 `decorative={false}`를 주는 것. 구획마다 separator가 알려지면 스크린 리더 사용자는 의미 없는 경계를 계속 듣게 됩니다 — 구조적인 구분선은 제목이나 랜드마크로 이미 드러나지 않는 경계에만 두세요.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-26).
+
+## 관련 컴포넌트
+
+- `Splitter` (`splitter`)
+- `Menu` (`menu`)
+
+## 가져오기
+
+```tsx
+import { Separator } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 1개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<Separator.Root />
+```
+
+- `Separator.Root` — 최상위에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 2개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `orientation` — `Orientation`, 선택. 선이 놓이는 방향. 기본값은 `horizontal`입니다.
+- `decorative` — `boolean`, 선택. 기본값 `true`에서는 보조기술에 드러나지 않습니다. 선이 내용의 구획을 나눠 스크린 리더 사용자도 알아야 할 때만 `false`로 두어 `separator` 역할을 줍니다.
+
+## 폼
+
+폼 참여: 아니요.
+
+> 폼에 제출하는 값이 없습니다. 폼 안에 놓여도 구획을 나누는 레이아웃 요소일 뿐입니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `size-axis` — 선은 굵기가 한 가지인 구분선이라 크기 척도가 뜻을 갖지 않습니다. 길이는 놓인 레이아웃이 정하고 굵기는 헤어라인 테두리 토큰 하나가 정하므로, xs부터 xl까지 고를 대상이 없습니다.
+- `empty-state` — 구분선은 콘텐츠를 담지 않는 요소라 비어 있을 수 있는 집합이 없습니다. 나눌 내용이 없으면 구분선 자체를 렌더링하지 않습니다.
+- `loading-state` — 구분선은 아무것도 가져오지 않으므로 불러오는 중인 구간이 없습니다. 주변 콘텐츠가 로딩 중이라는 표시는 그 콘텐츠 쪽의 몫입니다.
+- `error-state` — 구분선에는 값도 입력도 없어 실패할 수 있는 것이 없습니다. 알릴 오류도, 오류를 보여 줄 자리도 없습니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> 이름이 필요 없습니다. 장식용 구분선은 접근성 트리에 없고, 구조적인 구분선은 역할과 방향만으로 구획의 경계를 알립니다.
+
+### 포커스
+
+> 포커스를 받지 않습니다. 구조적인 구분선도 포커스할 수 없는 separator이며 값을 가진 분할 핸들이 아닙니다 — 드래그로 크기를 조절하는 구분선은 Splitter입니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `content-divider`, `axis-orientation`.
+- 다른 이름: `separator`, `divider`, `horizontal rule`, `hr`, `vertical divider`, `구분선`, `가로선`, `세로 구분선`.
+- 어휘 상태: `controlled`.

package/skills/components/signature-pad/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: 'signature-pad'
+description: 'SignaturePad — 사람이 포인터, 펜, 손가락으로 서명하는 표면으로, 획을 SVG 경로 데이터로 만들어 내고 요청하면 서명 전체를 래스터 이미지로도 만들어 줍니다. 다른 이름: signature pad, signature, sign here, draw, e-signature, 서명 패드, 전자 서명, 서명 입력, 사인 패드.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/signature-pad.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/signature-pad.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# SignaturePad
+
+> 사람이 포인터, 펜, 손가락으로 서명하는 표면으로, 획을 SVG 경로 데이터로 만들어 내고 요청하면 서명 전체를 래스터 이미지로도 만들어 줍니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `SignaturePad`
+- 분류: `range-and-drawing`
+- 수명 주기: `active`
+
+## 알려진 예외 — 사용 전에 확인
+
+이 컴포넌트는 아래 기준 2개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
+
+### WCAG 2.2 SC 2.1.1 키보드 (A)
+
+- 충족하지 못하는 것: 서명은 포인터 제스처로만 그릴 수 있고 키보드로 대신할 방법이 없습니다.
+- 의도한 이유: 서명을 그리는 행위 자체가 경로 기반 제스처이며, 어떤 machine도 키보드 대안을 제공하지 않습니다.
+- 사용 시 유의점: 서명이 필수인 곳에서는 패드 옆에 이름 입력 같은 입력식 대안을 함께 제공하세요. 그려진 서명만 받는 폼은 키보드만으로 완료할 수 없습니다.
+
+### HTML 폼 제출 — 알려진 결함
+
+- 충족하지 못하는 것: `name`도 `required`도 노출하지 않아 폼 제출에 서명이 포함되지 않습니다.
+- 의도한 이유: 서명의 data URL은 비동기인 `getDataUrl()`로만 만들어지므로 렌더링 중에 숨겨진 입력에 넣을 수 없습니다. 업스트림도 사용처가 넘기게 합니다.
+- 사용 시 유의점: `onValueChangeEnd`에서 data URL을 받아 제품의 숨겨진 필드에 넣어 제출하고, 필수 여부도 제품에서 검증하세요.
+
+## Do
+
+> 동의를 나타내는 손글씨 표시를 받을 때, 곧 그려진 모양 자체가 기록 대상일 때 쓰세요. 배송 수령 확인, 동의서, 태블릿으로 서명하는 계약서가 그런 예입니다. 텍스트가 아니라 획 자체가 가치인 짧은 자유 곡선 주석에도 쓸 수 있습니다.
+
+## Don't
+
+> 입력한 이름으로 충분한 곳에는 SignaturePad를 쓰지 마세요. 입력한 이름은 읽을 수 있고, 검색할 수 있고, 키보드로 조작할 수 있으며, 포인터를 쓸 수 없는 사람도 접근할 수 있지만, 그린 이름은 그중 어느 것도 아닙니다. 범용 그리기 캔버스로도 쓰지 마세요. 색도, 지우개도, 전체 지우기 외의 실행 취소도 없습니다. 받은 서명을 신원 증명으로 취급하지 마세요. 서명은 누군가가 무엇을 그렸는지를 기록할 뿐, 누가 그렸는지는 기록하지 않습니다.
+
+## Anti-patterns
+
+> `name`을 선언하고 machine의 숨겨진 입력이 서명을 제출해 주리라 기대하는 것. 그 값은 비동기로 만들어지는 data URL이므로, 필드는 렌더링될 때마다 빈 문자열을 제출합니다. 연결된 것처럼 보이지만 실제로는 연결되지 않은 폼입니다. 대신 onValueChangeEnd에서 data URL을 받아 쓰세요.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `FileUpload` (`file-upload`)
+- `Checkbox` (`checkbox`)
+- `Editable` (`editable`)
+
+## 가져오기
+
+```tsx
+import { SignaturePad } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 7개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<SignaturePad.Root>
+  <SignaturePad.Control>
+    <SignaturePad.Segment>
+      <SignaturePad.SegmentPath />
+    </SignaturePad.Segment>
+    <SignaturePad.Guide />
+  </SignaturePad.Control>
+  <SignaturePad.ClearTrigger />
+  <SignaturePad.Label />
+</SignaturePad.Root>
+```
+
+- `SignaturePad.Root` — 최상위에 놓입니다
+- `SignaturePad.Control` — `Root` 안에 놓입니다
+- `SignaturePad.Segment` — `Control` 안에 놓입니다
+- `SignaturePad.SegmentPath` — `Segment` 안에 놓입니다
+- `SignaturePad.Guide` — `Control` 안에 놓입니다
+- `SignaturePad.ClearTrigger` — `Root` 안에 놓입니다
+- `SignaturePad.Label` — `Root` 안에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 10개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `value` — `readonly string[]`, 선택. 제어되는 획들이며, SVG 패스 데이터로 표현합니다.
+- `defaultValue` — `readonly string[]`, 선택. 비제어 모드의 초기 획들. `value`를 주면 무시됩니다.
+- `onValueChange` — `(details: SignaturePadValueChangeDetails) => void`, 선택. 획이 확정될 때, 그리고 획을 긋는 도중에 호출됩니다.
+- `onValueChangeEnd` — `(details: SignaturePadValueChangeEndDetails) => void`, 선택. 획이 끝났을 때 호출됩니다. 값을 저장할 시점은 이쪽입니다.
+- `stroke` — `SignatureStrokeOptions`, 선택. 획을 그리는 방식.
+- `disabled` — `boolean`, 선택. 비활성화된 SignaturePad에는 그릴 수 없고, 탭 순서에도 들어가지 않습니다.
+- `readOnly` — `boolean`, 선택. 읽기 전용 SignaturePad는 획을 보여주지만 그 위에 그릴 수는 없습니다.
+- `translations` — `TranslationOverrides`, 선택. 이 SignaturePad에만 적용되는 접근성 문자열로, provider의 값보다 우선합니다.
+- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`.
+
+## 폼
+
+폼 참여: 아니요.
+
+> machine의 숨겨진 입력은 서명을 data URL로 받는데, data URL은 SVG를 래스터화하기 때문에 비동기인 getDataUrl()이 만듭니다. 어떤 컴포넌트도 렌더링 중에 이를 제공할 수 없으며, 그래서 업스트림도 사용처가 이를 넘기게 합니다. 따라서 이 getter는 렌더링하지 않는 것으로 선언되고 컴포넌트는 `name`도 `required`도 노출하지 않습니다. 사용처는 onValueChangeEnd에서 data URL을 받아 자신의 필드에 넣는 방식으로 서명을 제출합니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 서명되지 않은 패드는 콘텐츠를 기다리는 빈 컬렉션이 아니라 컨트롤의 시작 상태이며, 가이드 선과 표면이 이미 무엇을 해야 하는지 말해 줍니다. 이름 붙은 빈 상태 part를 두면 서명이 들어갈 자리에 메시지가 놓이게 됩니다.
+- `loading-state` — 저장된 서명이 아직 도착 중인 패드는 비활성화된 패드에 사용처의 스켈레톤을 더한 것입니다. 기존 서명을 래스터화하는 일은 비동기지만, 그 결과는 사용처가 갖는 이미지이지 이 컨트롤의 상태가 아닙니다.
+- `error-state` — machine은 유효하지 않은 상태를 보고하지 않고 컴포넌트도 `invalid` prop을 선언하지 않으므로, 오류 part를 움직일 근거가 없습니다. 서명이 있는지, 충분히 긴지, 상자 안에 있는지 같은 검증은 주변 필드의 몫입니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> 컨트롤은 aria-labelledby를 통해 Label part가 이름을 붙이며, Label이 렌더링되지 않으면 provider의 signaturePad.control.label로 대체됩니다. machine은 Label의 htmlFor를 이 컴포넌트가 렌더링하지 않는 숨겨진 입력으로 향하게 하므로 그 `for`는 제거됩니다. 역할 설명은 machine의 영어 문자열 "signature pad" 대신 `signaturePad.control.roleDescription`에서 옵니다.
+
+### 포커스
+
+> 컨트롤 자체가 포커스를 받으므로, 서명은 포인터 제스처지만 표면에는 키보드로도 도달할 수 있습니다. 지우기 trigger는 패드가 비어 있는 동안 숨겨지고, 획이 생기면 탭 순서에 다시 들어갑니다.
+
+### 알려진 한계
+
+> 서명 자체는 포인터 제스처이며, 이 machine에서든 다른 어떤 machine에서든 키보드로 대신할 방법이 없습니다. 그려진 서명만 받는 폼은 키보드만으로 조작할 수 없으므로, 그것이 중요한 곳에서는 패드 옆에 입력식 대안을 함께 제공하세요.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `freehand-drawing`, `signature-capture`, `vector-output`, `image-export`, `readonly-display`, `translatable-strings`.
+- 다른 이름: `signature pad`, `signature`, `sign here`, `draw`, `e-signature`, `서명 패드`, `전자 서명`, `서명 입력`, `사인 패드`.
+- 어휘 상태: `controlled`.