@neurocle/synapse-react 0.0.0-bootstrap

package/skills/components/progress/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: 'progress'
+description: 'Progress — 작업이 얼마나 진행되었는지를 막대나 원형 링으로 그립니다. 하나의 machine과 하나의 anatomy가 두 표현을 모두 맡으며, 두 표현의 차이는 오로지 제품이 어떤 part를 조합하느냐에 달려 있습니다. 다른 이름: progress, progress bar, loading bar, spinner ring, completion meter, 진행률, 프로그레스 바, 진행 표시줄, 로딩 바.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/progress.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/progress.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# Progress
+
+> 작업이 얼마나 진행되었는지를 막대나 원형 링으로 그립니다. 하나의 machine과 하나의 anatomy가 두 표현을 모두 맡으며, 두 표현의 차이는 오로지 제품이 어떤 part를 조합하느냐에 달려 있습니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `Progress`
+- 분류: `disclosure-layout-display`
+- 수명 주기: `active`
+
+## Do
+
+> 제품이 소요 시간을 측정할 수 있는 작업, 또는 측정할 수는 없지만 진행 중임을 보여줄 가치가 있는 작업에 쓰세요. 진행 표시가 아바타, 버튼, 타일처럼 둥글거나 작은 것 안에 놓일 때는 막대 대신 링을 고르세요. 둘은 같은 컴포넌트이므로 바꾸는 비용은 조합을 바꾸는 것뿐이라는 점을 기억하세요.
+
+## Don't
+
+> 컨트롤로 쓰지 마세요. 진행 막대를 끄는 사람은 탐색을 기대하지만 이 컴포넌트에는 그런 계약이 없으며, 그것은 Slider의 몫입니다. 사용자가 오가는 흐름의 단계에도 쓰지 마세요. Steps는 자체 진행 part를 갖고 있으며 어떤 단계가 끝났는지도 압니다. 1초 안에 끝나는 일에는 불확정 막대를 쓰지 마세요. 나타났다 사라지는 깜빡임이 되어, 작업이 아니라 오류처럼 읽힙니다.
+
+## Anti-patterns
+
+> 막대와 링을 두 개의 컴포넌트로 내보내거나, 둘 중 하나를 고르는 `presentation` prop을 추가하는 것. 어느 쪽이든 같은 machine이 두 이름에 응답하게 만듭니다. `size` 옆의 두 번째 variant 축은 Synapse가 제공하지 않는 것이며, 조합이 이미 사용처의 트리 안에서 그 선택을 눈에 보이게 드러냅니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `Steps` (`steps`)
+- `Timer` (`timer`)
+- `Slider` (`slider`)
+
+## 가져오기
+
+```tsx
+import { Progress } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 9개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<Progress.Root>
+  <Progress.Label />
+  <Progress.Track>
+    <Progress.Range />
+  </Progress.Track>
+  <Progress.ValueText />
+  <Progress.View />
+  <Progress.Circle>
+    <Progress.CircleTrack />
+    <Progress.CircleRange />
+  </Progress.Circle>
+</Progress.Root>
+```
+
+- `Progress.Root` — 최상위에 놓입니다
+- `Progress.Label` — `Root` 안에 놓입니다
+- `Progress.Track` — `Root` 안에 놓입니다
+- `Progress.Range` — `Track` 안에 놓입니다
+- `Progress.ValueText` — `Root` 안에 놓입니다
+- `Progress.View` — `Root` 안에 놓입니다
+- `Progress.Circle` — `Root` 안에 놓입니다
+- `Progress.CircleTrack` — `Circle` 안에 놓입니다
+- `Progress.CircleRange` — `Circle` 안에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 9개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `value` — `number | null`, 선택. 얼마나 진행됐는지이며 제어 모드입니다. `null`은 진행도를 알 수 없음을 뜻합니다. 막대는 돌아가고 있지만 얼마나 왔는지 모르는 상태이며, 이는 `0`과는 다른 주장입니다.
+- `defaultValue` — `number | null`, 선택. 비제어 모드의 초기 값. `value`를 주면 무시됩니다.
+- `onValueChange` — `(details: ValueChangeDetails<number | null>) => void`, 선택. 제어 여부와 무관하게 값이 바뀔 때마다 호출됩니다.
+- `min` — `number`, 선택. 범위의 아래 끝. 기본값은 0입니다.
+- `max` — `number`, 선택. 범위의 위 끝. 기본값은 100입니다.
+- `formatOptions` — `Intl.NumberFormatOptions`, 선택. 값을 텍스트로 렌더하는 방식. 기본값은 백분율입니다.
+- `orientation` — `Orientation`, 선택. 선형 막대가 채워지는 축. 기본값은 `horizontal`입니다. 링에서는 무시됩니다.
+- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. 크기 축은 막대의 두께와 링의 지름을 조절하며, 컴포넌트의 인라인 방향 길이는 조절하지 않습니다. 선형 Progress는 주어진 너비를 채웁니다. 진행 막대의 너비는 다섯 단계 척도가 아니라 주변 레이아웃이 정할 일이기 때문입니다.
+
+## 폼
+
+폼 참여: 아니요.
+
+> 폼에 제출하는 값이 없습니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 값이 없는 진행 막대는 비어 있는 것이 아니라 불확정 상태입니다. 이는 machine이 이미 가진 상태이며, 작업은 진행 중이지만 얼마나 진행되었는지 모른다는 점에서 '비어 있음'보다 강한 주장입니다. 이를 0으로 뭉개면 아무도 측정하지 않은 진행률을 보고하게 됩니다.
+- `loading-state` — 로딩은 이 컴포넌트가 곧 하는 일입니다. 이미 보고하는 값 위에 두 번째 로딩 상태를 얹을 일은 없으며, 불확정 상태의 Progress가 그 답이 취하는 모습입니다.
+- `error-state` — 실패한 작업은 더 이상 진행되지 않으므로, 제품은 막대 안에 오류 상태를 넣지 않고 막대 자체를 교체합니다. `View`를 쓰면 이 교체를 이 컴포넌트가 해석해야 할 prop이 아니라 상태마다 하나씩 뷰를 두는 조합으로 작성할 수 있습니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> aria-labelledby를 통해 Label part에서 가져옵니다. Label이 없으면 번역 가능한 'progress.root.label'로 대체됩니다. 서식이 입혀진 값은 막대의 aria-valuetext가 되며, 알 수 없는 값은 machine의 영어 문자열 'loading...'이 아니라 번역 가능한 'progress.valueText.indeterminate'로 읽힙니다.
+
+### 포커스
+
+> 여기에는 포커스 가능한 것이 없습니다. 제품은 흔히 진행 막대를 링크나 버튼의 내용으로 쓰고, 그러면 막대 자체의 상자가 곧 전체 대상이 되므로 최소 대상 크기를 루트에 둡니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 예. 가로 막대는 논리적 인라인 방향으로 채워지며, 값 텍스트는 제품이 제공하는 숫자 옵션으로 Intl을 통해 서식이 입혀집니다. 방향은 prop이 아니라 provider에서 옵니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `determinate-progress`, `indeterminate-progress`, `circular-progress`, `axis-orientation`.
+- 다른 이름: `progress`, `progress bar`, `loading bar`, `spinner ring`, `completion meter`, `진행률`, `프로그레스 바`, `진행 표시줄`, `로딩 바`.
+- 어휘 상태: `controlled`.

package/skills/components/qr-code/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: 'qr-code'
+description: 'QrCode — 문자열을 인코딩한 스캔 가능한 정사각형으로, 요소의 격자가 아니라 하나의 SVG 경로로 그려지며, 로고를 얹는 선택적 overlay와 이미지로 내려받는 trigger를 갖추고 있습니다. 다른 이름: qr code, qr, 2d barcode, scan code, matrix code, QR 코드, 큐알 코드, 2차원 바코드.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/qr-code.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/qr-code.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# QrCode
+
+> 문자열을 인코딩한 스캔 가능한 정사각형으로, 요소의 격자가 아니라 하나의 SVG 경로로 그려지며, 로고를 얹는 선택적 overlay와 이미지로 내려받는 trigger를 갖추고 있습니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `QrCode`
+- 분류: `disclosure-layout-display`
+- 수명 주기: `active`
+
+## Do
+
+> 값을 페이지가 아니라 사용자가 손에 든 기기로 넘겨줄 때 쓰세요. 로그인 확인, Wi-Fi 네트워크, 티켓, 휴대폰에서 이어서 하기 위한 링크가 그런 예입니다. overlay는 오류 정정 수준이 높을 때만 쓰세요. 코드의 가운데도 데이터이므로 이를 가리면 중복성을 잃게 되고, 그 중복성은 인코더에 미리 추가하라고 지시해 두었어야 합니다.
+
+## Don't
+
+> 무언가에 도달하는 유일한 수단으로 쓰지 마세요. 코드는 두 번째 기기가 없는 사람이나 스크린 리더 사용자에게는 읽을 수 없으므로, 같은 목적지로 가는 링크나 복사 가능한 문자열을 옆에 두어야 하며 보통 Clipboard가 그 짝이 됩니다. 사용자가 보는 동안 바뀌는 값에도 쓰지 마세요. 다시 렌더링되는 도중에 스캔되는 코드는 조용히 실패하고, 카메라가 나쁜 것처럼 보입니다.
+
+## Anti-patterns
+
+> Frame과 Pattern을 팩토리의 요소 도출에 맡겨 두는 것. machine은 `viewBox`, `xmlns`, 경로의 `d`를 내보낼 뿐 요소에 대해서는 아무 말도 하지 않으므로, 도출된 기본값은 둘 다 `div`가 됩니다. 그리고 다른 `div` 안에 있는 `d` 속성을 가진 `div`는 아무것도 그리지 않습니다. 컴포넌트는 렌더링되고 모든 구조 검사를 통과하지만 텅 비어 있습니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `Clipboard` (`clipboard`)
+- `Avatar` (`avatar`)
+
+## 가져오기
+
+```tsx
+import { QrCode } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 5개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<QrCode.Root>
+  <QrCode.Frame>
+    <QrCode.Pattern />
+  </QrCode.Frame>
+  <QrCode.Overlay />
+  <QrCode.DownloadTrigger />
+</QrCode.Root>
+```
+
+- `QrCode.Root` — 최상위에 놓입니다
+- `QrCode.Frame` — `Root` 안에 놓입니다
+- `QrCode.Pattern` — `Frame` 안에 놓입니다
+- `QrCode.Overlay` — `Root` 안에 놓입니다
+- `QrCode.DownloadTrigger` — `Root` 안에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 7개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `value` — `string`, 선택. 인코딩할 문자열이며 제어 모드입니다.
+- `defaultValue` — `string`, 선택. 비제어 모드의 초기 문자열. `value`를 주면 무시됩니다.
+- `onValueChange` — `(details: ValueChangeDetails<string>) => void`, 선택. 제어 여부와 무관하게 인코딩된 문자열이 바뀔 때마다 호출됩니다.
+- `encoding` — `QrCodeEncoding`, 선택. 값을 행렬로 바꾸는 방식.
+- `pixelSize` — `number`, 선택. 모듈 하나가 그려지는 크기(픽셀)입니다. 공용 크기 척도가 아니며, 의도적으로 그것과 분리해 두었습니다. 코드의 전체 크기는 모듈 크기에 인코더가 고른 버전을 곱한 값이므로, 이름 붙은 다섯 크기짜리 척도로는 둘 중 하나를 속이지 않고서는 이를 표현할 수 없습니다.
+- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. 공용 척도는 여기서 유일한 일반 컨트롤인 다운로드 trigger의 크기를 조절합니다. 코드 자체가 그려지는 크기는 `pixelSize`에 인코더가 값에 맞춰 고른 버전을 곱한 것이며, 다섯 단계 척도로는 둘 중 하나를 속이지 않고서는 이를 표현할 수 없습니다.
+
+## 폼
+
+폼 참여: 아니요.
+
+> 폼에 제출하는 값이 없습니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 빈 값도 유효하고 스캔 가능한 코드, 곧 빈 문자열을 담은 코드로 인코딩됩니다. 컴포넌트가 그릴 것이 없는 상태는 존재하지 않으며, 그래서 값은 빠질 수 있는 것이 아니라 평범한 prop입니다.
+- `loading-state` — 인코딩은 동기적이며 렌더링 중에 일어납니다. 코드는 존재하지만 아직 그려지지 않은 순간이 없으므로, 로딩 상태가 가릴 것이 없습니다.
+- `error-state` — 가장 큰 버전에도 담기지 않을 만큼 긴 값은 컴포넌트의 상태가 아니라 인코더의 오류입니다. 스캔되지 않을 코드를 렌더링하는 대신, 제품이 값을 줄일 수 있는 곳인 값을 넘기는 지점에서 예외를 던집니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> Frame은 role="img"이며 `qrCode.frame.label`로 이름이 붙고, 기본적으로 인코딩된 값을 포함합니다. 제품은 `translations` prop으로 값을 빼거나 문구를 바꿀 수 있습니다. 그래도 코드 옆에 값을 텍스트로 보여주거나 같은 목적지를 링크로 도달할 수 있게 해야 합니다. 코드는 카메라를 위한 것이며, 카메라만이 유일한 사용자는 아닙니다.
+
+### 포커스
+
+> 탭 순서에는 다운로드 trigger만 있습니다. 키보드로 코드 자체에 할 수 있는 일이 없으므로 코드는 포커스를 받지 않습니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 아니요. QR 코드의 기하 구조는 규격으로 고정되어 있으며 좌우 반전되지 않습니다. 루트는 다운로드 trigger의 텍스트를 위해 방향을 전달할 뿐이고, 그 밖에는 여기서 방향을 읽는 것이 없습니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `qr-encoding`, `error-correction`, `image-export`.
+- 다른 이름: `qr code`, `qr`, `2d barcode`, `scan code`, `matrix code`, `QR 코드`, `큐알 코드`, `2차원 바코드`.
+- 어휘 상태: `controlled`.

package/skills/components/radio-group/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: 'radio-group'
+description: 'RadioGroup — 여러 선택지 중 하나를 고르는 컨트롤로, 라디오 목록으로도 세그먼트 컨트롤로도 쓸 수 있습니다. 어느 쪽이든 같은 컴포넌트이며, 어떤 part를 렌더링하느냐로 모양이 정해집니다. 다른 이름: radio group, radio buttons, segmented control, option group, choice list, 라디오 그룹, 라디오 버튼, 세그먼트 컨트롤, 단일 선택.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/radio-group.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/radio-group.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# RadioGroup
+
+> 여러 선택지 중 하나를 고르는 컨트롤로, 라디오 목록으로도 세그먼트 컨트롤로도 쓸 수 있습니다. 어느 쪽이든 같은 컴포넌트이며, 어떤 part를 렌더링하느냐로 모양이 정해집니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `RadioGroup`
+- 분류: `form-controls`
+- 수명 주기: `active`
+
+## Do
+
+> 사용자가 한눈에 비교할 수 있어야 하는 작고 고정된 선택지 중 정확히 하나를 고를 때 쓰세요. 결제 수단, 배송 속도, 요금제가 그런 예입니다. 모든 선택지가 보인다는 점이 Select와의 차이이며, 선택지가 대략 일곱 개를 넘으면 더 이상 확장되지 않는 이유이기도 합니다.
+
+## Don't
+
+> 둘 이상을 고를 수 있을 때는 쓰지 마세요. 그것은 Checkbox의 묶음이며, 라디오는 사용자가 직접 눌러 보기 전까지 선택지가 배타적이라는 것을 알 방법을 주지 않습니다. 길거나 데이터로 채워지는 목록에도 쓰지 마세요. 모든 선택지가 항상 렌더링되고 항상 접근성 트리에 있으므로, 선택지가 몇 개를 넘으면 Select가 맞는 컨트롤입니다. 별도의 SegmentedControl 컴포넌트를 찾지 마세요. 그것은 ItemControl 없이 렌더링한 이 컴포넌트입니다.
+
+## Anti-patterns
+
+> 시각적으로 뻔하다는 이유로 ItemText 없이 항목을 렌더링하는 것. 항목의 접근 가능한 이름은 aria-labelledby를 통해 그 part에서 오므로, 이렇게 만든 아이콘 전용 세그먼트 컨트롤은 아무것도 알리지 않습니다. 화면에서는 완벽해 보이는 유일한 실패 방식입니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `Checkbox` (`checkbox`)
+- `ToggleGroup` (`toggle-group`)
+- `Select` (`select`)
+- `Switch` (`switch`)
+
+## 가져오기
+
+```tsx
+import { RadioGroup } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 6개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<RadioGroup.Root>
+  <RadioGroup.Label />
+  <RadioGroup.Item>
+    <RadioGroup.ItemText />
+    <RadioGroup.ItemControl />
+  </RadioGroup.Item>
+  <RadioGroup.Indicator />
+</RadioGroup.Root>
+```
+
+- `RadioGroup.Root` — 최상위에 놓입니다
+- `RadioGroup.Label` — `Root` 안에 놓입니다
+- `RadioGroup.Item` — `Root` 안에 놓입니다
+- `RadioGroup.ItemText` — `Item` 안에 놓입니다
+- `RadioGroup.ItemControl` — `Item` 안에 놓입니다
+- `RadioGroup.Indicator` — `Root` 안에 놓입니다
+
+### part가 렌더링하고 소유하는 요소
+
+- `itemHiddenInput`, `RadioGroup.Item`이 렌더링합니다 — 항목 하나에 대한 네이티브 라디오 입력입니다. 포커스, 키보드 조작, 폼 제출을 맡으며, 보이는 `itemControl`이 aria-hidden 쪽입니다. 항목마다 하나씩 있고 항목의 값은 사용처의 마크업에 있으므로 Root가 렌더링할 수 없습니다. 그래서 Item part가 이를 소유하고, 자신의 getter를 위해 풀어낸 것과 같은 값을 넘겨줍니다. 일부러 part로 두지 않았습니다. anatomy 키가 없는 part는 이 Registry 자체의 part 검사에 실패하며, 사용처가 컴포넌트의 유일한 포커스 가능 요소를 옮기거나 빠뜨릴 수 있게 되기 때문입니다.
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 12개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `value` — `string | null`, 선택. 제어되는 선택. `null`은 아무것도 선택하지 않음이며, 라디오 그룹에서는 엄연한 상태입니다.
+- `defaultValue` — `string | null`, 선택. 비제어 모드의 초기 선택. `value`를 주면 무시됩니다.
+- `onValueChange` — `(details: ValueChangeDetails<string | null>) => void`, 선택. 제어 여부와 무관하게 선택이 바뀔 때마다 호출됩니다.
+- `orientation` — `Orientation`, 선택. 그룹이 배치되는 축이자, 그 축을 따라 움직이는 화살표 키를 정합니다.
+- `name` — `string`, 선택. 폼 필드 이름. 이 값이 없으면 컨트롤은 아무것도 제출하지 않습니다.
+- `form` — `string`, 선택. 폼 바깥에 렌더된 그룹을 id로 그 폼에 연결합니다.
+- `disabled` — `boolean`, 선택. 비활성화된 RadioGroup은 제출하지도, 반응하지도 않습니다.
+- `readOnly` — `boolean`, 선택. 읽기 전용 RadioGroup은 값을 제출하지만 바꿀 수는 없습니다.
+- `invalid` — `boolean`, 선택. 모든 아이템에 `aria-invalid`로 보조 기술에 알립니다.
+- `required` — `boolean`, 선택. 제약 검증. 폼이 제출되려면 무언가가 선택돼 있어야 합니다.
+- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`.
+
+## 폼
+
+폼 참여: 예.
+
+- `input[type=radio]`로 제출합니다.
+- 제출 값은 `value`에서 옵니다.
+- 항목은 사용처가 아무것도 설정하지 않았을 때 제출되는 값을 기록하지 않습니다.
+
+> 라디오 입력은 항목마다 하나씩 있습니다. 모든 항목이 그룹이 공유하는 `name` 아래에 자신의 네이티브 라디오를 렌더링하므로, FormData에는 정확히 하나의 값만 들어갑니다. `disabled`이면 제출되지 않으며, `required`는 항목 하나를 반드시 골라야 함을 뜻합니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 항목은 컴포넌트가 데이터로 받아 갖는 것이 아니라 사용처가 자신의 마크업에 직접 작성하므로, 컴포넌트는 집합이 비어서 돌아왔다는 사실을 알 수 없습니다. 선택지가 없는 그룹은 사용처가 렌더링하기 전에 이미 처리한 분기입니다.
+- `loading-state` — 선택지가 아직 도착하지 않은 그룹은 아직 렌더링되지 않은 그룹입니다. 항목이 데이터가 아니라 마크업이므로, 사용처는 모르는데 컴포넌트만 기다리고 있음을 아는 순간은 존재하지 않습니다.
+- `error-state` — 유효하지 않음은 컨트롤의 상태이며, `invalid`로 전달되고 모든 항목의 입력에 aria-invalid로 알려집니다. 무엇이 잘못되었는지 설명하는 문장은 레이블과 설명을 소유하는 주변 필드의 몫입니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> 그룹의 이름은 Label part에서 옵니다. 각 항목의 이름은 aria-labelledby를 통해 자신의 ItemText에서 오므로, ItemText 없이 렌더링된 항목은 이름 없이 보조 기술에 전달됩니다. 이는 조용히 채워지지 않고 감사에서 드러납니다.
+
+### 포커스
+
+> 포커스는 숨겨진 네이티브 라디오에 놓입니다. 이 라디오들은 시각적으로 잘려 있을 뿐 보조 기술에서 숨겨지거나 탭 순서에서 빠지지 않습니다. 로빙 동작은 네이티브 라디오 그룹화가 제공하며, 포커스 링은 보이는 항목에 그려집니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 이 컴포넌트가 이미 다루는 패턴
+
+- **segmented control** — 선택하는 방법: 조합으로 선택합니다. ItemControl 없이 Item과 ItemText를 렌더링하고 Indicator를 포함합니다. 다른 모든 라이브러리가 두 번째 컴포넌트로 내보내는 패턴이 여기서는 같은 machine, 같은 역할, 같은 키보드 동작입니다. 미끄러지는 하이라이트는 machine이 이미 측정하고 위치를 정하는 Indicator part이므로, 이 패턴에는 동작 코드도, prop도, 추가 테스트 범위도 들지 않습니다. `shape`나 `appearance` prop을 두면 첫 번째 컴포넌트의 이름을 빌려 입은 두 번째 컴포넌트가 되며, FORBIDDEN_VARIANT_AXES는 바로 이를 막기 위해 있습니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `single-select`, `segmented-control`, `form-value`, `axis-orientation`, `readonly-display`.
+- 다른 이름: `radio group`, `radio buttons`, `segmented control`, `option group`, `choice list`, `라디오 그룹`, `라디오 버튼`, `세그먼트 컨트롤`, `단일 선택`.
+- 어휘 상태: `controlled`.

package/skills/components/rating-group/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: 'rating-group'
+description: 'RatingGroup — 하나의 라디오 그룹처럼 동작하는 평점 항목의 행으로, 선택적으로 반 단위 값을 지원하며 모양은 사용하는 제품이 제공하는 glyph를 씁니다. 다른 이름: rating, stars, star rating, score, review rating, 별점, 평점, 별점 입력, 평가.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/rating-group.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/rating-group.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# RatingGroup
+
+> 하나의 라디오 그룹처럼 동작하는 평점 항목의 행으로, 선택적으로 반 단위 값을 지원하며 모양은 사용하는 제품이 제공하는 glyph를 씁니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `RatingGroup`
+- 분류: `form-controls`
+- 수명 주기: `active`
+
+## Do
+
+> 각 단계가 그 자체로 의미를 갖는 짧은 순서형 척도의 점수에 쓰세요. 상품 리뷰, 만족도 점수, 난이도가 그런 예입니다. 행이 척도 전체를 한 번에 보여주므로, 사용자는 숫자가 아니라 범위를 기준으로 자신의 답을 판단합니다.
+
+## Don't
+
+> 연속적인 양이나 넓은 범위에는 쓰지 마세요. 항목 다섯 개에서 열 개가 실질적인 한계이며, 그 너머는 모두 Slider가 맡습니다. 선택지에 순서가 없는 선택에도 쓰지 마세요. 화살표 키는 척도를 암시하며, 그렇지 않은 컨트롤은 RadioGroup입니다. 아무도 설정할 수 없는 종합 평점을 보여주는 수단으로 `readOnly`를 쓰지 마세요. 그것은 정적인 표시이며, 상호작용할 수 있어 보이면서 상호작용을 거부하는 컨트롤은 텍스트보다 나쁩니다.
+
+## Anti-patterns
+
+> PinInput의 `index`가 0부터 시작한다는 이유로 이 컴포넌트의 `index`도 0부터 센다고 여기는 것. 이 machine의 항목은 1부터 번호가 매겨지고 `value`는 인덱스와 직접 비교되므로, 항목 1이 첫 번째 별입니다. 두 컴포넌트는 같은 묶음에서 나란히 만들어졌지만, 같은 인자 이름을 서로 다른 뜻으로 씁니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `RadioGroup` (`radio-group`)
+- `Slider` (`slider`)
+- `ToggleGroup` (`toggle-group`)
+
+## 가져오기
+
+```tsx
+import { RatingGroup } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 4개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<RatingGroup.Root>
+  <RatingGroup.Label />
+  <RatingGroup.Control>
+    <RatingGroup.Item />
+  </RatingGroup.Control>
+</RatingGroup.Root>
+```
+
+- `RatingGroup.Root` — 최상위에 놓입니다
+- `RatingGroup.Label` — `Root` 안에 놓입니다
+- `RatingGroup.Item` — `Control` 안에 놓입니다
+- `RatingGroup.Control` — `Root` 안에 놓입니다
+
+### part가 렌더링하고 소유하는 요소
+
+- `hiddenInput`, `RatingGroup.Root`가 렌더링합니다 — 평점을 `name` 아래에 담는 네이티브 필드입니다. 이 machine은 aria-hidden이 아니라 `hidden` 속성으로 이를 숨기므로 탭 순서와 접근성 트리 양쪽에서 모두 빠집니다. 보이는 항목이 실제 컨트롤이고 이것은 통로입니다. Root가 렌더링하며 일부러 part로 두지 않았습니다. 사용처가 이를 옮기거나 빠뜨릴 수 있으면, 보이는 것은 아무것도 깨지지 않은 채 제출이 깨지기 때문입니다.
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 15개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `value` — `number`, 선택. 제어되는 평점. `0`은 평가하지 않음이고, 반값은 `allowHalf`일 때만 허용됩니다.
+- `defaultValue` — `number`, 선택. 비제어 모드의 초기 평점. `value`를 주면 무시됩니다.
+- `onValueChange` — `(details: ValueChangeDetails<number>) => void`, 선택. 제어 여부와 무관하게 평점이 바뀔 때마다 호출됩니다.
+- `onHoverChange` — `(details: RatingHoverChangeDetails) => void`, 선택. 아무것도 확정되기 전에, 포인터가 아이템 위를 지날 때 호출됩니다.
+- `count` — `number`, 선택. 아이템이 몇 개인지. 기본값은 5입니다.
+- `allowHalf` — `boolean`, 선택. 반값을 허용합니다. 포인터가 아이템의 어느 쪽에 있는지로 정해집니다.
+- `autoFocus` — `boolean`, 선택. 마운트될 때 그룹 안으로 포커스를 옮깁니다.
+- `name` — `string`, 선택. 폼 필드 이름. 이 값이 없으면 컨트롤은 아무것도 제출하지 않습니다.
+- `form` — `string`, 선택. 폼 바깥에 렌더된 그룹을 id로 그 폼에 연결합니다.
+- `disabled` — `boolean`, 선택. 비활성화된 RatingGroup은 제출하지도, 반응하지도 않습니다.
+- `readOnly` — `boolean`, 선택. 읽기 전용 RatingGroup은 평점을 보여주되 바꿀 수 없습니다. 표시용으로 쓰는 경우입니다.
+- `required` — `boolean`, 선택. 제약 검증. 폼이 제출되려면 평점이 있어야 합니다.
+- `translations` — `TranslationOverrides`, 선택. 이 RatingGroup에만 적용되는 접근성 문자열로, provider의 값보다 우선합니다.
+- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`.
+
+## 폼
+
+폼 참여: 예.
+
+- `input[type=text]`로 제출합니다.
+- 제출 값은 `value`에서 옵니다.
+- 아무것도 설정하지 않으면 `0`을 제출합니다.
+
+> 숨겨진 통로 하나가 숫자 평점을 `name` 아래에 담습니다. `disabled`이면 제출되지 않으며, `required`는 평점을 반드시 매겨야 함을 뜻합니다. 통로는 aria-hidden이 아니라 `hidden` 속성으로 숨겨지며, 이는 통로 패턴을 표현하는 세 번째 정당한 방식입니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 항목의 수는 무엇이든 선택되기 전에 `count`로 정해지므로 비어서 도착할 수 있는 집합이 없습니다. 평가되지 않은 그룹은 하이라이트되지 않은 항목이 한 줄 가득 있는 상태이며, 이는 부재가 아니라 기본 상태입니다.
+- `loading-state` — 아직 도착하지 않은 종합 평점은 비활성화되었거나 읽기 전용인 RatingGroup에 주변 페이지가 이미 쓰는 스켈레톤을 더한 것입니다. 로딩 part를 두면 비활성화 상태와 중복됩니다.
+- `error-state` — machine은 `invalid` prop을 노출하지 않습니다. 사용자는 존재하는 항목만 고를 수 있으므로 평점은 구조상 언제나 범위 안에 있습니다. 유일한 제약은 `required`이며, 이를 설명하는 메시지는 주변 필드의 몫입니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> 그룹의 이름은 Label part에서 옵니다. 각 항목은 provider의 번역 가능한 세트에서 위치로 이름을 받으므로, glyph가 없는 항목도 올바르게 알려집니다. 영어 기본값이 '{count} stars'가 아니라 '{count} star rating'인 이유는, 그렇지 않으면 모든 그룹의 첫 항목이 '1 stars'로 읽히기 때문입니다.
+
+### 포커스
+
+> 로빙 탭 인덱스를 씁니다. 선택된 항목이 tabIndex 0을, 나머지가 -1을 가지므로 그룹은 정지 지점 하나이고 화살표 키로 그 안을 이동합니다. 읽기 전용 그룹도 평점을 읽을 수 있도록 선택된 항목을 포커스 가능한 상태로 유지합니다.
+
+### Glyph
+
+> 자식 없이 렌더링된 Item은 별을 보여줍니다. 평가 전에는 윤곽선만, 평가 후에는 채워진 모양으로 그려지므로 평점을 색만이 아니라 모양으로도 읽을 수 있습니다. 사용처의 자식이 이를 대체하며, 레시피는 여전히 하이라이트 상태에 따라 자식에 색을 입히고, 이름은 glyph가 아니라 항목에 남습니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `rating`, `fractional-rating`, `form-value`, `readonly-display`, `translatable-strings`.
+- 다른 이름: `rating`, `stars`, `star rating`, `score`, `review rating`, `별점`, `평점`, `별점 입력`, `평가`.
+- 어휘 상태: `controlled`.