@mindlogic-ai/logician-ui 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/components/Typography/Typography.usage.mdx

@@ -0,0 +1,257 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TypographyStories from './Typography.stories';
+
+<Meta of={TypographyStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Typography
+
+The type scale: headings (`H1`–`H5`), body text (`Text`), supporting text
+(`Subtitle`, `Subtext`, `Caption`, `Overline`) and inline links (`Link`).
+Each tier sets a size and a colour. Word breaking is set by language on
+`<html>` in the global styles: Korean (`lang="ko"`) gets `keep-all`, Japanese
+(`lang="ja"`) gets `auto-phrase` where supported, other languages keep the
+browser default.
+
+## When to use
+
+- `H1`–`H5` for headings that belong in the page outline: a page title, a
+  section, a card or modal title.
+- `Text` for body copy. `Subtext` for the secondary line under a title or
+  value. `Caption` for metadata (time, count, length). `Overline` for a short
+  uppercase eyebrow above a heading.
+- `Link` for navigation inside a sentence.
+
+## When not to use
+
+- An action that changes something (save, delete, open a modal) → `Button`
+  (`variant="ghost"` if it has to look light). A link goes somewhere.
+- A status label next to a title → `Badge`.
+- Code inside a sentence → `InlineCode`. Formatted content from a model or an
+  author → `Markdown`, which maps to these same components.
+
+## The scale and what each tier means
+
+| Component | Renders | Default colour | Use for |
+| --- | --- | --- | --- |
+| `H1`–`H5` | `<h1>`–`<h5>` | `fg.emphasized` | Headings in the outline |
+| `Text` | `<p>` | `fg.default` | Body copy |
+| `Subtitle` | `<p>` | `fg.muted` | Helper copy under a heading |
+| `Subtext` | `<p>` | `fg.default` | A step smaller than body: secondary lines, dense lists |
+| `Caption` | `<p>` | `fg.subtle` | Timestamps, counts, file sizes |
+| `Overline` | `<p>` | `fg.muted` | Uppercase eyebrow above a heading |
+| `Link` | `<a>` | `fg.link` (`variant="error"`: `danger.fg`) | Inline navigation |
+
+**Size and level are separate choices.** Every component takes `as`, and the
+props of that element come with it. Pick the size for the layout, then set
+the level the outline needs: `<H3 as="h2">`. `Subtitle` used to render
+`<h6>`; it is a paragraph now, and says `as="h2"` only where it really is the
+next heading. Passing `fontSize` turns off the tier's `textStyle`, so an
+explicit size wins.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Typography
+
+글자 체계입니다. 제목(`H1`–`H5`), 본문(`Text`), 보조 문구(`Subtitle`, `Subtext`,
+`Caption`, `Overline`), 문장 안 링크(`Link`)로 나뉩니다. 각 단계는 크기와 색을
+정합니다. 줄바꿈 방식은 전역 스타일이 `<html>`의 언어로 정합니다. 한국어
+(`lang="ko"`)는 단어 중간에서 끊기지 않도록 `keep-all`, 일본어(`lang="ja"`)는
+지원 브라우저에서 문절 단위로 끊는 `auto-phrase`이고, 다른 언어는 브라우저
+기본값을 씁니다.
+
+## 언제 쓰나요
+
+- 페이지 구조에 들어가는 제목에는 `H1`–`H5`를 씁니다. 페이지 제목, 섹션, 카드나
+  모달의 제목이 여기에 해당합니다.
+- 본문은 `Text`, 제목이나 값 아래의 보조 줄은 `Subtext`, 시간·개수·길이 같은
+  메타데이터는 `Caption`, 제목 위의 짧은 대문자 머리말은 `Overline`을 씁니다.
+- 문장 안에서 다른 곳으로 이동할 때는 `Link`를 씁니다.
+
+## 언제 쓰지 않나요
+
+- 무언가를 바꾸는 동작(저장, 삭제, 모달 열기)에는 `Button`을 씁니다. 가벼워 보여야
+  한다면 `variant="ghost"`를 씁니다. 링크는 어딘가로 이동할 때만 씁니다.
+- 제목 옆의 상태 라벨은 `Badge`를 씁니다.
+- 문장 안의 코드는 `InlineCode`를 씁니다. 모델이나 작성자가 쓴 서식 있는 글은
+  `Markdown`을 쓰면 같은 컴포넌트로 그려집니다.
+
+## 단계와 뜻
+
+| 컴포넌트 | 그리는 요소 | 기본 색 | 쓰는 곳 |
+| --- | --- | --- | --- |
+| `H1`–`H5` | `<h1>`–`<h5>` | `fg.emphasized` | 문서 구조 안의 제목 |
+| `Text` | `<p>` | `fg.default` | 본문 |
+| `Subtitle` | `<p>` | `fg.muted` | 제목 아래의 도움말 |
+| `Subtext` | `<p>` | `fg.default` | 본문보다 한 단계 작은 글: 보조 줄, 촘촘한 목록 |
+| `Caption` | `<p>` | `fg.subtle` | 시각, 개수, 파일 크기 |
+| `Overline` | `<p>` | `fg.muted` | 제목 위의 대문자 머리말 |
+| `Link` | `<a>` | `fg.link` (`variant="error"`이면 `danger.fg`) | 문장 안의 이동 |
+
+**크기와 제목 수준은 따로 고릅니다.** 모든 컴포넌트가 `as`를 받고, 그 요소의
+속성도 함께 받습니다. 크기는 레이아웃에 맞춰 고르고, 수준은 문서 구조에 맞춰
+`<H3 as="h2">`처럼 정합니다. `Subtitle`은 예전에 `<h6>`로 그려졌지만 지금은
+문단이며, 정말 다음 수준의 제목일 때만 `as="h2"`를 붙입니다. `fontSize`를 넘기면
+그 단계의 `textStyle`이 꺼지고 지정한 크기가 적용됩니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TypographyStories.DoLevelFromOutline} />
+<Verdict
+  kind="do"
+  en="Choose H3 for its size and render it as h2 because it is the first heading under the page title."
+  ko="크기 때문에 H3를 고르고, 페이지 제목 바로 아래의 첫 제목이므로 h2로 그립니다."
+/>
+
+<Canvas of={TypographyStories.DontSubtitleAsHeading} />
+<Verdict
+  kind="dont"
+  en="Give helper copy a heading tag. A screen reader lists it as a heading, and the outline jumps from h2 to h6."
+  ko="도움말 문구에 제목 태그를 주지 마세요. 화면 낭독기가 제목 목록에 넣고, 문서 구조가 h2에서 h6로 건너뜁니다."
+/>
+
+<Canvas of={TypographyStories.DoLinkSaysWhere} />
+<Verdict
+  kind="do"
+  en="Write link text that names where it goes, so it makes sense when read on its own."
+  ko="링크 문구에는 이동할 곳을 적어서, 링크만 따로 읽어도 뜻이 통하게 합니다."
+/>
+
+<Canvas of={TypographyStories.DontLinkHere} />
+<Verdict
+  kind="dont"
+  en="Use “여기” as the link text, or remove the underline. A link list full of “여기” tells nobody anything, and without the underline only colour marks the link."
+  ko="'여기'를 링크 문구로 쓰거나 밑줄을 없애지 마세요. '여기'만 늘어선 링크 목록은 아무것도 알려 주지 못하고, 밑줄이 없으면 색만으로 링크를 구분해야 합니다."
+/>
+
+<Canvas of={TypographyStories.DoCaptionForMetadata} />
+<Verdict
+  kind="do"
+  en="Keep Caption for metadata the reader can skip."
+  ko="Caption은 읽지 않고 넘어가도 되는 메타데이터에만 씁니다."
+/>
+
+<Canvas of={TypographyStories.DontCaptionForErrors} />
+<Verdict
+  kind="dont"
+  en="Put something the user must act on in Caption. It is the faintest tier; use Text, or a Banner for a real error."
+  ko="사용자가 조치해야 하는 내용을 Caption에 넣지 마세요. 가장 흐린 단계이므로 Text를 쓰고, 실제 오류라면 Banner를 씁니다."
+/>
+
+<En>
+
+## Content
+
+- Headings in sentence case, no full stop. Keep them short enough for one
+  line on mobile.
+- Do not set long body copy in `Subtext` or `Caption` to make it fit. Cut
+  the copy instead.
+- Link text is the destination or the thing you get: 요금제 비교 보기, not
+  여기 or 자세히.
+
+## Accessibility
+
+What the components do for you:
+
+- `H1`–`H5` render real heading elements, and the body tiers render
+  paragraphs, so the outline only contains what you mark as a heading.
+- `Link` is underlined (1px, 2px on hover) and medium weight, so it does not
+  rely on colour alone (WCAG 1.4.1). `fg.link` and `fg.linkHover` are tuned
+  against the canvas in both modes (WCAG 1.4.3).
+- The markdown `h6` keeps `as="h6"`, because a heading the author wrote must
+  stay in the outline.
+
+What you still have to do:
+
+- **Keep the heading levels in order** (WCAG 1.3.1, 2.4.6; KWCAG 5.2.4.2 제목
+  제공). Use `as` to fix the level, never a smaller component to fix the size.
+- **Do not remove the link underline** in running text (WCAG 1.4.1).
+- **Name the destination** in the link text (WCAG 2.4.4). If a link opens a
+  new tab, say so in the text or with a visually hidden note.
+- The error link keeps `danger.fg` on hover; only the underline thickens.
+- An action is a `<button>`, not a link with an `onClick` (WCAG 4.1.2).
+  `<Link as="button">` is fine when it must look like a link.
+
+## Tokens
+
+Default colour of each tier, and the link states from `LINK_RAMP` in
+`Link.tsx`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 제목은 문장형 대소문자로 쓰고 마침표를 찍지 않습니다. 모바일에서 한 줄에 들어갈
+  만큼 짧게 씁니다.
+- 긴 본문을 화면에 맞추려고 `Subtext`나 `Caption`으로 줄이지 않습니다. 문구를
+  줄입니다.
+- 링크 문구에는 이동할 곳이나 얻을 것을 씁니다. '여기', '자세히'가 아니라 '요금제
+  비교 보기'처럼 씁니다.
+
+## 접근성
+
+컴포넌트가 알아서 하는 일
+
+- `H1`–`H5`는 실제 제목 요소로, 본문 단계는 문단으로 그려집니다. 그래서 제목으로
+  지정한 것만 문서 구조에 들어갑니다.
+- `Link`는 밑줄(평소 1px, 마우스를 올리면 2px)과 중간 굵기를 가지므로 색에만
+  기대지 않습니다(WCAG 1.4.1). `fg.link`와 `fg.linkHover`는 두 모드 모두에서 바탕과
+  대비가 맞도록 정해져 있습니다(WCAG 1.4.3).
+- 마크다운의 `h6`는 `as="h6"`를 유지합니다. 작성자가 쓴 제목은 문서 구조에 남아야
+  하기 때문입니다.
+
+직접 챙겨야 하는 일
+
+- **제목 수준을 차례대로 씁니다**(WCAG 1.3.1, 2.4.6, KWCAG 5.2.4.2 제목 제공).
+  수준은 `as`로 맞추고, 크기를 맞추려고 더 작은 컴포넌트를 고르지 않습니다.
+- 본문 안 링크의 **밑줄을 없애지 않습니다**(WCAG 1.4.1).
+- 링크 문구에 **이동할 곳을 적습니다**(WCAG 2.4.4). 새 탭에서 열린다면 문구나
+  시각적으로 숨긴 안내로 알립니다.
+- 오류 링크는 마우스를 올려도 `danger.fg`를 유지하고 밑줄만 굵어집니다.
+- 동작은 `onClick`을 단 링크가 아니라 `<button>`으로 만듭니다(WCAG 4.1.2). 링크처럼
+  보여야 한다면 `<Link as="button">`을 씁니다.
+
+## 토큰
+
+각 단계의 기본 색과 `Link.tsx`의 `LINK_RAMP`에 있는 링크 상태입니다.
+
+</Ko>
+
+<Canvas of={TypographyStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Markdown**: renders authored or generated text with these components.
+- **InlineCode**: code inside a sentence.
+- **ExpandableText**: body text clipped to a few lines.
+- **Badge**: a status label next to a heading.
+- **Foundations/Brand & colour usage**: which `fg.*` role to use where.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Markdown**: 작성하거나 생성한 글을 이 컴포넌트들로 그립니다.
+- **InlineCode**: 문장 안의 코드.
+- **ExpandableText**: 몇 줄만 보여 주고 접어 두는 본문.
+- **Badge**: 제목 옆의 상태 라벨.
+- **Foundations/Brand & colour usage**: 어느 자리에 어떤 `fg.*` 역할을 쓰는지.
+
+</Ko>

package/src/components/Workflow/Workflow.usage.mdx

@@ -0,0 +1,199 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as WorkflowStories from './stories/Workflow.stories';
+
+<Meta of={WorkflowStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Workflow
+
+A node-based workflow editor on React Flow: a drag-and-drop palette, a
+canvas with undo/redo, auto-arrange and selection, and an optional inspector
+drawer. It ships **no node types**: you register yours with
+`defineNodeType`, and you own persistence and validation. FactChat's studio
+behaviour editor is built on it. Full API: `Workflow/README.md`.
+
+## When to use
+
+- Users build or read a graph of steps with branches: triggers, AI steps,
+  conditions, outputs.
+- A read-only picture of a saved flow (`readOnly`, `showPalette={false}`,
+  `minHeight={0}`).
+
+## When not to use
+
+- A fixed, linear sequence of steps → a numbered list or a stepper.
+- A hierarchy → `Tree`.
+- A settings form that happens to have sections → `Accordion` or `Card`s.
+
+## Options that change behaviour
+
+| Prop / part | Means |
+| --- | --- |
+| `nodeTypes` | Required. Your node kinds; `category` (`trigger`, `ai`, `logic`, `safety`, `output`, `note`) drives the tile colour |
+| `graph` + `onGraphChange`, or `defaultGraph` | Controlled or uncontrolled graph |
+| `<NodeInspector />` child | Built-in drawer on selection (`dock="left" \| "right"`); omit it and use `onSelectionChange` to drive your own panel |
+| `issues` / `validating` | Render-only validation you supply; the editor does not validate |
+| `readOnly` | No palette, no connecting, dragging or deleting; the inspector becomes a read-only view |
+| `translate` | Chrome copy. Without it the bundled strings resolve to Korean |
+| `useWorkflowActions().addNode` | Add nodes without dragging (a "+" toolbar, a tap-to-add list) |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Workflow
+
+React Flow 위에 만든 노드 기반 워크플로 편집기입니다. 끌어다 놓는 팔레트, 실행 취소·
+다시 실행, 자동 정렬, 선택이 되는 캔버스, 그리고 선택해서 켜는 속성 서랍이 있습니다.
+**노드 종류는 하나도 들어 있지 않습니다.** `defineNodeType`으로 직접 등록하고, 저장과
+검증도 앱이 맡습니다. FactChat 스튜디오의 동작 편집기가 이것으로 만들어졌습니다. 전체
+API는 `Workflow/README.md`에 있습니다.
+
+## 언제 쓰나요
+
+- 사용자가 갈래가 있는 단계 그래프(트리거, AI 단계, 조건, 출력)를 만들거나 읽을 때.
+- 저장된 흐름을 읽기 전용 그림으로 보여 줄 때(`readOnly`, `showPalette={false}`,
+  `minHeight={0}`).
+
+## 언제 쓰지 않나요
+
+- 갈래 없이 정해진 순서의 단계라면 번호 목록이나 단계 표시를 씁니다.
+- 계층이라면 `Tree`를 씁니다.
+- 섹션이 있는 설정 폼이라면 `Accordion`이나 `Card`를 씁니다.
+
+## 동작을 바꾸는 옵션
+
+| 속성 / 파트 | 뜻 |
+| --- | --- |
+| `nodeTypes` | 필수. 노드 종류. `category`(`trigger`, `ai`, `logic`, `safety`, `output`, `note`)가 타일 색을 정합니다 |
+| `graph` + `onGraphChange`, 또는 `defaultGraph` | 제어 그래프 또는 비제어 그래프 |
+| 자식 `<NodeInspector />` | 선택하면 열리는 기본 서랍(`dock="left" \| "right"`). 빼고 `onSelectionChange`로 직접 만든 패널을 움직일 수도 있습니다 |
+| `issues` / `validating` | 앱이 넘기는 검증 결과를 그리기만 합니다. 편집기가 검증하지 않습니다 |
+| `readOnly` | 팔레트를 숨기고 연결·이동·삭제를 막습니다. 서랍은 읽기 전용 보기가 됩니다 |
+| `translate` | 화면 문구 번역 함수. 넘기지 않으면 내장 문구가 한국어로 나옵니다 |
+| `useWorkflowActions().addNode` | 끌지 않고 노드를 추가합니다("+" 도구 모음, 눌러서 추가하는 목록) |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={WorkflowStories.AddNodeWithoutDrag} />
+<Verdict
+  kind="do"
+  en="Offer a way to add nodes without dragging: a + beside the selected node or a list of node types, built on useWorkflowActions().addNode."
+  ko="끌지 않고도 노드를 추가할 방법을 줍니다. useWorkflowActions().addNode로 선택한 노드 옆의 +나 노드 종류 목록을 만듭니다."
+/>
+
+<Canvas of={WorkflowStories.ReadOnly} />
+<Verdict
+  kind="do"
+  en="Use readOnly for a saved flow the user can look at but not change."
+  ko="사용자가 보기만 하고 바꾸지 않는 저장된 흐름에는 readOnly를 씁니다."
+/>
+
+<Verdict
+  kind="dont"
+  en="Validate inside the editor or rely on canvas colour alone for errors. Pass issues with a message; they appear on the node and in the drawer as text."
+  ko="편집기 안에서 검증하거나 캔버스 색만으로 오류를 알리지 마세요. 메시지가 있는 issues를 넘기면 노드와 서랍에 글로 나타납니다."
+/>
+
+<En>
+
+## Content
+
+- Node `label`s are short operational nouns (Message, Condition). The README
+  keeps them untranslated on purpose.
+- `getMetaChips` shows a few words of config on the card; keep chips short.
+- Issue `message`s say what to fix: "연결되지 않은 출구가 있습니다", not "오류".
+
+## Accessibility
+
+What Workflow does for you:
+
+- Canvas controls (zoom, fit, undo, redo, lock, auto-arrange) are buttons
+  with translated names; the palette is a labelled region with a named close
+  button (WCAG 4.1.2).
+- Keyboard shortcuts: ⌘/Ctrl+Z and +Y (undo, redo), +C/+V (copy, paste),
+  +D (duplicate), Delete/Backspace (remove the selected node or edge), Escape
+  (close the inspector). They stay out of the way while typing in a field.
+
+What you still have to do:
+
+- **Give a non-drag way to add nodes** (WCAG 2.5.7): the palette is
+  drag-and-drop. Use `useWorkflowActions().addNode`, as in the Do example.
+- **Pass `translate`** for any non-Korean app, or the chrome is announced in
+  Korean.
+- Moving nodes and drawing connections are pointer gestures in React Flow;
+  the graph is hard to edit by keyboard alone. Keep the inspector the place
+  where every setting can be changed by keyboard (WCAG 2.1.1).
+
+## Tokens
+
+Node tiles take their colour from `category`; override the mapping with
+`categoryTokens`. See `Workflow/README.md`, "Theming, layout & read-only".
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 노드 `label`은 짧은 동작 명사(Message, Condition)로 씁니다. README는 일부러 번역하지
+  않습니다.
+- `getMetaChips`는 카드에 설정값 몇 단어를 보여 줍니다. 칩은 짧게 씁니다.
+- issue의 `message`에는 고칠 내용을 씁니다. '오류'가 아니라 '연결되지 않은 출구가
+  있습니다'처럼 씁니다.
+
+## 접근성
+
+Workflow가 알아서 하는 일
+
+- 캔버스 컨트롤(확대, 축소, 화면 맞춤, 실행 취소, 다시 실행, 잠금, 자동 정렬)은 번역된
+  이름이 있는 버튼이고, 팔레트는 이름이 있는 영역이며 닫기 버튼에도 이름이 있습니다
+  (WCAG 4.1.2).
+- 단축키: ⌘/Ctrl+Z와 +Y(실행 취소, 다시 실행), +C/+V(복사, 붙여넣기), +D(복제),
+  Delete/Backspace(선택한 노드나 연결 삭제), Escape(서랍 닫기). 입력 칸에 글을 쓰는
+  동안에는 동작하지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **끌지 않고 노드를 추가하는 방법을 줍니다**(WCAG 2.5.7). 팔레트는 끌어다 놓는
+  방식입니다. 이렇게 하세요 예시처럼 `useWorkflowActions().addNode`를 씁니다.
+- 한국어가 아닌 앱이라면 **`translate`를 넘깁니다.** 넘기지 않으면 화면 문구가 한국어로
+  읽힙니다.
+- 노드 이동과 연결 그리기는 React Flow의 포인터 동작이라 키보드만으로 그래프를 고치기
+  어렵습니다. 모든 설정은 서랍에서 키보드로 바꿀 수 있게 합니다(WCAG 2.1.1).
+
+## 토큰
+
+노드 타일 색은 `category`에서 오며, `categoryTokens`로 바꿀 수 있습니다.
+`Workflow/README.md`의 "Theming, layout & read-only"를 봅니다.
+
+</Ko>
+
+<En>
+
+## Related
+
+- **Tree**: a hierarchy rather than a graph.
+- **Banner**: graph-wide issues above the canvas.
+- `Workflow/README.md`: node types, the inspector, selection, `hostBridge`.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tree**: 그래프가 아니라 계층일 때.
+- **Banner**: 캔버스 위의 그래프 전체 문제.
+- `Workflow/README.md`: 노드 종류, 서랍, 선택, `hostBridge`.
+
+</Ko>

package/src/components/a11y.kwcag.test.tsx

@@ -6,6 +6,7 @@ import { buttonVariantStyles } from '@/components/Button/Button.styles';
 import { FileInput } from '@/components/FileInput';
 import { LogicianProvider } from '@/components/LogicianProvider';
 import { baseMarkdownComponents } from '@/components/Markdown/Markdown';
+import { NavList } from '@/components/NavList';
 import { Radio, RadioGroup } from '@/components/Radio';
 import { SelectField } from '@/components/Select';
 import {
@@ -292,6 +293,71 @@ describe('axe — 구조·ARIA 규칙', () => {
       </RadioGroup>,
     ],
     ['파일 입력', <FileInput key="file" onChange={() => {}} />],
+    [
+      // Rows are links or buttons with aria-current — never tabs — and the
+      // trailing action sits beside its row, not inside it (nested-interactive).
+      '내비게이션 목록',
+      <NavList key="navlist" aria-label="소스">
+        <NavList.Item href="/recent" isCurrent trailingVisual="3">
+          최근
+        </NavList.Item>
+        <NavList.Item href="/off" isDisabled>
+          사용 불가
+        </NavList.Item>
+        <NavList.Group title="공유 드라이브">
+          <NavList.Item
+            onClick={() => {}}
+            trailingAction={
+              <button type="button" aria-label="마케팅 옵션">
+                …
+              </button>
+            }
+          >
+            마케팅
+          </NavList.Item>
+          <NavList.Item onClick={() => {}} isDisabled>
+            보관됨
+          </NavList.Item>
+        </NavList.Group>
+      </NavList>,
+    ],
+    [
+      // Icon-only rows keep their label as the name; a new-window link says
+      // so in its name; a collapsible group is a disclosure with its list
+      // still labelled; a hover-revealed action is still in the tree.
+      '접힌 내비게이션 레일과 새 창 링크',
+      <NavList key="navlist-collapsed" aria-label="관리자 메뉴" isCollapsed>
+        <NavList.Item href="/a" isCurrent leadingVisual={<svg />}>
+          멤버 관리
+        </NavList.Item>
+        <NavList.Item
+          href="https://docs.example"
+          target="_blank"
+          leadingVisual={<svg />}
+        >
+          사용 가이드
+        </NavList.Item>
+      </NavList>,
+    ],
+    [
+      '접을 수 있는 내비게이션 묶음',
+      <NavList key="navlist-collapsible" aria-label="설정">
+        <NavList.Group title="결제" isCollapsible>
+          <NavList.Item
+            href="/b"
+            tooltip="요금제와 결제 수단"
+            trailingActionVisibility="hover"
+            trailingAction={
+              <button type="button" aria-label="요금제 옵션">
+                …
+              </button>
+            }
+          >
+            요금제
+          </NavList.Item>
+        </NavList.Group>
+      </NavList>,
+    ],
   ])('%s', async (_name, ui) => {
     const { container } = withProvider(ui);
     expect(await axeViolations(container)).toEqual([]);
@@ -393,27 +459,18 @@ describe('브랜드 색 대비 — Link · Tab 램프', () => {
     expect(hover).toBeGreaterThan(resting);
   });
 
-  // KNOWN (5.0 open question, needs designer sign-off): the BAZE guide's dark
-  // `fg.linkHover` #8BB7E3 is 6.52:1 on bg.surface against the resting link's
-  // 7.89:1 — the hover moves TOWARD the background. Both still clear 4.5:1 and
-  // the underline thickens 1px → 2px, so the hover cue survives, but this is
-  // the exact inversion this file was written to stop. `it.fails` keeps the
-  // invariant on record: when the value is fixed this starts passing and fails
-  // the suite, so flip it back to `it`.
-  it.fails(
-    'hover 가 배경 반대쪽으로 간다 — 다크 (BAZE 가이드 값 확인 필요)',
-    () => {
-      const resting = contrast(
-        resolve(LINK_RAMP.default, '_dark'),
-        DARK_CANVAS
-      );
-      const hover = contrast(
-        resolve(LINK_RAMP.defaultHover, '_dark'),
-        DARK_CANVAS
-      );
-      expect(hover).toBeGreaterThan(resting);
-    }
-  );
+  // The BAZE guide's dark `fg.linkHover` #8BB7E3 went TOWARD the background
+  // (6.52:1 on bg.surface against the resting link's 7.89:1) and sat here as
+  // `it.fails`. Fixed by making the dark hover lighter than the resting link
+  // (#C5DEF8, 10.66:1 on bg.surface).
+  it('hover 가 배경 반대쪽으로 간다 — 다크', () => {
+    const resting = contrast(resolve(LINK_RAMP.default, '_dark'), DARK_CANVAS);
+    const hover = contrast(
+      resolve(LINK_RAMP.defaultHover, '_dark'),
+      DARK_CANVAS
+    );
+    expect(hover).toBeGreaterThan(resting);
+  });
 
   it('선택된 가로 탭의 레이블이 라이트·다크 양쪽에서 4.5:1 을 넘는다', () => {
     // Measured against the RAISED surface (bg.surface), not the page canvas:

package/src/components/claude.md

@@ -249,6 +249,29 @@ const createSyntheticEvent = (
 };
 ```
 
+## Control sizes
+
+Every control that takes `size` resolves it through **one** table,
+`controlSizes` in `src/theme/controlSizes.ts` — height token, textStyle, icon
+size, inline padding (action vs field ramp) and `CONTROL_RADIUS`. `Button` is
+the reference. Recipe-driven controls get it from `src/theme/recipes/controls.ts`;
+components with their own maps (SegmentedControl, interactive Tag, the date
+pickers, MonthPicker) call `getControlSize(size)`.
+
+- Never add a per-component height / font-size map. Read the scale.
+- Control type must be the textStyle of the size, not a fixed `fontSize`:
+  inside a `ScaledContext` the sizes tokens are em and resolve against the
+  control's own type, so a different type means a different height.
+- Overriding a Chakra **slot** recipe: pass the full anatomy
+  (`selectAnatomy.keys()` from `@chakra-ui/react/anatomy`), never a partial
+  `slots` list — Chakra merges arrays by index and drops slots.
+- Keep `size` responsive (`ConditionalValue<…>`) where Chakra allowed it, and
+  resolve the scale per breakpoint — never collapse an object/array to `md`.
+  A composed sub-part with its own recipe type (e.g. `TagLabel` in an
+  interactive Tag) must inherit the control's type, not keep the badge's.
+- `src/theme/controlSizes.test.ts` fails if a control stops resolving to the
+  scale; the Storybook page **Foundations / Control sizes** measures it live.
+
 ## Component Props Best Practices
 
 ### Default Values
@@ -348,7 +371,7 @@ When adding to `src/index.ts`, follow these categories:
 
 - **Core Components**: Button, Card, Badge, Tag
 - **Form Components**: Input, Select, Checkbox, Radio
-- **Navigation**: Breadcrumb, Pagination, Menu, Tabs
+- **Navigation**: Breadcrumb, Pagination, Menu, Tabs, NavList
 - **Feedback**: Alert, Toast, Modal, Tooltip
 - **Data Display**: Table, Avatar, Typography, Code
 - **File Components**: FileInput, FileItem, FileList

package/src/components/noRawScales.test.ts

@@ -4,7 +4,7 @@ import { join, relative } from 'node:path';
 import { describe, expect, it } from 'vitest';
 
 import { SYSTEM_HUE_NAMES } from '@/theme/colors';
-import { CORAL } from '@/theme/palette.generated';
+import { CORAL, DATAVIZ } from '@/theme/palette.generated';
 
 /**
  * Components read ROLE tokens (`bg.*`, `fg.*`, `primary.*`, `category.*` …),
@@ -64,6 +64,7 @@ const TOKEN = new RegExp(
   `(?<![\\w.$-])(?:` +
     `(?:${alt(numeric)})\\.\\d+` +
     `|coral\\.(?:${alt(Object.keys(CORAL))})` +
+    `|dataviz\\.(?:${alt(Object.keys(DATAVIZ))})` +
     `|(?:${alt(SYSTEM_HUE_NAMES)})\\.(?:${alt(HUE_KEYS)})` +
     `)(?![\\w.])`,
   'g'
@@ -124,6 +125,7 @@ describe('components read no raw palette scales', () => {
       "'ink.12'",
       "'sandDark.3'",
       "'coral.base'",
+      "'dataviz.blueMid'",
       "'red.surface'",
       "'blue.hc'",
       "'blackAlpha.600'",
@@ -135,6 +137,8 @@ describe('components read no raw palette scales', () => {
       "'category.green.surface'",
       "'green'",
       "'fg.default'",
+      "'data.4'",
+      "'diverging.pos.3'",
       'theme.colors.gray.100',
       "'--chakra-colors-gray-100'",
       "'secondary.surface'",