@qijenchen/design-system 0.1.0-beta.74 → 0.1.0-beta.76

package/src/components/Toast/toast.principles.stories.tsx

@@ -42,10 +42,10 @@ export const UsageGuidance: Story = {
       <p>適合 Toast 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Toast/展示" name="有標題與描述"><span className="text-primary hover:underline font-medium cursor-pointer">有 Title + Description</span></LinkTo>
+          <LinkTo kind="Design System/Components/Toast/展示" name="有標題與描述"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">有 Title + Description</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Toast/展示" name="互動測試"><span className="text-primary hover:underline font-medium cursor-pointer">互動測試</span></LinkTo>
+          <LinkTo kind="Design System/Components/Toast/展示" name="互動測試"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">互動測試</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:先看下方「何時用 / 何時不用」的對照;若訊息重要到使用者必須看到、或需要使用者確認,就不該用 Toast,改用 Alert(持久顯示)或 Dialog(阻斷確認)。</p>

package/src/components/Tooltip/tooltip.principles.stories.tsx

@@ -49,13 +49,13 @@ export const UsageGuidance: Story = {
           <p>適合 Tooltip 的真實業務場景(點擊跳轉「展示」頁範例):</p>
           <ul className="space-y-1">
             <li>
-              <LinkTo kind="Design System/Components/Tooltip/展示" name="非 Button 元素"><span className="text-primary hover:underline font-medium cursor-pointer">非 Button 元素</span></LinkTo>
+              <LinkTo kind="Design System/Components/Tooltip/展示" name="非 Button 元素"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">非 Button 元素</span></LinkTo>
             </li>
             <li>
-              <LinkTo kind="Design System/Components/Tooltip/展示" name="方向"><span className="text-primary hover:underline font-medium cursor-pointer">方向</span></LinkTo>
+              <LinkTo kind="Design System/Components/Tooltip/展示" name="方向"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">方向</span></LinkTo>
             </li>
             <li>
-              <LinkTo kind="Design System/Components/Tooltip/展示" name="長文字"><span className="text-primary hover:underline font-medium cursor-pointer">長文字</span></LinkTo>
+              <LinkTo kind="Design System/Components/Tooltip/展示" name="長文字"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長文字</span></LinkTo>
             </li>
           </ul>
           <p className="text-fg-muted mt-3">判斷不確定時:回到「畫面上的資訊是否已足夠」這個核心問題;若提示需要被點擊或停留互動,改用近親元件(見下方「vs 近親」)。</p>

package/src/components/TreeView/tree-view.principles.stories.tsx

@@ -45,11 +45,11 @@ export const UsageGuidance: Story = {
         <div className="prose prose-sm max-w-prose mb-8">
           <p>適合 TreeView 的真實業務場景(點擊跳轉「展示」頁範例):</p>
           <ul className="space-y-1">
-            <li><LinkTo kind="Design System/Components/TreeView/展示" name="檔案瀏覽"><span className="text-primary hover:underline font-medium cursor-pointer">檔案瀏覽</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/TreeView/展示" name="步驟引導"><span className="text-primary hover:underline font-medium cursor-pointer">步驟引導</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/TreeView/展示" name="多選"><span className="text-primary hover:underline font-medium cursor-pointer">多選</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/TreeView/展示" name="長標籤"><span className="text-primary hover:underline font-medium cursor-pointer">長標籤</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/TreeView/展示" name="拖曳重排"><span className="text-primary hover:underline font-medium cursor-pointer">拖曳重排</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="檔案瀏覽"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">檔案瀏覽</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="步驟引導"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">步驟引導</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="多選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">多選</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="長標籤"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長標籤</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="拖曳重排"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">拖曳重排</span></LinkTo></li>
           </ul>
           <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
         </div>

package/src/components/TreeView/tree-view.stories.tsx

@@ -245,7 +245,7 @@ export const DragAndDrop: Story = {
               {renderNodes(tree)}
             </TreeView>
           </div>
-          <button type="button" onClick={() => setTree(INITIAL_TREE)} className="text-caption text-primary hover:underline cursor-pointer self-start">
+          <button type="button" onClick={() => setTree(INITIAL_TREE)} className="text-caption text-primary hover:text-primary-hover cursor-pointer self-start">
             重設
           </button>
         </div>

package/src/components/TreeView/tree-view.tsx

@@ -1057,7 +1057,7 @@ export const treeViewMeta = {
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-primary', 'bg-primary-subtle', 'bg-surface'],
+    bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],
     ring: ['ring-ring'],
   },

package/src/patterns/element-anatomy/item-anatomy.spec.md

@@ -474,7 +474,7 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 | 內容物高度 | 對齊容器 | 對齊目標 |
 |---|---|---|
 | ≤ 24px | `h-[1lh]` | 第一行 label 的垂直中心 |
-| > 24px(+ 有 description) | `h-[calc(1lh + 2px + desc_1lh)]` | label + gap + description 文字塊的垂直中心 |
+| > 24px(+ 有 description) | `h-[calc(1lh + var(--item-gap-label-desc-<mode>[-lg]) + desc-font-size*1.3)]` | label + gap + description 文字塊的垂直中心 |
 | > 24px(無 description) | `h-[1lh]` | 強制 inline(沒有文字塊可對齊) |
 
 ### 為什麼 prefix 和 suffix 各自獨立(不互相同步)

package/src/patterns/element-anatomy/item-anatomy.stories.tsx

@@ -161,7 +161,7 @@ const SCANNING_SPECS: Record<SizeKey, TypoSpec> = {
 const READING_SPECS: Record<SizeKey, TypoSpec> = {
   sm: { labelFont: 'text-body', labelSize: '14px', labelLh: '1.5', descFont: 'text-body', descSize: '14px', descLh: '1.5', iconPx: 16 },
   md: { labelFont: 'text-body', labelSize: '14px', labelLh: '1.5', descFont: 'text-body', descSize: '14px', descLh: '1.5', iconPx: 16 },
-  lg: { labelFont: 'text-body-lg', labelSize: '16px', labelLh: '1.5', descFont: 'text-body-lg', descSize: '16px', descLh: '1.5', iconPx: 20 },
+  lg: { labelFont: 'text-body-lg', labelSize: '16px', labelLh: '1.5', descFont: 'text-body', descSize: '14px', descLh: '1.5', iconPx: 20 },
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════

package/src/patterns/overlay-surface/overlay-surface.spec.md

@@ -177,6 +177,7 @@ list 不再是 body 唯一 region → **不該撤 body chrome padding**(撤了
 - `border-t border-divider`
 - `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`
 - `flex items-center justify-end gap-2 shrink-0`(右對齊按鈕列,不被壓縮)
+- **Footer px = body 內容內縮原則**:預設 `layout-space-loose` 讓 footer 按鈕左緣對齊 SurfaceHeader title / SurfaceBody 內容左緣(整面板內容垂直對齊一條線,同 Body alignment rationale)。**例外**:body 為 full-bleed(滿欄 column selector / 無 chrome padding 的 unbounded list)、無內容左緣可對齊時,可經 `className` override 較緊 px(eg. TimePicker footer override `px-[var(--layout-space-tight)]` 對齊滿欄置中 columns、保窄面板平衡)。**注**:`--field-px` 是 form-field gutter 概念(uiSize),**不**用於 overlay footer——footer 屬 overlay chrome,padding 走 layoutSpace 家族。
 
 ---
 

package/src/patterns/resize-handle/resize-handle.spec.md

@@ -59,7 +59,7 @@ benchmark:
 取值依據:7px 命中區 / 1px line 非自創——來自下方「世界級對照細節」5 家共識(hit zone 7-8px fingertip-friendly / 1px line non-intrusive)+ DataTable v11 已 ship 的既有 canonical(本 primitive 抽取自它,M17)。
 
 - **命中區**:7px 寬(horizontal)/ 高(vertical),`-3px` outward offset 跨 boundary 抓得到
-- **Visual line**:1px,positioned `right-[3px]` / `bottom-[3px]`,default full-extent
+- **Visual line**:1px,line offset 3px from the position edge(inline style `right: 3` / `bottom: 3`,非 Tailwind class — 見 tsx JIT-quirk note),default full-extent
   - **idle**:`bg-divider`
   - **disabled**:`bg-divider`(無 hover affordance)
   - **hover**:`bg-[var(--border-hover)]`(via `group/resize` selector)

package/src/tokens/color/color.spec.md

@@ -195,6 +195,8 @@ Icon 色彩 canonical 的 SSOT 住 `patterns/element-anatomy/item-anatomy.spec.m
 <a className="text-primary hover:text-primary-hover">查看詳情</a>
 ```
 
+**連結 hover = 換色(`text-primary-hover`),不用底線** —— `text-primary hover:underline` 偏離 canonical。真元件 Breadcrumb / Button / RadioGroup 已遵循。**例外:`LinkInput` 是「外部連結值」顯示,刻意保留 hover 底線作為「可點開連結」affordance(見 `link-input.spec.md`),非 violator**。story 導覽連結由 `check_story_invariants.sh` R10 機械防 drift(P1 warn,豁免 `// @link-style-allow:`)。
+
 ### Status
 
 狀態色表達系統回饋，代表「系統在告訴你什麼」，不用於互動操作。

package/src/tokens/color/semantic.css

@@ -197,7 +197,7 @@
 
   /* Brand / Action — 品牌主操作色
      --primary-text 為 SOP 規定的 5 件套之一，目前無消費者
-     （Button 直接用 text-white, Tag 用 primitive --color-blue-7） */
+     （Button 直接用 text-on-emphasis, Tag 用 primitive --color-blue-7） */
   --primary:              var(--color-blue-6);
   --primary-hover:        var(--color-blue-5);
   --primary-active:       var(--color-blue-7);

package/src/tokens/uiSize/uiSize.css

@@ -24,6 +24,11 @@
   --field-height-md: 2rem;      /* 32px */
   --field-height-lg: 2.25rem;   /* 36px */
 
+  /* Field horizontal padding — 固定 12px(不隨 size/density);form-context field 左右內距 SSOT。
+     跟 --table-cell-px(cell-context)同 -px 慣例;Input/Select/Combobox/DatePicker/TimePicker/Textarea
+     + tag 模式右緣 re-assert 全消費此 token(取代散落的 px-3 / inline 0.75rem,M17 SSOT 可傳播)。 */
+  --field-px: 0.75rem;          /* 12px */
+
   /* Table Row Height — DataTable */
   --table-row-sm: 2rem;         /* 32px */
   --table-row-md: 2.5rem;       /* 40px */

package/src/tokens/uiSize/uiSize.spec.md

@@ -94,6 +94,20 @@ Consumer 寫 Form 或 Toolbar 時並排多個 field-height 元件：
 
 本專案曾發生 SegmentedControl 的 code defaults 是 `md`、spec + docblock 寫 `sm ★default` 的三方不一致（2026-04-18 修正）。避免方式：改 cva `defaultVariants` 前先讀本表，確認新值仍符合 family 約束。
 
+## Field Horizontal Padding
+
+Form-context field 控件的左右水平內距。**固定 12px,不隨 size / density 變化**——縱向才是 density 節奏;橫向是內容溝槽常數,對齊 field-height family 全控件。
+
+| Token | 值 | 說明 |
+|-------|-----|------|
+| `--field-px` | 0.75rem (12px) | form-context field 左右內距 SSOT;固定不隨 size / density |
+
+**消費者**:`Input` / `NumberInput` / `Select` / `Combobox` / `DatePicker` / `TimePicker` / `LinkInput` / `Textarea`(經 `fieldWrapperStyles` cva `px-[var(--field-px)]`)+ `PeoplePicker`(form-context inject `!px-[var(--field-px)]`)+ tag 模式右緣 re-assert(`paddingRight: var(--field-px)`,Select / Combobox readonly + edit)。
+
+**與 `--table-cell-px` 的關係**:同 `-px` 命名慣例。`--table-cell-px`(DataTable-scoped)預設 `var(--field-px)`(form / cell 同 12px content gutter SSOT),但仍是獨立 named token、可被 DataTable 單獨 override(per `components/Field/field-controls.spec.md` contract (c) scoped 決策)。
+
+**Why 固定不隨 density**:density 本質是縱向密度(一屏幾列);橫向管可讀性(字離格線距離),目的不同不綁。對齊 Ant Table(橫向 padding 不隨 density 變、縱橫分離)+ 全 DS field 控件 12px 常數。M17「SSOT 必可傳播」:散落的 `px-3` / inline `0.75rem` 全收斂進此 token。
+
 ## Table Row
 
 DataTable 行高。density 切換統一 +0.5rem (+8px)。
@@ -152,9 +166,9 @@ DataTable 行高。density 切換統一 +0.5rem (+8px)。
 | Avatar 內 icon | `components/Avatar/avatar.spec.md:165` | `round_even(size × 0.6)` formula | Material / Apple HIG |
 | Empty illustration | `components/Empty/empty.tsx:48` | Avatar 48 wrap → icon 28(Avatar formula derived)| Empty-state canonical |
 | FileViewer thumb | `components/FileViewer/file-viewer.tsx:621` | thumb 64 → icon 20(file-type indicator hardcode 無公式)| Thumbnail UI 慣例 |
-| CircularProgress | `components/CircularProgress/circular-progress.tsx:87` | `strokeWidth = max(2, size/10)` stroke ring 厚度非 icon | Geometric scaling |
-| Steps indicator icon | `components/Steps/steps.tsx:24` | `INDICATOR_ICON_SIZE {sm:0, md:16, lg:20}`(sm 因圓圈 8px 太小)| Indicator-internal |
-| Checkbox/Switch check | `components/Checkbox/checkbox.tsx:49` + `components/Switch/switch.tsx:73` | `{sm:12, md:12, lg:16}` form-control internal + stroke 下限 12 | iOS HIG / Material 3 / Polaris | <!-- @benchmark-unverified -->
+| CircularProgress | `components/CircularProgress/circular-progress.tsx:86` | `strokeWidth = max(2, round(size/10))` stroke ring 厚度非 icon | Geometric scaling |
+| Steps indicator icon | `components/Steps/steps.tsx:25` | `INDICATOR_ICON_SIZE {sm:0, md:16, lg:20}`(sm 因圓圈 8px 太小)| Indicator-internal |
+| Checkbox/Switch check | `components/Checkbox/checkbox.tsx:52` + `components/Switch/switch.tsx:83` | `{sm:12, md:12, lg:16}` form-control internal + stroke 下限 12 | iOS HIG / Material 3 / Polaris | <!-- @benchmark-unverified -->
 
 **程式化 SSOT**:`patterns/element-anatomy/item-anatomy.tsx:66` `ICON_SIZE = {sm:16, md:16, lg:20}` 是本 tier 的 type-safe const。**Form control 透過 `tokens/uiSize/icon-size.ts` re-export entry import**(避 components→patterns 反向 dependency)。