@reopt-ai/opt-ui 1.4.1 → 1.6.0

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);
+  }
+}