@reopt-ai/opt-ui 1.5.0 → 1.6.0

package/COMPONENT_CATALOG.md

@@ -2,7 +2,7 @@
 
 <!-- DEPRECATED: Prefer dist/docs/02-components/ for per-layer reference. -->
 <!-- Auto-generated from ComponentMeta. Do not edit. -->
-<!-- Version: 1.4.1 -->
+<!-- Version: 1.6.0 -->
 
 ## Quick Stats
 
@@ -184,7 +184,7 @@
 | Toggle        | 눌림(pressed) 두 상태 버튼. 단독 사용하거나 ToggleGroup으로 묶어 단일/다중 선택을 만든다.                                                                | `Toggle`, `ToggleGroup`                                                                                                                         |
 | Accordion     | 수직으로 쌓인 펼침/접힘 패널. single(한 개)/multiple(여러 개) 모드와 collapsible 지원.                                                                   | `AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`                                                                        |
 | Meter         | 범위 내 스칼라 측정값 게이지 (디스크 사용량·점수·용량 등). role=meter로 작업 진행률(Progress)과 구분된다.                                                | `Meter`                                                                                                                                         |
-| BlockLayout   | Block 루트 레이아웃. flex + 기본 section spacing 적용, loading prop으로 LoadingOverlay 자동 래핑.                                                        | `BlockLayout`                                                                                                                                   |
+| BlockLayout   | Block 루트 레이아웃. 자식 간 section spacing과 선택적 시맨틱 inset을 제공하고 loading prop으로 LoadingOverlay를 자동 래핑합니다.                         | `BlockLayout`                                                                                                                                   |
 | createBlock   | Block 팩토리 함수. BlockLayout 래핑을 구조적으로 강제하여 loading/className 처리를 자동화합니다.                                                         | `createBlock`                                                                                                                                   |
 | StarRating    | 1~N점 별점을 선택하는 인터랙티브 레이팅 입력. 읽기 전용 표시도 지원.                                                                                     | `StarRating`                                                                                                                                    |
 | ErrorBoundary | React 에러 바운더리. 자식 컴포넌트 렌더 에러를 잡아 fallback UI를 표시합니다.                                                                            | `ErrorBoundary`                                                                                                                                 |
@@ -373,9 +373,11 @@
 
 **Import:** `import { Kbd } from "@reopt-ai/opt-ui"`
 
-| Prop       | Type        | Required | Default | Description          |
-| ---------- | ----------- | -------- | ------- | -------------------- |
-| `children` | `ReactNode` | Yes      |         | 표시할 단축키 텍스트 |
+| Prop        | Type        | Required | Default | Description                                                                     |
+| ----------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------- |
+| `children`  | `ReactNode` | Yes      |         | 표시할 단축키 텍스트                                                            |
+| `hint`      | `boolean`   |          |         | 인라인 힌트 배지로 표시. `data-shortcut-hints="hidden"`일 때 숨겨진다 (app.css) |
+| `className` | `string`    |          |         | 기본 스타일 오버라이드                                                          |
 
 #### Separator
 
@@ -542,26 +544,31 @@
 
 **TabsRoot:**
 
-| Prop                | Type                           | Required | Default | Description               |
-| ------------------- | ------------------------------ | -------- | ------- | ------------------------- |
-| `defaultSelectedId` | `string`                       |          |         | 초기 선택된 탭 ID         |
-| `selectedId`        | `string \| null`               |          |         | 제어 모드: 선택된 탭 ID   |
-| `setSelectedId`     | `(id: string \| null) => void` |          |         | 제어 모드: 탭 변경 핸들러 |
+| Prop                | Type                           | Required | Default | Description                                                                            |
+| ------------------- | ------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `variant`           | `"underline" \| "workspace"`   |          |         | 탭 프레임 형태. workspace는 편집기 탭(문서/쿼리처럼 열고 닫히며 상태를 갖는 작업 단위) |
+| `defaultSelectedId` | `string`                       |          |         | 초기 선택된 탭 ID                                                                      |
+| `selectedId`        | `string \| null`               |          |         | 제어 모드: 선택된 탭 ID                                                                |
+| `setSelectedId`     | `(id: string \| null) => void` |          |         | 제어 모드: 탭 변경 핸들러                                                              |
 
 **TabList:**
 
-| Prop        | Type        | Required | Default | Description            |
-| ----------- | ----------- | -------- | ------- | ---------------------- |
-| `children`  | `ReactNode` | Yes      |         | Tab 요소들             |
-| `className` | `string`    |          |         | 기본 스타일 오버라이드 |
+| Prop        | Type        | Required | Default | Description                                                                            |
+| ----------- | ----------- | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `children`  | `ReactNode` | Yes      |         | Tab 요소들                                                                             |
+| `actions`   | `ReactNode` |          |         | 탭 줄 오른쪽 액션 영역 (새 탭, 닫기 등). tablist 바깥에 렌더돼 탭 순회에 끼어들지 않음 |
+| `className` | `string`    |          |         | 기본 스타일 오버라이드                                                                 |
 
 **Tab:**
 
-| Prop        | Type        | Required | Default | Description                          |
-| ----------- | ----------- | -------- | ------- | ------------------------------------ |
-| `id`        | `string`    | Yes      |         | 탭 고유 ID (TabPanel의 tabId와 매칭) |
-| `children`  | `ReactNode` | Yes      |         | 탭 레이블                            |
-| `className` | `string`    |          |         | 기본 스타일 오버라이드               |
+| Prop          | Type                   | Required | Default | Description                                       |
+| ------------- | ---------------------- | -------- | ------- | ------------------------------------------------- |
+| `id`          | `string`               | Yes      |         | 탭 고유 ID (TabPanel의 tabId와 매칭)              |
+| `children`    | `ReactNode`            | Yes      |         | 탭 레이블                                         |
+| `icon`        | `ReactNode`            |          |         | 탭 이름 앞 아이콘. 활성 탭에서 accent 색으로 전환 |
+| `status`      | `"dirty" \| "running"` |          |         | 저장되지 않은 변경 / 실행 중 인디케이터           |
+| `statusLabel` | `string`               |          |         | status 인디케이터의 접근성 레이블                 |
+| `className`   | `string`               |          |         | 기본 스타일 오버라이드                            |
 
 **TabPanel:**
 
@@ -1877,13 +1884,14 @@ import {
 
 **Import:** `import { BlockLayout } from "@reopt-ai/opt-ui"`
 
-| Prop           | Type                                          | Required | Default   | Description                                                                          |
-| -------------- | --------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------ |
-| `children`     | `ReactNode`                                   | Yes      |           | Block 콘텐츠                                                                         |
-| `loading`      | `boolean`                                     |          |           | 로딩 상태. 설정 시 LoadingOverlay로 자동 래핑                                        |
-| `loadingLabel` | `string`                                      |          |           | LoadingOverlay 접근성 레이블                                                         |
-| `spacing`      | `"section" \| "group" \| "element" \| "none"` |          | "section" | Block 최상위 자식 사이 간격. 데이터 밀도가 높은 Block는 group/element로 낮출 수 있음 |
-| `className`    | `string`                                      |          |           | 기본 스타일 오버라이드                                                               |
+| Prop           | Type                                          | Required | Default   | Description                                                                                          |
+| -------------- | --------------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `children`     | `ReactNode`                                   | Yes      |           | Block 콘텐츠                                                                                         |
+| `loading`      | `boolean`                                     |          |           | 로딩 상태. 설정 시 LoadingOverlay로 자동 래핑                                                        |
+| `loadingLabel` | `string`                                      |          |           | LoadingOverlay 접근성 레이블                                                                         |
+| `spacing`      | `"section" \| "group" \| "element" \| "none"` |          | "section" | Block 최상위 자식 사이 간격. 데이터 밀도가 높은 Block는 group/element로 낮출 수 있음                 |
+| `inset`        | `"section" \| "group" \| "element" \| "none"` |          |           | Block 안쪽 여백. 페이지 콘텐츠 경계에는 section을 사용하고, 이미 여백을 제공하는 Shell 안에서는 생략 |
+| `className`    | `string`                                      |          |           | 기본 스타일 오버라이드                                                                               |
 
 **Examples:**
 
@@ -1892,7 +1900,7 @@ _Block 루트:_
 ```tsx
 import { BlockLayout, PageHeader } from "@reopt-ai/opt-ui";
 
-<BlockLayout loading={isLoading} spacing="section">
+<BlockLayout loading={isLoading} spacing="section" inset="section">
   <PageHeader title="대시보드" description="프로젝트 현황" />
   <section>콘텐츠 영역</section>
 </BlockLayout>;
@@ -2605,17 +2613,17 @@ const filters = [
 **Import:** `import { FileUploadForm } from "@reopt-ai/opt-ui"`
 **Dependencies:** form (core)
 
-| Prop              | Type                                             | Required | Default                    | Description                               |
-| ----------------- | ------------------------------------------------ | -------- | -------------------------- | ----------------------------------------- |
-| `accept`          | `string`                                         |          | "image/\*,.pdf,.doc,.docx" | 허용 파일 타입                            |
-| `showPreview`     | `boolean`                                        |          | true                       | 이미지 미리보기 표시                      |
-| `showFileInfo`    | `boolean`                                        |          | true                       | 파일 정보 표시                            |
-| `showDescription` | `boolean`                                        |          | true                       | 설명 텍스트영역 표시                      |
-| `maxFileSize`     | `number`                                         |          |                            | 최대 파일 크기 (bytes)                    |
-| `onSubmit`        | `(values: { title, description, file }) => void` |          |                            | 제출 핸들러                               |
-| `labels`          | `FileUploadFormLabels`                           |          |                            | i18n용 라벨 오버라이드                    |
-| `onPreview`       | `(file: File) => void`                           |          |                            | 파일 선택 후 프리뷰 콜백                  |
-| `columnMapping`   | `ReactNode`                                      |          |                            | CSV 컬럼 매핑 UI 슬롯 (파일 선택 후 표시) |
+| Prop              | Type                                             | Required | Default                   | Description                               |
+| ----------------- | ------------------------------------------------ | -------- | ------------------------- | ----------------------------------------- |
+| `accept`          | `string`                                         |          | "image/*,.pdf,.doc,.docx" | 허용 파일 타입                            |
+| `showPreview`     | `boolean`                                        |          | true                      | 이미지 미리보기 표시                      |
+| `showFileInfo`    | `boolean`                                        |          | true                      | 파일 정보 표시                            |
+| `showDescription` | `boolean`                                        |          | true                      | 설명 텍스트영역 표시                      |
+| `maxFileSize`     | `number`                                         |          |                           | 최대 파일 크기 (bytes)                    |
+| `onSubmit`        | `(values: { title, description, file }) => void` |          |                           | 제출 핸들러                               |
+| `labels`          | `FileUploadFormLabels`                           |          |                           | i18n용 라벨 오버라이드                    |
+| `onPreview`       | `(file: File) => void`                           |          |                           | 파일 선택 후 프리뷰 콜백                  |
+| `columnMapping`   | `ReactNode`                                      |          |                           | CSV 컬럼 매핑 UI 슬롯 (파일 선택 후 표시) |
 
 #### EventIcon
 
@@ -2627,6 +2635,19 @@ const filters = [
 | `color` | `string`                    |          | theme accent | 사용자 지정 아이콘 색상. 없으면 theme accent 토큰을 사용하고, 전달하면 전경색과 tint 배경에 적용됩니다. |
 | `size`  | `"sm" \| "md" \| "lg"`      |          | "md"         | 아이콘 크기 (sm=20px, md=28px, lg=36px)                                                                 |
 
+#### ConnectionIndicator
+
+**Import:** `import { ConnectionIndicator } from "@reopt-ai/opt-ui"`
+
+| Prop        | Type                                                        | Required | Default | Description                                                           |
+| ----------- | ----------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------- |
+| `status`    | `"connected" \| "connecting" \| "disconnected" \| "error"`  |          |         | 연결 상태 프리셋. tone과 pulse의 기본값을 정함                        |
+| `tone`      | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` |          |         | status로 표현되지 않는 도메인 상태의 색을 직접 지정 (status보다 우선) |
+| `label`     | `string`                                                    |          |         | 상태 문구                                                             |
+| `showLabel` | `boolean`                                                   |          |         | 문구 표시 여부                                                        |
+| `pulse`     | `boolean`                                                   |          |         | 점 애니메이션. 생략하면 status 프리셋을 따름                          |
+| `className` | `string`                                                    |          |         | 기본 스타일 오버라이드                                                |
+
 #### TemplatePicker
 
 **Import:** `import { TemplatePicker } from "@reopt-ai/opt-ui"`
@@ -2728,6 +2749,30 @@ const filters = [
 | `error`   | `string`                         |          |         | assertive 오류 상태     |
 | `labels`  | `QueryResultsTableLabels`        |          |         | 로딩/빈 상태/행 수 문구 |
 
+#### SqlEditor
+
+**Import:** `import { SqlEditor } from "@reopt-ai/opt-ui"`
+**Dependencies:** button (core)
+
+| Prop                | Type                          | Required | Default | Description                                                                      |
+| ------------------- | ----------------------------- | -------- | ------- | -------------------------------------------------------------------------------- |
+| `value`             | `string`                      | Yes      |         | 편집 중인 SQL                                                                    |
+| `onChange`          | `(sql: string) => void`       | Yes      |         | 본문 변경 핸들러                                                                 |
+| `onRun`             | `(sql: string) => void`       |          |         | Mod+Enter 실행 핸들러                                                            |
+| `onRunAndAdvance`   | `(sql: string) => void`       |          |         | Shift+Enter — 실행 후 다음 셀/탭으로 이동                                        |
+| `schema`            | `SqlEditorSchema`             |          |         | 테이블/컬럼 자동완성 스키마. 변경 시 에디터를 다시 만들지 않고 자동완성만 재구성 |
+| `completionSources` | `SqlEditorCompletionSource[]` |          |         | 스키마 자동완성에 더할 완성 소스 (함수 시그니처, 스니펫)                         |
+| `keymap`            | `SqlEditorKeyBinding[]`       |          |         | 추가 키 바인딩. 내장 실행 바인딩보다 먼저 평가                                   |
+| `extensions`        | `SqlEditorExtension[]`        |          |         | 임의의 CodeMirror 확장. 내장 확장 뒤에 붙어 우선권을 가짐                        |
+| `height`            | `number \| "fill"`            |          |         | px 고정 높이. fill이면 부모가 정한 높이를 채움                                   |
+| `placeholder`       | `string`                      |          |         | 빈 편집기 안내 문구                                                              |
+| `readOnly`          | `boolean`                     |          |         | 편집 잠금                                                                        |
+| `ariaLabel`         | `string`                      |          |         | 편집 영역 접근성 레이블                                                          |
+| `autoFocus`         | `boolean`                     |          |         | 마운트 시 포커스                                                                 |
+| `showFooter`        | `boolean`                     |          |         | 실행 힌트/버튼 표시. 기본값은 onRun이 있을 때 표시                               |
+| `labels`            | `SqlEditorLabels`             |          |         | 문구 오버라이드                                                                  |
+| `className`         | `string`                      |          |         | 기본 스타일 오버라이드                                                           |
+
 #### ReportBuilder
 
 **Import:** `import { ReportBuilder } from "@reopt-ai/opt-ui"`

package/README.md

@@ -2,6 +2,25 @@
 
 접근성 우선 UI 컴포넌트 라이브러리. opt-ui-primitives 기반 Core, 비즈니스 Shells, Surface/block layout primitives를 제공합니다. 페이지 템플릿 Surface는 `@reopt-ai/opt-cli` registry로 설치하며, 차트와 데이터 시각화 컴포넌트는 `@reopt-ai/opt-charts`로 분리되었습니다.
 
+## 에이전트 스킬로 설정하기 (권장)
+
+소비자 프로젝트 루트에서 전용 스킬을 설치합니다.
+
+```bash
+npx skills add reopt-ai/reopt-skills/opt-ui-install
+```
+
+설치 후 에이전트에게
+`opt-ui-install 스킬로 이 프로젝트에 @reopt-ai/opt-ui를 설정하고 검증해줘`라고
+요청하세요. 스킬은 신규 설치와 업그레이드를 구분하고, `AGENTS.md`(없으면
+`CLAUDE.md`)의 reopt marker 블록, Tailwind v4, `OptThemeProvider`, `opt
+doctor`, Surface 흐름을 멱등하게 설정합니다. 스킬 소스는
+[`reopt-ai/reopt-skills`](https://github.com/reopt-ai/reopt-skills/tree/main/skills/opt-ui-install)가
+단일 기준입니다.
+
+아래 설치 명령은 스킬을 사용할 수 없거나 모든 단계를 직접 통제할 때의 수동
+대안입니다.
+
 ## 설치
 
 ```bash
@@ -170,13 +189,15 @@ CSS 변수 기반 시맨틱 토큰 — `dark:` 프리픽스 없이 자동 전환
 
 ### 시맨틱 스페이싱
 
-| CSS 변수              | Tailwind      | 값            |
-| --------------------- | ------------- | ------------- |
-| `--opt-space-section` | `gap-section` | 1.5rem (24px) |
-| `--opt-space-group`   | `gap-group`   | 1rem (16px)   |
-| `--opt-space-element` | `gap-element` | 0.5rem (8px)  |
+| CSS 변수              | Tailwind                   | 값            |
+| --------------------- | -------------------------- | ------------- |
+| `--opt-space-section` | `gap-section`, `p-section` | 1.5rem (24px) |
+| `--opt-space-group`   | `gap-group`, `p-group`     | 1rem (16px)   |
+| `--opt-space-element` | `gap-element`, `p-element` | 0.5rem (8px)  |
 
-Surface 루트는 반드시 `SurfaceLayout`을 사용하여 일관된 스페이싱을 유지합니다.
+Block 루트는 반드시 `BlockLayout`을 사용합니다. 페이지 콘텐츠 경계를 Block이 직접 맡을 때는
+`inset="section"`을 지정하고, 카드나 Shell이 이미 여백을 제공하는 embedded Block에서는 inset을
+생략합니다. `PageHeader`는 재사용 가능한 콘텐츠 헤더이므로 바깥 여백을 소유하지 않습니다.
 
 ## 접근성
 
@@ -229,7 +250,7 @@ bun run test:coverage
 ## Design Decisions
 
 - **Layer metaphor**: Core → Shells는 opt-ui가 맡고, 페이지 템플릿 Surface는 opt-cli block registry로 설치
-- **SurfaceLayout 강제**: block template은 반드시 `SurfaceLayout` 또는 `createSurface`를 사용하여 구조적 일관성 보장
+- **BlockLayout 강제**: block template은 반드시 `BlockLayout` 또는 `createBlock`을 사용하고, 페이지 경계는 `inset="section"`으로 명시
 - **Subpath exports**: `./core`, `./visuals`, `./shells` — 필요한 계층만 import 가능
 - **Dual format**: ESM + CJS — 모든 번들러/런타임 호환
 - **Source maps**: 디버깅을 위한 소스맵 포함

package/dist/app.css

@@ -0,0 +1,146 @@
+/*
+ * @reopt-ai/opt-ui — Application base layer (optional)
+ *
+ * `tailwind.css`가 토큰과 유틸리티를 준다면, 이 파일은 **앱 셸이 매번 다시 쓰는
+ * 규칙**을 준다. 실제 소비 프로젝트를 감사했을 때 아래 다섯 가지가 앱마다
+ * 손으로 재작성돼 있었고, 매번 조금씩 달랐다 — 커서 정책, opt-ui 밖 요소의
+ * 포커스 링, 사용자 모션 설정, 글자 크기 설정, 스킵 링크.
+ *
+ * Usage (consumer globals.css):
+ *
+ *   @import "tailwindcss";
+ *   @import "@reopt-ai/opt-ui/tailwind.css";
+ *   @import "@reopt-ai/opt-ui/app.css";
+ *
+ * 선택 사항이다. 앱이 자기 규칙을 갖고 있다면 안 써도 되고, 여기 규칙은 전부
+ * `:where()`로 특이도 0이라 유틸리티 클래스가 항상 이긴다.
+ */
+
+@layer base {
+  /* ── Cursor ──
+   *
+   * 브라우저 기본값은 button에 `default`를 준다. 디자인 시스템을 쓰는 앱은
+   * 예외 없이 이걸 pointer로 되돌리는데, 그 목록을 손으로 관리하면 role 기반
+   * 요소(`[role="option"]`, `[role="treeitem"]`)가 빠지기 쉽다.
+   *
+   * opt-ui 컴포넌트는 자체 클래스로 커서를 지정하므로 여기 규칙과 무관하다.
+   * 이건 앱이 직접 쓰는 raw 요소를 위한 것이다. */
+  :where(
+    button:not(:disabled),
+    summary,
+    label[for],
+    select:not(:disabled),
+    a[href],
+    input:is(
+      [type="button"],
+      [type="submit"],
+      [type="reset"],
+      [type="checkbox"],
+      [type="radio"],
+      [type="file"],
+      [type="range"]
+    ):not(:disabled),
+    [role="button"]:not([aria-disabled="true"]),
+    [role="tab"]:not([aria-disabled="true"]),
+    [role="menuitem"]:not([aria-disabled="true"]),
+    [role="menuitemcheckbox"]:not([aria-disabled="true"]),
+    [role="menuitemradio"]:not([aria-disabled="true"]),
+    [role="option"]:not([aria-disabled="true"]),
+    [role="switch"]:not([aria-disabled="true"]),
+    [role="checkbox"]:not([aria-disabled="true"]),
+    [role="radio"]:not([aria-disabled="true"]),
+    [role="treeitem"]:not([aria-disabled="true"])
+  ) {
+    cursor: pointer;
+  }
+
+  :where(
+    button:disabled,
+    input:disabled,
+    select:disabled,
+    textarea:disabled,
+    [aria-disabled="true"]
+  ) {
+    cursor: not-allowed;
+  }
+
+  /* ── Focus ──
+   *
+   * opt-ui 컴포넌트는 `data-opt-id`를 달고 자체 포커스 링을 갖는다. 앱이 직접
+   * 쓰는 raw button/link/summary에는 아무것도 없어서, 키보드 사용자가 앱 고유
+   * 영역에 들어가는 순간 포커스가 사라지곤 한다. 같은 링을 기본값으로 준다. */
+  :where(
+    button:not([data-opt-id]),
+    a[href]:not([data-opt-id]),
+    summary:not([data-opt-id]),
+    [tabindex]:not([tabindex="-1"]):not([data-opt-id])
+  ):focus-visible {
+    outline: 2px solid var(--opt-ring);
+    outline-offset: 2px;
+  }
+
+  /* ── User preference: text scale ──
+   *
+   * `<html data-text-scale="small|large">`로 루트 글자 크기를 조절한다. rem
+   * 기반 토큰이 전부 따라 움직이므로 레이아웃이 함께 확대/축소된다. */
+  html[data-text-scale="small"] {
+    font-size: 93.75%;
+  }
+
+  html[data-text-scale="large"] {
+    font-size: 112.5%;
+  }
+
+  /* ── User preference: motion ──
+   *
+   * `tailwind.css`가 시스템 `prefers-reduced-motion`을 이미 존중한다. 이건 앱
+   * 설정에서 사용자가 **시스템과 무관하게** 끈 경우를 위한 명시적 스코프다.
+   * `<html data-motion="reduced">` 또는 앱 셸 루트에 붙인다. */
+  [data-motion="reduced"],
+  [data-motion="reduced"] :where(*, *::before, *::after) {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+@layer components {
+  /* ── Shortcut hints ──
+   *
+   * `<Kbd hint>`가 붙이는 클래스. 메뉴 항목 옆에 붙는 "⌘K" 같은 광고성 배지를
+   * 가리키며, 단축키 도움말 자체는 대상이 아니다.
+   *
+   * `<html data-shortcut-hints="hidden">`이면 사라진다 — 설정 값을 모든 호출
+   * 지점에 내려보내지 않고 "키보드 힌트 숨기기"를 구현하는 경로다.
+   * opt-shell의 `shortcutHints` 정책이 그 속성을 쓴다. */
+  [data-shortcut-hints="hidden"] .opt-shortcut-hint {
+    display: none;
+  }
+
+  /* ── Skip link ──
+   *
+   * 키보드 사용자가 사이드바 전체를 Tab으로 통과하지 않고 본문으로 건너뛰는
+   * 링크. 포커스 전에는 화면 밖에 있다가 포커스되면 나타난다.
+   *
+   *   <a class="opt-skip-link" href="#main">본문으로 건너뛰기</a>
+   */
+  .opt-skip-link {
+    position: fixed;
+    z-index: 100;
+    top: var(--opt-space-element);
+    left: var(--opt-space-element);
+    padding: var(--opt-space-element) var(--opt-space-group);
+    border: 1px solid var(--opt-ring);
+    border-radius: var(--opt-radius-md);
+    color: var(--opt-text);
+    background: var(--opt-surface-overlay);
+    box-shadow: var(--opt-shadow-md);
+    text-decoration: none;
+    transform: translateY(calc(-100% - var(--opt-space-section)));
+  }
+
+  .opt-skip-link:focus {
+    transform: translateY(0);
+  }
+}