@qijenchen/design-system 0.1.0-beta.10

package/src/patterns/resize-handle/resize-handle.tsx

@@ -0,0 +1,188 @@
+import * as React from 'react'
+import { cn } from '@/lib/utils'
+
+/**
+ * ResizeHandle — pattern primitive for drag-to-resize visual + a11y(2026-05-21 v1 ship per
+ * user「style 難道不用跟 data table column resize 維持 ssot」+「都照你建議做」approval)。
+ *
+ * ── 定位 ──
+ * 統一所有 drag-resize affordance 的視覺 / cursor / 命中區 / a11y attributes。
+ * Consumer 自管 drag math(TanStack column resize / Sidebar drag-resize / Aside drag-resize
+ * 各有不同 width state pathway,本 primitive 不耦合)。
+ *
+ * Consumers(roadmap per spec.md):
+ * - Phase 1(本 commit):primitive ship,DataTable / Sidebar / Aside 尚未 migrate
+ * - Phase 2(future):DataTable column resize migrate(TanStack `header.getResizeHandler()` 接入)
+ * - Phase 3(future):Sidebar drag-resize enable
+ * - Phase 4(future):AppShell Aside drag-resize enable
+ *
+ * ── 實作基礎 ──
+ * 視覺對齊 DataTable column resize 既有 canonical(7px 命中區 + 1px line + cursor:col-resize
+ * + hover border-hover + dragging primary)。direction='vertical' 同 idiom 軸換 row-resize。
+ *
+ * ── 消費的 SSOT ──
+ * - tokens: [--border-hover, --divider, --primary, --table-cell-py(只 DataTable consumer 用)]
+ * - patterns: none(self-contained primitive)
+ *
+ * ── World-class 對照 ──
+ * - AG Grid column resize handle(7-8px hit zone + 1px line)
+ * - Material X-DataGrid `MuiDataGrid-iconSeparator`(同 visual idiom)
+ * - Notion column / sidebar resize handle(同 cursor + line + hover affordance)
+ * - VS Code activity bar / sidebar resize(8px hit zone + bg highlight on drag)
+ * - Figma left panel resize(8px hit zone + 1px line)
+ *
+ * 統一共識:hit zone ≥ 7px(fingertip-friendly)/ 1px visual line(non-intrusive)/
+ * hover affordance(stronger line) / drag feedback(primary highlight) /
+ * a11y `role="separator"` + `aria-orientation` + 描述性 aria-label。
+ */
+export interface ResizeHandleProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'role'> {
+  /**
+   * Drag 方向。`horizontal` = 拖拉左右(column resize / sidebar width);
+   * `vertical` = 拖拉上下(row resize / panel height)。決定 cursor + aria-orientation。
+   */
+  direction: 'horizontal' | 'vertical'
+  /**
+   * 命中區相對於容器位置。`end` = 右側(column right edge / sidebar right edge);
+   * `start` = 左側(較少用);`vertical` direction 同邏輯:end=bottom / start=top。
+   */
+  position?: 'start' | 'end'
+  /**
+   * 是否處於拖拉中。consumer 自管(eg. `header.column.getIsResizing?.()` for TanStack /
+   * `isDragging` boolean for sidebar)。primary 色 highlight feedback。
+   */
+  isResizing?: boolean
+  /**
+   * 是否禁用拖拉。consumer 透過 col / panel 的 resizable flag 決定。
+   * 禁用時不 render cursor + 不 attach a11y role。
+   */
+  disabled?: boolean
+  /** a11y 描述性 label。consumer 必傳(eg. 「拖曳調整欄寬」/「拖曳調整側欄寬度」)。 */
+  'aria-label': string
+  /**
+   * 是否畫 visual line(1px divider)。`false` = consumer 已 paint(eg. DataTable panel
+   * boundary col by panel-r 接管,不重複)。Default `true`。
+   */
+  showLine?: boolean
+  /**
+   * Vertical line `top` / `bottom` inset(只 direction='horizontal' 用)。Default 0
+   * (full-height line)。DataTable 用 `var(--table-cell-py)` 縮到 cell padding 內(cell-fit line)。
+   */
+  lineInsetStart?: string
+  /** 同上 inset 對位(bottom)。 */
+  lineInsetEnd?: string
+}
+
+/**
+ * Primitive consumer pattern:
+ *
+ * ```tsx
+ * // DataTable column resize(future Phase 2 migrate sample)
+ * <ResizeHandle
+ *   direction="horizontal"
+ *   position="end"
+ *   isResizing={header.column.getIsResizing?.()}
+ *   disabled={!isResizable}
+ *   aria-label="拖曳調整欄寬"
+ *   onPointerDownCapture={(e) => {
+ *     e.stopPropagation()
+ *     header.getResizeHandler?.()(e.nativeEvent)
+ *   }}
+ *   lineInsetStart="var(--table-cell-py)"
+ *   lineInsetEnd="var(--table-cell-py)"
+ * />
+ *
+ * // Sidebar drag-resize(future Phase 3 sample)
+ * <ResizeHandle
+ *   direction="horizontal"
+ *   position="end"
+ *   isResizing={isDragging}
+ *   aria-label="拖曳調整側欄寬度"
+ *   onPointerDown={startDrag}
+ * />
+ * ```
+ */
+export const ResizeHandle = React.forwardRef<HTMLSpanElement, ResizeHandleProps>(
+  (
+    {
+      direction,
+      position = 'end',
+      isResizing,
+      disabled,
+      showLine = true,
+      lineInsetStart,
+      lineInsetEnd,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const isHorizontal = direction === 'horizontal'
+    const ariaOrientation = isHorizontal ? 'vertical' : 'horizontal'  // separator's axis is perpendicular to drag
+
+    // 命中區用 inline style 而非 Tailwind arbitrary values(避免 Tailwind v4 JIT 對新增 arbitrary
+    // class 在 dev mode 不更新 stylesheet 的 quirk;7px 是 primitive constant 非 token,inline 妥當)。
+    const hitZoneStyle: React.CSSProperties = isHorizontal
+      ? {
+          position: 'absolute',
+          top: 0,
+          bottom: 0,
+          width: 7,
+          ...(position === 'end' ? { right: 0, marginRight: -3 } : { left: 0, marginLeft: -3 }),
+          cursor: disabled ? undefined : 'col-resize',
+        }
+      : {
+          position: 'absolute',
+          left: 0,
+          right: 0,
+          height: 7,
+          ...(position === 'end' ? { bottom: 0, marginBottom: -3 } : { top: 0, marginTop: -3 }),
+          cursor: disabled ? undefined : 'row-resize',
+        }
+
+    // Visual line — 1px,position 端對齊。dragging=primary / hover=border-hover / idle=divider
+    const lineColorClass = isResizing
+      ? 'bg-primary'
+      : disabled
+        ? 'bg-divider'
+        : 'bg-divider group-hover/resize:bg-[var(--border-hover)]'
+
+    const lineStyle: React.CSSProperties = isHorizontal
+      ? {
+          position: 'absolute',
+          width: 1,
+          top: lineInsetStart ?? 0,
+          bottom: lineInsetEnd ?? 0,
+          ...(position === 'end' ? { right: 3 } : { left: 3 }),
+        }
+      : {
+          position: 'absolute',
+          height: 1,
+          left: lineInsetStart ?? 0,
+          right: lineInsetEnd ?? 0,
+          ...(position === 'end' ? { bottom: 3 } : { top: 3 }),
+        }
+
+    // 抽 aria-label / style 由我們管,其他 ...props 不重複
+    const { 'aria-label': ariaLabel, style: extraStyle, ...restProps } = props
+    return (
+      <span
+        ref={ref}
+        role={disabled ? undefined : 'separator'}
+        aria-orientation={disabled ? undefined : ariaOrientation}
+        aria-label={disabled ? undefined : ariaLabel}
+        style={{ ...hitZoneStyle, ...extraStyle }}
+        className={cn('group/resize', !disabled && 'select-none', className)}
+        {...restProps}
+      >
+        {showLine && (
+          <span
+            aria-hidden
+            className={cn('transition-colors', lineColorClass)}
+            style={lineStyle}
+          />
+        )}
+      </span>
+    )
+  },
+)
+ResizeHandle.displayName = 'ResizeHandle'

package/src/stories-helpers/anatomy/anatomy-utils.tsx

@@ -0,0 +1,64 @@
+import React from 'react'
+
+/**
+ * Shared helper components for all `*.anatomy.stories.tsx` files.
+ *
+ * Canonical definitions picked from Button/button.anatomy.stories.tsx and
+ * Slider/slider.anatomy.stories.tsx. Before duplicating these helpers locally,
+ * consider whether the shared version meets your need — visual consistency
+ * across anatomy stories is intentional.
+ *
+ * If you must diverge locally, add a comment explaining why.
+ */
+
+export const H3 = ({ children }: { children: React.ReactNode }) => (
+  <h3 className="text-body font-bold text-foreground mb-2">{children}</h3>
+)
+
+export const Desc = ({ children }: { children: React.ReactNode }) => (
+  <p className="text-caption text-fg-muted mb-4 max-w-[720px] leading-relaxed">{children}</p>
+)
+
+export const Td = ({ children, mono, className }: { children: React.ReactNode; mono?: boolean; className?: string }) => (
+  <td className={`border border-border px-3 py-1.5 text-caption ${mono ? 'font-mono' : ''} ${className ?? ''}`}>{children}</td>
+)
+
+export const Th = ({ children }: { children?: React.ReactNode }) => (
+  <th className="border border-border px-3 py-1.5 text-caption text-fg-secondary bg-muted text-left">{children}</th>
+)
+
+/**
+ * Token color preview swatch.
+ * - `transparent` / `none` / `—` → checkerboard pattern (communicates "no color")
+ * - `white` → literal #fff (CSS var won't resolve to white in all themes)
+ * - otherwise → `var(--token-name)` via backgroundColor
+ */
+export const Swatch = ({ value, size = 'sm' }: { value: string; size?: 'sm' | 'md' }) => {
+  const s = size === 'sm' ? 'w-3 h-3' : 'w-4 h-4'
+  if (value === 'transparent' || value === 'none' || value === '—') {
+    return (
+      <span
+        className={`${s} rounded-md shrink-0 border border-border inline-block align-middle`}
+        style={{
+          backgroundImage:
+            'linear-gradient(45deg,#ddd 25%,transparent 25%,transparent 75%,#ddd 75%),linear-gradient(45deg,#ddd 25%,transparent 25%,transparent 75%,#ddd 75%)',
+          backgroundSize: '6px 6px',
+          backgroundPosition: '0 0,3px 3px',
+        }}
+      />
+    )
+  }
+  return (
+    <span
+      className={`${s} rounded-md shrink-0 border border-black/10 inline-block align-middle`}
+      style={{ backgroundColor: value === 'white' ? '#fff' : `var(${value})` }}
+    />
+  )
+}
+
+export const TokenCell = ({ token, display }: { token: string; display?: string }) => (
+  <span className="inline-flex items-center gap-1.5">
+    <Swatch value={token} size="sm" />
+    <span className="font-mono">{display ?? token}</span>
+  </span>
+)

package/src/styles/preset.css

@@ -0,0 +1,31 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   @qijenchen/design-system — Tailwind v4 Preset
+   ═══════════════════════════════════════════════════════════════════════
+
+   Single-import,即取即用 setup。Consumer entry CSS 只需 1 行:
+
+     @import '@qijenchen/design-system/styles/preset';
+
+   等價於展開:
+     @import 'tailwindcss';
+     @import '@qijenchen/design-system/styles/tokens';
+     @source '../path-to-DS-source';
+
+   Why this exists:
+   Tailwind v4 預設只掃 `src/**`(consumer 自己的 source),不掃 node_modules。
+   DS 元件原始碼用的 utility class(`h-field-md` / `bg-primary-hover` etc.)
+   不在 consumer Tailwind scan scope 內 → 不會被產出 → 元件純文字無樣式。
+
+   Preset 透過 `@source` directive(Tailwind v4 native)告訴 Tailwind:
+   「也掃 DS package source(node_modules/@qijenchen/design-system/src/**)」
+   → DS 內部使用的 utility class 全 generated → 元件正確 render。
+
+   Path resolution:
+   `@source` 路徑相對於 *此 CSS 檔位置*。本檔在
+     node_modules/@qijenchen/design-system/src/styles/preset.css
+   相對路徑 `../**/*` = node_modules/@qijenchen/design-system/src/**
+   ═══════════════════════════════════════════════════════════════════════ */
+
+@import 'tailwindcss';
+@import './tokens.css';
+@source '../**/*.{js,ts,jsx,tsx}';

package/src/styles/tokens.css

@@ -0,0 +1,35 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   @qijenchen/design-system — Consolidated Token Stylesheet
+   ═══════════════════════════════════════════════════════════════════════
+
+   AUTO-GENERATED by scripts/gen-figma-make-artifacts.mjs — DO NOT EDIT MANUALLY.
+
+   To add a new token category:
+     1. Create packages/design-system/src/tokens/<category>/*.css
+     2. Run: node scripts/gen-figma-make-artifacts.mjs
+     3. Commit this file alongside the new token file
+
+   Single-import setup for consumers (Figma Make / ad-hoc Tailwind v4 projects):
+
+     import '@qijenchen/design-system/styles/tokens'
+
+   Load order canonical (per src/globals.css):
+     primitives → @theme-using files (semantic / typography / uiSize / ...) →
+     other categories (layoutSpace / radius / opacity / motion).
+
+   Why aggregator:
+     Tailwind v4 generates utility classes only when @theme directives are
+     loaded. Individual token files declare both raw CSS vars (:root) and
+     @theme inline blocks; aggregator preserves canonical order so all utility
+     classes are generated correctly.
+
+   ═══════════════════════════════════════════════════════════════════════ */
+
+@import './../tokens/color/primitives.css';
+@import './../tokens/color/semantic.css';
+@import './../tokens/typography/typography.css';
+@import './../tokens/uiSize/uiSize.css';
+@import './../tokens/layoutSpace/layoutSpace.css';
+@import './../tokens/radius/radius.css';
+@import './../tokens/opacity/opacity.css';
+@import './../tokens/motion/motion.css';

package/src/tokens/README.md

@@ -0,0 +1,53 @@
+# tokens/ Charter
+
+## 這裡只收:design token 定義 + spec + stories
+
+每個 token 類別一個 folder:
+- `{name}.css` — CSS custom properties 定義
+- `{name}.spec.md` — 命名原則 / 用法規則 / 家族結構
+- `{name}.stories.tsx` — token 展示(色票 / 字級 / 尺寸對照)
+- primitives vs semantic 分檔(如 `color/primitives.css` + `color/semantic.css`)
+
+**folder 名規則**:
+- 單字 → lowercase(`color/` / `radius/` / `typography/`)
+- 多字 → camelCase 反映 CSS `--uiSize` 命名風格(`uiSize/` / `layoutSpace/`)
+
+## 當前居民
+
+`color/` / `typography/` / `uiSize/` / `layoutSpace/` / `density/` / `elevation/` / `radius/` / `opacity/`
+
+## Consumer scope:public vs internal token(2026-05-17 codified)
+
+| Token folder | Scope | Consumer 範例 |
+|---|---|---|
+| `color/` / `typography/` / `radius/` / `elevation/` / `opacity/` / `layoutSpace/` / `density/` | **Public** — consumer-layer(`src/app` / `src/explorations`)直接消費 | UI 開發者寫 `text-body` / `bg-primary` / `--layout-space-loose` 等 |
+| `uiSize/`(`--field-height-*` / `--tab-height-*` / `--table-row-*` / `--tree-indent-*`)| **Internal primitive** — DS 內部 component 消費,consumer 不直接用 | Button / Input / Tabs / DataTable / TreeView 等 primitive 內部消費;consumer 用 `<Button size="sm">` 不用 `h-[var(--field-height-sm)]` |
+
+**Internal token 規則**(`uiSize/` 適用):
+- **不必補 Storybook stories**(consumer 不直接看;審查 grep 結果:`src/app` + `src/explorations` 0 個檔案直接消費 uiSize token,2026-05-17 verified)
+- 但仍有 `.spec.md` codify family / 命名 / 派生公式
+- 出現在 consumer-layer code = anti-pattern(該用 component prop 不該 raw token)
+
+**Public token 規則**:
+- 必補 Storybook stories(色票 / 字級 / 間距對照展示)
+- consumer 可直接消費 utility(`text-body` / `gap-[var(--layout-space-loose)]` 等)
+- 2026-05-17 ship:opacity / layoutSpace 補齊 stories(原本只 spec.md + css 沒展示頁)
+
+## 這裡**不收**(反例)
+
+| 疑似要放這但其實不是 | 實際應去 | 為什麼 |
+|-------------------|---------|--------|
+| 元件消費 token 的 code | `../components/{Name}/` | token 被 consume,不在 token home 寫 consumer |
+| cross-cutting design rule(如「何時用 semantic token vs primitive」)| `.claude/rules/ui-development.md`「Token 命名 4 條硬規則」 | 系統級 rule,不只關某個 token |
+| shadcn compat alias 遷移規則 | `.claude/rules/ui-development.md`「Tailwind 5 條核心」 | 技術陷阱屬 UI 開發 |
+
+## 新增 token 的 criteria
+
+1. 找不到現有 family 可鏡射 → **先質疑是否真需要**(見 CLAUDE.md 「對齊既有 family」)
+2. 命名過三重 test(既有語言 / 世界級 idiom / 跨元件不衝突)
+3. Primitive / semantic 分層清楚
+4. 若是語意色相 → 走 `color/color.spec.md`「新增語意色相的標準流程」4 步
+
+## 建立前必 Read
+
+`.claude/rules/ui-development.md`「Token 命名 4 條硬規則」+ 對應 family 的 spec(如 `color/color.spec.md`)。