@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

package/src/components/Rating/rating.principles.stories.tsx

@@ -0,0 +1,296 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import { useState } from 'react'
+import { Heart, ThumbsUp, Star } from 'lucide-react'
+import { Rating } from './rating'
+import { Button } from '@/design-system/components/Button/button'
+import { Tag } from '@/design-system/components/Tag/tag'
+import { Slider } from '@/design-system/components/Slider/slider'
+
+const meta: Meta = {
+  title: 'Design System/Components/Rating/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-wrap gap-6 items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal mt-2 ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse / InteractiveVsReadOnly / RatingVsAlternatives(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const SubmitFlow = () => {
+      const [v, setV] = useState(0)
+      return (
+        <div className="flex flex-col gap-2 w-[300px] p-4 border border-border rounded-md">
+          <div className="text-caption text-fg-secondary font-medium">送出評分 — interactive</div>
+          <Rating value={v} onChange={setV} size="lg" aria-label="為這次用餐評分" />
+          <Label>使用者正在給分，hover 預覽 + click 送出</Label>
+        </div>
+      )
+    }
+    return (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Rating 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Rating/展示" name="商品列表平均分"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品列表平均分</span></LinkTo>
+          <span className="text-fg-secondary"> — 電商搜尋結果每張商品卡的 readOnly 平均分 + 評論數(4.7、12,843 則)</span>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Rating/展示" name="送出評分流程"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">送出評分流程</span></LinkTo>
+          <span className="text-fg-secondary"> — 訂單完成 / 用餐後使用者親自給分:hover 預覽 + click 送出(interactive)</span>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Rating/展示" name="包在 Field 內"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">包在 Field 內</span></LinkTo>
+          <span className="text-fg-secondary"> — 售後問卷表單中作為欄位:label + 驗證跟其他 Field 控制項一致</span>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="❌ standalone readOnly 不給可存取名稱"
+        note="純視覺的星星螢幕閱讀器讀不出「4.7 分」。standalone readOnly Rating 必須有可存取名稱——傳 aria-label 描述目前分數與滿分（如「平均評分 4.5 星，共 5 星」）；包在 Field 內時由 aria-labelledby 自動指向 FieldLabel，免傳 aria-label。評論數只在畫面確實顯示時才加進描述。"
+      >
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <Rating value={4.5} readOnly precision="half" size="md" aria-label="平均評分 4.5 星，共 5 星" />
+          <Label>✅ `aria-label=&quot;平均評分 4.5 星，共 5 星&quot;`</Label>
+        </div>
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <Rating value={4.5} readOnly precision="half" size="md" aria-label="平均評分 4.5 星，共 5 星" />
+          <Label warn>❌ 若省略 aria-label，螢幕閱讀器會讀不出分數；此可執行示範仍保留名稱，避免 demo 本身成為違規來源</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 換成 Heart / ThumbsUp 做愛心 / like"
+        note="愛心是 binary（喜歡 / 不喜歡），不是 graded 1–5。使用者對「五顆愛心」的期待是『有 5 顆愛心那麼喜歡』= 量化——但 like 本身就是二元，語意衝突。"
+      >
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <Button variant="text" iconOnly startIcon={Heart} aria-label="收藏" />
+          <Label>✅ binary like → Button + pressed</Label>
+        </div>
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <Rating defaultValue={3} max={5} size="md" icon={Heart} aria-label="誤用 Heart" />
+          <Label warn>❌ Rating 換 Heart → 把 binary 變成 graded，語意衝突</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 用 Rating 做 progress bar"
+        note="Rating 的語意是『給分』,用『填了 4 顆星』表達『完成 4/5 步』會讓使用者誤以為是評分而非進度。進度有具體 % 用 ProgressBar(linear)或 CircularProgress(circular,有 value),不定進度用 CircularProgress(無 value,indeterminate)。"
+      >
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <div className="text-caption text-fg-secondary font-medium">完成 4/5 步</div>
+          <Rating value={4} readOnly size="md" aria-label="誤用範例" />
+          <Label warn>❌ 使用者會以為「這個任務被評 4 星」→ 改 ProgressBar</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ max 超過 7"
+        note="超過 7 顆使用者無法「一眼看出是幾星」——必須一顆顆數。這違背 Rating 快速掃視的本質。若需要更細分度（0–100），改用 Slider。"
+      >
+        <div className="flex flex-col gap-2 w-[400px] p-4 border border-border rounded-md">
+          <Rating value={7} readOnly max={10} size="md" aria-label="10 星量表" />
+          <Label warn>❌ 10 星量表無法快速掃視 → 超過 7 改用 Slider</Label>
+        </div>
+      </Rule>
+    </div>
+
+      {/* vs 近親 — 原 InteractiveVsReadOnly + RatingVsAlternatives */}
+      <div>
+        <Rule
+          title="送出前 → interactive，送出後 / 他人評分 → readOnly"
+          note="Rating 既可編輯也可展示，最常見的錯誤是「讓使用者以為可以改別人的分數」。一條清楚的分界：自己正在給分 = interactive；看別人給的分或平均分 = readOnly。"
+        >
+          <SubmitFlow />
+          <div className="flex flex-col gap-2 w-[300px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-secondary font-medium">評論列表 — readOnly</div>
+            <Rating value={5} readOnly size="lg" aria-label="王小明給 5 星" />
+            <Label>他人評分，純顯示</Label>
+          </div>
+          <div className="flex flex-col gap-2 w-[300px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-secondary font-medium">商品平均分 — readOnly</div>
+            <Rating value={4.7} readOnly precision="half" size="lg" aria-label="平均 4.7 星" />
+            <Label>平均分數，使用者無法改</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="❌ 展示平均分時用 interactive"
+          note="使用者以為自己可以改變商品平均分。所有展示用途必須 readOnly。"
+        >
+          <div className="flex flex-col gap-2 w-[300px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-secondary font-medium">商品平均分</div>
+            <Rating defaultValue={4.7} precision="half" size="lg" aria-label="誤用範例" />
+            <Label warn>使用者會以為點下去能改平均分 → 改 readOnly</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="Rating — 離散 1–5 分評分"
+          note="星等是使用者對商品 / 服務的 graded 量化評價。5 顆是世界級共識（超過 7 使用者無法快速掃視）。"
+        >
+          <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-secondary font-medium">商品評分</div>
+            <Rating value={4.7} readOnly precision="half" size="md" aria-label="4.7 星" />
+            <Label>離散 tier:1 / 2 / 3 / 4 / 5(或 0.5 step)</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="Slider — 連續數值（非 1–5 評分）"
+          note="音量、亮度、價格區間、百分比調整。Slider 是連續值，Rating 是離散 tier——完全不同語意。"
+        >
+          <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-secondary font-medium">音量（連續值）</div>
+            <Slider defaultValue={[65]} max={100} aria-label="音量" />
+            <Label>0–100 任何值都合理 → 用 Slider，不是 Rating</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="Tag — 靜態分類標記（非量化）"
+          note="「熱門」「Beta」「NEW」是 categorical label，不是 1–5 評分。分類標籤用 Tag——Badge 是通知計數 / 紅點指示器（badge.spec：不用 Badge 做分類標籤）。Tag 傳達「屬於哪類」，Rating 傳達「值多少分」。"
+        >
+          <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-secondary font-medium">商品標記</div>
+            <div className="flex items-center gap-2">
+              <Tag color="blue">熱門</Tag>
+              <Tag color="neutral">Beta</Tag>
+            </div>
+            <Label>分類 / 狀態標記 → Tag（通知計數才用 Badge），不是 Rating</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="Like / ThumbsUp — 二元喜歡（非 graded）"
+          note="愛心 / 豎拇指是 binary（喜歡 / 不喜歡），不是 1–5 分。用 Button iconOnly + pressed，不用 Rating 換 icon。"
+        >
+          <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-secondary font-medium">收藏（binary）</div>
+            <div className="flex items-center gap-2">
+              <Button variant="text" iconOnly startIcon={Heart} aria-label="收藏" />
+              <Button variant="text" iconOnly startIcon={ThumbsUp} aria-label="喜歡" />
+            </div>
+            <Label>二元切換 → Button + pressed，不是 Rating 換 Heart icon</Label>
+          </div>
+        </Rule>
+      </div>
+    </div>
+    )
+  },
+}
+
+export const PrecisionChoice: Story = {
+  name: '精度選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="full — 送出評分（使用者給分當下）"
+        note="送出流程要「決斷」，整星最清晰。Yelp / Google Reviews / Amazon 的送出表單都是整星——使用者不必在 4 和 4.5 之間猶豫。"
+      >
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <div className="text-caption text-fg-secondary font-medium">為這次服務評分</div>
+          <Rating defaultValue={0} precision="full" size="lg" aria-label="送出評分" />
+          <Label>step = 1，可選值：1 / 2 / 3 / 4 / 5</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="half — 展示平均分（顯示小數）"
+        note="平均分必定有小數（4.7、3.2、4.5），整星無法表達。半星用 overflow-hidden 疊一個 filled 在 empty 上，呈現「4.5 看起來就是 4 顆半星」。"
+      >
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <div className="text-caption text-fg-secondary font-medium">商品平均分</div>
+          <div className="flex items-center gap-2">
+            <Rating value={4.7} readOnly precision="half" size="lg" aria-label="平均 4.7" />
+            <span className="text-body text-fg-secondary">4.7</span>
+            <span className="text-caption text-fg-muted">(12,843)</span>
+          </div>
+          <Label>顯示 4.7 需要半星精度</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 送出表單用 half — 使用者猶豫症"
+        note="半星給送出評分會讓使用者陷入「4 跟 4.5 差在哪」的猶豫。送出 = full；半星只用於展示。"
+      >
+        <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
+          <div className="text-caption text-fg-secondary font-medium">送出評分 — 誤用 half</div>
+          <Rating defaultValue={0} precision="half" size="lg" aria-label="誤用範例" />
+          <Label warn>使用者要在 10 個刻度裡選 → 改 full（5 個整星）</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const YellowStarConvention: Story = {
+  name: '為什麼用黃色',
+  render: () => (
+    <div>
+      <Rule
+        title="黃星 = 世界級 convention，破壞 = 破壞使用者直覺"
+        note="黃 / 金色星是星級評分最通用的視覺慣例——Amazon 商品評分、Google 地點評分都用金黃星，使用者的視覺記憶早已把「黃星 = 評分」綁定。換成品牌 primary 色（藍 / 綠 / 紫）會讓使用者多花一瞬間「這是什麼？」，這一瞬間就是設計 bug。（少數平台改用自家色：Yelp 紅星、Tripadvisor 綠色圓點 bubble——但黃 / 金星仍是跨平台最通用的星級評分色。）"
+      >
+        <div className="flex flex-col gap-2">
+          <Rating value={4.5} readOnly precision="half" size="lg" aria-label="標準黃星" />
+          <Label>✅ `var(--warning)` = yellow-6 — 世界級 convention</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="填色 = 黃，空色 = 灰"
+        note="空星用灰（`--divider`，= `--color-neutral-4`）不用黃的淺色（yellow-2）——空星要表達「未選」不是「弱黃選」。灰色是跨系統的「empty / disabled」通用語。"
+      >
+        <div className="flex flex-col gap-2">
+          <Rating value={3.5} readOnly precision="half" size="lg" aria-label="黃填灰空" />
+          <Label>✅ filled = `--warning`，empty = `--divider`（= `--color-neutral-4`）</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 不要換成品牌 primary 色"
+        note="Rating 是 evaluation convention color，跟 status color 共用 `--warning` 色相但語境不同——這是 documented 例外（見 color.spec.md）。不要為了『跟品牌一致』把 Rating 改藍 / 改綠，使用者不會認得。"
+      >
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-2">
+            <div style={{ color: 'var(--primary)' }} className="inline-flex">
+              <Rating value={4.5} readOnly precision="half" size="lg" aria-label="誤用範例" icon={Star} />
+            </div>
+          </div>
+          <Label warn>藍星讓使用者猶豫「這是什麼」→ 一瞬間流失 = 設計 bug。（上例外層雖掛 color: var(--primary)，渲染仍是黃星——星色由 rating.tsx fill 硬綁 --warning，非 currentColor，機械保證此誤用做不出來）</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Rating/rating.spec.md

@@ -1,6 +1,6 @@
 ---
 component: Rating
-family: 4
+family: self-contained
 variants: {}
 sizes: {}
 traits:
@@ -11,15 +11,13 @@ benchmark:
   - MUI Rating: github.com/mui/material-ui/tree/master/packages/mui-material/src/Rating
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # Rating 設計原則
 
 ## 定位
 
 Rating 是**離散 1–5 分評分元件**——使用者對商品、服務、體驗給出 1 到 max（預設 5）分的星等，或將已提交的平均分數唯讀展示。
 
-**實作基礎**：自建，無 shadcn 核心或 Radix primitive 對應（shadcn 不提供 Rating，Ant Design `<Rate>` / Material `<Rating>` 為世界級對照）。內部以 lucide-react `Star` 為預設 icon，外層 `role="slider"` / `role="img"` 依 `readOnly` 切換。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**實作基礎**：自建的離散星等控件。內部以 lucide-react `Star` 為預設 icon，外層 `role="slider"` / `role="img"` 依互動性切換(`isInteractive = !readOnly && !disabled && !loading`,`rating.tsx` — disabled / loading 也切 `role="img"` 並摘除 slider aria / tabIndex)。
 
 **Layout Family**:非 4-Family Model —— **self-contained primitive**(獨立視覺,無 slot 結構,類似 Switch / Checkbox / Badge / CircularProgress)。
 
@@ -36,7 +34,7 @@ Rating 是**離散 1–5 分評分元件**——使用者對商品、服務、
 
 | 情境 | 改用 | 原因 |
 |------|------|------|
-| 純資訊標記（「熱門」「Beta」「新品」）| `Badge` | Rating 是量化 1–5 分，不是分類標籤 |
+| 純資訊標記（「熱門」「Beta」「新品」）| `Tag` | Rating 是量化 1–5 分，不是分類標籤;文字分類標記走 Tag(Badge 僅 count/dot 兩模式,無文字承載) |
 | 非 1–5 的連續數值（音量、亮度、價格範圍）| `Slider` | Rating 是離散 tier，Slider 是連續值 |
 | 二元喜歡 / 不喜歡（thumbs up/down、like）| `Switch` 或自組 icon button | Like 是 binary，Rating 是 graded 1–5 |
 | 多維度評比（服務 / 品質 / 速度 各 5 分）| 自組多個 Rating 縱向排列 | 單一 Rating 只表達單一維度 |
@@ -53,10 +51,11 @@ Rating 是**離散 1–5 分評分元件**——使用者對商品、服務、
 | `defaultValue` | `number` | `0` | uncontrolled 預設值 |
 | `onChange` | `(value: number) => void` | — | 評分改變 callback |
 | `max` | `number` | `5` | 滿分星數（世界級慣例 = 5，超過 7 會讓使用者無法快速掃視） |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸。standalone 展示建議 `xs`(24px,對齊 Avatar/Tag sm);Field 內跟 Field size 傳 sm/md/lg |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'xs'`（standalone）/ 跟隨 Field size（Field 內）| 尺寸。未傳 size 時:standalone（無 Field context）預設 `xs`(container 24 / icon 20,對齊 Avatar/Tag sm);Field 內跟 Field size(sm/md/lg) |
 | `precision` | `'full' \| 'half'` | `'full'` | 整星 or 半星 |
 | `readOnly` | `boolean` | `false` | 唯讀展示（不響應 hover / click / 鍵盤） |
 | `disabled` | `boolean` | `false` | 完全停用 |
+| `loading` | `boolean` | `false` | 暫時性等待(fetch / save in flight)——視覺同 disabled(composite 整塊 dim)、`aria-busy`;詳「Loading canonical」段 |
 | `icon` | `LucideIcon` | `Star` | 自訂 icon（極少用；禁止換成 Heart / ThumbsUp，見禁止事項） |
 | `aria-label` | `string` | — | `readOnly` 時必填（例：「平均評分 4.7 星，共 5 星」） |
 
@@ -71,13 +70,13 @@ Rating 是**離散 1–5 分評分元件**——使用者對商品、服務、
 | `md` | 32px(`h-field-md`) | 24px | **Field 預設**。一般表單評分欄位 | field md |
 | `lg` | 36px(`h-field-lg`) | 24px | 送出評分的 review form、強調的主 CTA 區塊 | field lg |
 
-### Standalone vs Field 尺寸選擇(canonical)
+### 為什麼不 default md — Standalone vs Field 尺寸選擇(canonical)
 
-- **Standalone 展示**(非 Field 內):用 **`xs`**(container 24 / icon 20)——對齊 Avatar sm 20px / Tag sm;Airbnb / Yelp 商品卡星星亦此大小 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Standalone 展示**(非 Field 內):用 **`xs`**(container 24 / icon 20)——對齊 Avatar sm 20px / Tag sm，讓商品卡與清單 row 的身分視覺量體一致。
 - **Field 內**(`<Field>` 表單內當 control):跟 Field size 對應傳 sm/md/lg(Field 預設 md)
-- 世界級對照:Material Rating standalone ≈ 24dp;Ant Rate 在 Form 內跟 Form itemSize。兩種 context 分開設計,不強求單一預設 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- Standalone 與 Field 是兩種 context：前者以清單掃視為主，後者必須跟表單列高對齊，因此不強求單一預設尺寸。
 
-### Icon 尺寸對齊 **Avatar inline**,不對齊 icon tier(2026-04-21 AR48 canonical)
+### 為什麼不完全對齊 icon tier — Icon 尺寸對齊 **Avatar inline**(2026-04-21 AR48 canonical)
 
 Rating 的 **container 高度消費 `--field-height-*` token**(sm=28 / md=32 / lg=36),讓它可以與 Input / Select / NumberInput / Button 等 field-height family 元件並排時 row-align 一致。
 
@@ -89,22 +88,25 @@ Rating 的 **container 高度消費 `--field-height-*` token**(sm=28 / md=32 / l
 | md | **24px** ← Avatar | 24px | 16px | Avatar |
 | lg | **24px** ← Avatar | 24px | 20px | Avatar |
 
-**為什麼對齊 Avatar 不對齊 icon tier**:
-
-1. **視覺份量**:Rating 的「一顆星」是 **filled shape**(整個 icon 面積都是重量),不像純 outline icon 靠 stroke。跟 filled identity 元件(Avatar)同尺寸才能在 row 裡 visual weight 對齊。
-2. **語意**:Rating 是「主要資料視覺」(一顆星 = 一個資料點),不是次要 affordance。次要 affordance(如 Input 的 startIcon、Button iconOnly)才走 icon tier(16/16/20)。
-3. **世界級對照**:Ant Rate in Form = 20px(對齊 Form avatar-like components);Material MUI Rating default 24px;Airbnb 商品卡星星 24px。皆走 identity 重量,不走 icon tier。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-4. **歷史錯誤**:早期設 16/16/20 跟 icon tier 齊,但視覺上跟 inline avatar / tag 並排時星星顯得比 avatar「小一號」,失去「這一顆星是資料點」的語感——AR48 修正。
+**為什麼對齊 Avatar 不對齊 icon tier**:星星是 filled shape 的「主要資料視覺」(一顆星 = 一個資料點),與同為 filled 的 identity 元件(Avatar)同尺寸才能在 row 裡 visual weight 對齊;次要 affordance(Input startIcon / Button iconOnly)才走 icon tier(16/16/20)。(歷史:早期 16/16/20 對齊 icon tier,星星比並排 avatar「小一號」——AR48 修正。)
 
 ### 放入 Field 的可組合性
 
 Rating 可直接塞進 `<Field>`(讓使用者能套 Field label / error / hint 共用機制):
 
 ```tsx
-<Field>
+// 驗證時機走 form-validation.spec.md canonical(blur + submit,不在初始 / 操作中即時報錯)
+// —— error 由 form.errors 驅動,非 `rating === 0` 立即判(那會讓初始未觸碰欄位直接紅框)。
+const form = useFormValidation({
+  initialValues: { rating: 0 },
+  validate: { rating: (v) => (v === 0 ? '請至少給 1 星' : undefined) },
+  onSubmit: async (values) => { /* ... */ },
+})
+
+<Field invalid={!!form.errors.rating}>
   <FieldLabel required>整體滿意度</FieldLabel>
-  <Rating value={rating} onChange={setRating} size="md" />
-  {rating === 0 && <FieldError>請至少給 1 星</FieldError>}
+  <Rating {...form.getInputProps('rating')} size="md" />
+  <FieldError>{form.errors.rating}</FieldError>
 </Field>
 ```
 
@@ -127,7 +129,7 @@ Field 高度由 Rating container(`h-field-md`)自然對齊其他 field control,
 
 | Mode | 觸發 | 行為 | ARIA |
 |------|------|------|------|
-| **interactive**（預設）| `readOnly={false} && disabled={false} && loading={false}` | hover 預覽、click 設值、鍵盤 Arrow Left/Right/Up/Down 改值、Focus ring | `role="slider"` + `aria-valuenow/valuemin/valuemax` + `tabIndex={0}` |
+| **interactive**（預設）| `readOnly={false} && disabled={false} && loading={false}` | hover 預覽、click 設值、鍵盤 Arrow Left/Right/Up/Down ± step、Home=0 / End=max、Focus ring | `role="slider"` + `aria-valuenow/valuemin/valuemax` + `aria-valuetext`（`{value} of {max} stars`）+ `tabIndex={0}` |
 | **readOnly** | `readOnly={true}` | 純顯示，不響應 hover / click / 鍵盤 | `role="img"` + `aria-label`（**必填**，給螢幕閱讀器描述分數）|
 | **disabled** | `disabled={true}` | 不響應，視覺淡化（`opacity-disabled`）| `aria-disabled="true"` |
 | **loading** | `loading={true}` | 不響應,視覺同 disabled(uniform dim)——但語義是「正在取得既有評分 / 正在儲存」,非永久不可互動 | `aria-busy="true"`(screen reader 宣告「忙碌中」) |
@@ -152,20 +154,20 @@ API:`loading?: boolean` prop(對齊 `../Field/field-controls.spec.md` Field 家
 
 | Role | Token | 色值（light） | 說明 |
 |------|-------|--------------|------|
-| Filled star | `var(--warning)` | yellow-6 | 世界級黃星 convention（Amazon / Yelp / Google / Shopify / Airbnb 都是黃）| <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-| Empty star | `var(--color-neutral-4)` | 中灰 | 未填的輪廓色，與 disabled / empty state 同級 |
-| Hover 放大 | `scale-110` + `transition-transform` | — | interactive 時 hover 單顆星放大 10%，給予 preview 回饋 |
+| Filled star | `var(--warning)` | yellow-6 | 本 DS 評分語意的固定黃色，不隨品牌 primary 色變動 |
+| Empty star | `var(--divider)` | 中灰（= `--color-neutral-4`）| 未填的輪廓色;借 `--divider` semantic alias(neutral-4,user 2026-05-09 拍板),與分隔線同級的 muted-fill |
+| Hover 預覽 | 改 `fill`（不改尺寸） | — | interactive 時 hover 把游標所在星之前（含）的星填色預覽，給予 preview 回饋；星星尺寸不變 |
 | Focus ring | `ring-2 ring-ring ring-offset-2` + `rounded-md` | — | 鍵盤 focus 時整個 Rating 容器顯示 focus ring（**per-star 無 ring / border / outline**——focus 視覺由 parent container 統一承擔）|
 | Gap between stars | `gap-1` | 4px | 五顆星之間的間距，不隨 size 變化 |
 | Disabled | `opacity-disabled` + `pointer-events-none` | — | 整體降透明度，阻擋所有事件 |
 
 ### Star icon 無 stroke outline
 
-Star icon 渲染時明確設 `stroke="none"`(Lucide Star 預設有 1.5px outline stroke,保留會讓 filled 星星多一層深色 outline,破壞純 fill-only shape canonical)。**Rating 是純 fill-only shape**,不保留 outline——對齊 Ant Rate / Material MUI Rating 的世界級慣例。Empty star 靠 `--color-neutral-4` 的 fill 本身與 canvas 對比區隔,不需 outline 補視覺。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Star icon 渲染時明確設 `stroke="none"`(Lucide Star 預設 `stroke="currentColor"` 帶輪廓,strokeWidth 預設 2,保留會讓 filled 星星多一層深色 outline,破壞純 fill-only shape canonical)。**Rating 是純 fill-only shape**,不保留 outline。Empty star 靠 `--divider`(= `--color-neutral-4`)的 fill 本身與 canvas 對比區隔,不需 outline 補視覺。
 
 ### 為什麼用 `--warning`（黃色）而不用 `--primary`
 
-黃星是**世界級 convention**——Amazon / Yelp / Google Reviews / Shopify / Airbnb / TripAdvisor 全部用黃。使用者的視覺記憶已經把「黃星 = 評分」綁定，換成品牌 primary 色（藍、綠、紫）會破壞這個直覺。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+黃星是本 DS 的評分語意 canonical。使用者在同一產品內應以相同色相辨識評分，換成品牌 primary 色（藍、綠、紫）會讓評分與一般選取狀態混淆。
 
 `--warning` 在本系統指向 yellow-6，與 Rating **共用色相但語境不同**——evaluation convention color，非 status color。這是 documented 例外（見 `color.spec.md`），不是每個元件都能這樣共用。
 
@@ -173,10 +175,10 @@ Star icon 渲染時明確設 `stroke="none"`(Lucide Star 預設有 1.5px outline
 
 ## A11y 預設
 
-- **interactive**：`role="slider"` + `aria-valuenow={value}` + `aria-valuemin={0}` + `aria-valuemax={max}` + `tabIndex={0}`，鍵盤 Arrow Left/Right/Up/Down 改值（precision=half 時 step=0.5，否則 step=1）
-- **readOnly**：`role="img"` + `aria-label`（**必填**），例：`aria-label="平均評分 4.7 星，共 5 星"`。無 tabIndex
+- **interactive**：`role="slider"` + `aria-valuenow={value}` + `aria-valuemin={0}` + `aria-valuemax={max}` + `aria-valuetext={`{value} of {max} stars`}` + `tabIndex={0}`，鍵盤 Arrow Left/Right/Up/Down ± step（precision=half 時 step=0.5，否則 step=1）；Home = 0；End = max（完整 WAI-ARIA slider keyboard pattern）
+- **readOnly**：`role="img"` + accessible name。`Field` 內由 `aria-labelledby` 自動指向 `FieldLabel`（免填 `aria-label`）；standalone（無 Field）時 `aria-label` 必填，例：`aria-label="平均評分 4.7 星，共 5 星"`。無 tabIndex
 - **disabled**：`aria-disabled="true"` + `pointer-events-none`
-- **單顆星** `aria-hidden`：所有內部 `<button>`（包含 half-precision 的兩個 hover zone）都是 `aria-hidden` 不干擾螢幕閱讀器，父層 role 獨自表達語意
+- **單顆星** `aria-hidden`：內部點擊目標是 `<span role="presentation" aria-hidden>`（非 interactive element，避免與外層 `role="slider"` 形成 axe nested-interactive 違規，2026-04-25 修正；含 half-precision 的兩個 hover zone）都不干擾螢幕閱讀器，父層 role 獨自表達語意
 
 ---
 
@@ -193,10 +195,20 @@ Star icon 渲染時明確設 `stroke="none"`(Lucide Star 預設有 1.5px outline
 
 ---
 
+## 邊界案例
+
+- **value = 0 / 未評分**:全空星照常渲染(`--divider` fill),不做特殊 empty state。
+- **超界 value**:渲染端每顆星 fill ratio 自動 clamp 0–1(`> max` 全滿、`< 0` 全空),鍵盤增減恆 clamp 0–max(tsx)。
+- **max 上限**:預設 5(世界級慣例,見 Props 表);**不設超過 7**,原因見「禁止事項」。
+- **Disabled / Loading**:整塊 dim(`opacity-disabled`),兩者視覺同、語義與 ARIA 不同 — 見「Interactive vs ReadOnly」表 +「Loading canonical」段。
+- **Dark mode**:`--warning` / `--divider` semantic token 自動 adapt,Rating 不 own dark token。
+
+---
+
 ## 相關
 
 - **`Slider`** — 連續數值選擇（0–100、音量、亮度、價格區間）。Rating vs Slider 分界：離散 tier = Rating，連續值 = Slider
-- **`Badge`** — 靜態分類標記（「熱門」「Beta」「NEW」）。Rating 是量化，Badge 是分類
+- **`Tag`** — 靜態文字分類標記（「熱門」「Beta」「NEW」）。Rating 是量化,Tag 是文字分類(Badge 僅 count/dot,不承載文字)
 - **`Switch`** — 二元 on/off。Rating 是 graded，Switch 是 binary
 - **`Button iconOnly + pressed={liked}`** — 愛心 / like 的正確實作
 - **Color token 例外** — `color.spec.md`「共用 `--warning` 色相但語境不同」段落

package/src/components/Rating/rating.stories.tsx

@@ -0,0 +1,119 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { Rating } from './rating'
+import { Button } from '@/design-system/components/Button/button'
+import { Field, FieldLabel, FieldError } from '@/design-system/components/Field/field'
+
+const meta: Meta<typeof Rating> = {
+  title: 'Design System/Components/Rating/展示',
+  component: Rating,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '用於讓使用者給出離散星等，或唯讀顯示已提交的個人／平均評分。連續數值改用 Slider，二元喜好改用 Switch 或 icon button，完成進度改用 ProgressBar / CircularProgress。',
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Rating>
+
+/* ── 商品列表的平均分（Amazon / Shopify 風格）── */
+export const ReadOnlyProductRating: Story = {
+  name: '商品列表平均分',
+  render: () => (
+    <div className="flex flex-col gap-4 w-[420px]">
+      {[
+        { name: 'AirPods Pro （第二代）', rating: 4.7, count: 12843 },
+        { name: 'Kindle Paperwhite', rating: 4.5, count: 8921 },
+        { name: 'Anker 快充行動電源 20000mAh', rating: 4.8, count: 23104 },
+        { name: 'UNIQLO 輕量羽絨外套', rating: 4.2, count: 592 },
+      ].map((p) => (
+        <div key={p.name} className="flex items-center gap-3 p-3 border border-border rounded-md bg-surface">
+          <div className="flex-1 min-w-0">
+            <div className="text-body font-medium truncate">{p.name}</div>
+            <div className="flex items-center gap-2 mt-1">
+              <Rating
+                value={p.rating}
+                readOnly
+                precision="half"
+                size="xs"
+                aria-label={`平均評分 ${p.rating} 星，共 5 星,${p.count} 則評論`}
+              />
+              <span className="text-caption text-fg-secondary">{p.rating}</span>
+              <span className="text-caption text-fg-muted">({p.count.toLocaleString()})</span>
+            </div>
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/* ── 送出評分 flow（Yelp / Google Reviews 風格）── */
+export const InteractiveReview: Story = {
+  name: '送出評分流程',
+  render: () => {
+    const ReviewForm = () => {
+      const [rating, setRating] = useState(0)
+      const labels = ['', '很差', '不佳', '普通', '不錯', '很棒']
+      return (
+        <div className="flex flex-col gap-4 w-[420px] p-5 border border-border rounded-md bg-surface">
+          <div className="text-body font-semibold">為這次服務評分</div>
+          <p className="text-caption text-fg-muted">
+            訂單編號 #A-2026-0412 · 完成於 2026/04/15
+          </p>
+          <div className="flex items-center gap-3 py-2">
+            <Rating
+              value={rating}
+              onChange={setRating}
+              size="lg"
+              precision="full"
+              aria-label="為這次服務給 1 到 5 星"
+            />
+            <span className="text-body text-fg-secondary min-w-[48px]">
+              {labels[rating] ?? ''}
+            </span>
+          </div>
+          <div className="flex items-center gap-2 justify-end pt-1">
+            <Button variant="primary" size="md" disabled={rating === 0}>
+              送出評分
+            </Button>
+          </div>
+        </div>
+      )
+    }
+    return <ReviewForm />
+  },
+}
+
+/* ── Field 包裝(Rating 可塞進 Field wrapper)── */
+export const InField: Story = {
+  name: '包在 Field 內',
+  render: () => {
+    const [rating, setRating] = useState(0)
+    return (
+      <div className="w-[420px]">
+        <Field>
+          <FieldLabel required>整體滿意度</FieldLabel>
+          <Rating
+            value={rating}
+            onChange={setRating}
+            size="md"
+            aria-label="整體滿意度評分"
+          />
+          {rating === 0 && <FieldError>請至少給 1 星</FieldError>}
+        </Field>
+      </div>
+    )
+  },
+}
+
+/* @story-history: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。 */
+// @story-history: Disabled retired per audit Dim 24 —
+//   disabled 覆蓋已由 anatomy.stories.tsx StateBehavior 的 disabled live case
+//   (value=4 disabled)owns;對齊 Checkbox / Switch / RadioGroup 同 Family
+//   已 retire 的獨立 Disabled story,不重複展示同一 state。