@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

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

@@ -12,7 +12,7 @@ const meta: Meta<typeof Rating> = {
     docs: {
       description: {
         component:
-          '用於讓使用者給出離散星等，或唯讀顯示已提交的個人／平均評分。連續數值改用 Slider，二元喜好改用 Switch 或 icon button，完成進度改用 ProgressBar / CircularProgress。',
+          '讓使用者點一顆整星給分；已提交的個人或平均評分一律用唯讀精簡版「★ 4.7 (12,843)」顯示。連續數值改用 Slider，二元喜好改用 Switch 或 icon button，完成進度改用 ProgressBar / CircularProgress。',
       },
     },
   },
@@ -21,7 +21,7 @@ const meta: Meta<typeof Rating> = {
 export default meta
 type Story = StoryObj<typeof Rating>
 
-/* ── 商品列表的平均分（Amazon / Shopify 風格）── */
+/* ── 商品列表的平均分（Amazon / Shopify 風格）——唯讀精簡版,評論數走 count ── */
 export const ReadOnlyProductRating: Story = {
   name: '商品列表平均分',
   render: () => (
@@ -35,17 +35,14 @@ export const ReadOnlyProductRating: Story = {
         <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>
+            <Rating
+              value={p.rating}
+              count={p.count}
+              readOnly
+              size="sm"
+              className="mt-1"
+              aria-label={`平均評分 ${p.rating} 星，共 5 星，${p.count.toLocaleString()} 則評論`}
+            />
           </div>
         </div>
       ))}
@@ -53,7 +50,7 @@ export const ReadOnlyProductRating: Story = {
   ),
 }
 
-/* ── 送出評分 flow（Yelp / Google Reviews 風格）── */
+/* ── 送出評分 flow（Yelp / Google Reviews 風格）——只有整顆 ── */
 export const InteractiveReview: Story = {
   name: '送出評分流程',
   render: () => {
@@ -71,7 +68,6 @@ export const InteractiveReview: Story = {
               value={rating}
               onChange={setRating}
               size="lg"
-              precision="full"
               aria-label="為這次服務給 1 到 5 星"
             />
             <span className="text-body text-fg-secondary min-w-[48px]">

package/src/components/Rating/rating.tsx

@@ -3,6 +3,8 @@ import * as React from 'react'
 import { Star, type LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode } from '@/design-system/components/Field/field-context'
+import { fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 
 /**
  * Rating — 星星評分元件
@@ -20,12 +22,10 @@ import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useRes
  * 空色用 `var(--divider)`(neutral-4 借 divider semantic alias;灰色;與 disabled/empty 同級)。
  *
  * ── 互動 ──
- * interactive(預設):hover 預覽、click 設值、keyboard Left/Right 改值
- * readOnly:純顯示,不響應 hover / click
- *
- * ── 精度 ──
- * precision="full"(預設) — 整星(1, 2, 3, 4, 5)
- * precision="half" — 半星(0.5, 1, 1.5, 2, 2.5, ..., 5)
+ * interactive(預設):只有整顆星 —— hover 預覽、click 設值、keyboard ±1
+ * readOnly:一律精簡版「★ 4.7 (12,843)」—— 一顆實心星 + 數值 + 選填評論數,不畫五顆星
+ *   (user 2026-09-26:「唯讀直接一律給精簡版就好吧？搞得這麼麻煩幹嘛？其他照你建議」;
+ *   rating.spec.md「Interactive vs ReadOnly」)
  */
 
 // ── Icon size canonical(2026-04-21 AR48 修正)──
@@ -34,25 +34,18 @@ import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useRes
 // 理由:
 // - 星星是 filled shape(解析整個 icon 是重量感的一部分),不像純 outline icon 靠 stroke
 // - Field 內 Rating 跟 Avatar / Tag 並排時視覺份量要對齊,否則 row height 一致但 icon 看起來比重量不對
-// - 世界級對照:Ant Rate in Form = 20px、Material MUI Rating fontSize=inherit 預設約 24、Airbnb 評分星 24px
 //
-// 因此 Field 內 Rating icon size 對齊 **item-anatomy inline Avatar sizes**:sm=20 / md=24 / lg=24。
+// 因此可以點的星對齊 **item-anatomy inline Avatar sizes**:sm=20 / md=24 / lg=24。
 // 非 icon tier(16/16/20)——star 不是次要 affordance icon,它是主要資料視覺。
 //
-// Container 高度仍對齊 `--field-height-*`(sm=28 / md=32 / lg=36),讓 Rating 可與其他
-// field-height family 元件(Input / Select)並排時 row height 對齊。
-//
-// ── 使用情境 ──
-// - **Standalone**(獨立展示評分,如商品卡 / 評論)→ 預設 `xs`(container 24,icon 20,
-//   對齊 Avatar sm 20px;iOS HIG / Airbnb 商品卡星星 20-24px)
-// - **Field 內**(表單評分欄位)→ 跟 Field 尺寸對齊(sm=20 / md=24 / lg=24,default md)
-const SIZE_PX = { xs: 20, sm: 20, md: 24, lg: 24 } as const
-const CONTAINER_HEIGHT: Record<'xs' | 'sm' | 'md' | 'lg', string> = {
-  xs: 'h-field-xs',
-  sm: 'h-field-sm',
-  md: 'h-field-md',
-  lg: 'h-field-lg',
-}
+// ── 高度模型(2026-09-27;user:「我反而覺得其跟 switch 和 checkbox 十分接近的邏輯」)──
+// 元件只有內容高、不吃 `--field-height-*` 容器:可以點的評分根高 = 星高;唯讀精簡版 = 星與文字行高的較大者。
+// 列高由所在的列供給 —— Field 控件槽 `min-h-field-* + items-center`(field.tsx)、表格格子、列的 items-center。
+// 世界級六家(MUI / Ant / Fluent / Mantine / Chakra / PrimeReact)評分根容器都 hug 星、表單對齊交給表單列;
+// 之前自己吃容器會把 Field 外的列撐高(商品卡 24 容器實佔 26px),對命中零幫助。出處與實量:rating.spec.md「Size」。
+// xs 於同日退役(可以點的 xs 與 sm 只差容器;唯讀 xs 是 AI 自訂、無 user 同意、產品零處)。
+type RatingSize = 'sm' | 'md' | 'lg'
+const SIZE_PX: Record<RatingSize, number> = { sm: 20, md: 24, lg: 24 }
 
 export interface RatingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
   /** 當前評分(0 ~ max) */
@@ -63,12 +56,12 @@ export interface RatingProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   onChange?: (value: number) => void
   /** 滿分(預設 5) */
   max?: number
-  /** 尺寸。standalone 建議 xs(24px);Field 內跟隨 Field size 傳 sm/md/lg */
-  size?: 'xs' | 'sm' | 'md' | 'lg'
-  /** 精度:full = 整星,half = 半星 */
-  precision?: 'full' | 'half'
-  /** 唯讀(無 hover / click 響應) */
+  /** 尺寸。預設 md、元件只有內容高(同 Switch / Checkbox);解析序同 Input 類:明傳 > Field 明確指定 > Field 預設 md > 表格 surface size > md。沒有 xs(2026-09-27 退役) */
+  size?: RatingSize
+  /** 唯讀:顯示精簡版「★ 數值 (評論數)」,不響應 hover / click / 鍵盤 */
   readOnly?: boolean
+  /** 唯讀時顯示在數值後的評論數(千分位);interactive 時不顯示 */
+  count?: number
   /** 完全停用 */
   disabled?: boolean
   /**
@@ -97,8 +90,8 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
       onChange,
       max = 5,
       size: sizeProp,
-      precision = 'full',
       readOnly: readOnlyProp = false,
+      count,
       disabled: disabledProp,
       loading = false,
       icon: Icon = Star,
@@ -107,11 +100,6 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
     },
     ref,
   ) => {
-    // Context-aware default size(AR31 canonical):
-    //   - Field 內(有 FieldContext.size) → 跟 Field size 對齊(sm / md / lg)
-    //   - Standalone(無 Field context) → default `xs`(24px,對齊 Avatar / Tag sm / iOS HIG standalone)
-    // consumer 可傳 size 顯式 override。世界級對照:Material Rating standalone 24dp、
-    // Ant Rate in Form 跟 Form.itemSize,standalone 24px。
     // 2026-07-18 決策4:max dev-warn(spec canonical ≤7;維持 number 型別不收窄,對齊 MUI Rating.max)。
     if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production' && (max > 7 || max < 1 || Math.round(max) !== max)) {
       console.warn(`[DS] Rating max ${max} 超出 canonical 範圍 1-7(或非整數)。建議 ≤7 顆星(對齊世界級 review-stars)。`)
@@ -119,19 +107,71 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
     const fieldCtx = useFieldContext()  // 保留:aria-labelledby 用 fieldCtx.labelId
     // 2026-06-08 SSOT:<Field disabled> cascade(原 isInteractive 只看 local disabled prop)
     const disabled = useResolvedFieldDisabled(disabledProp)
-    // <Field mode="readonly"> cascade(2026-06-12 補):Rating 的 readonly 呈現 = 星星本身
-    // (星星即值語言,role=img,全業界 review-stars canonical)——不包灰框,只鎖互動。
+    // <Field mode="readonly"> cascade(2026-06-12 補):Rating 的 readonly 呈現 = 唯讀精簡版「★ 數值」
+    // (2026-09-26 起;role=img)——不包灰框,只鎖互動。
     const resolvedMode = useResolvedFieldMode({ mode: undefined, disabled, readOnly: readOnlyProp })
     const readOnly = readOnlyProp || resolvedMode === 'readonly'
-    const size = useResolvedFieldSize<'xs' | 'sm' | 'md' | 'lg'>(sizeProp, 'xs')  // SSOT:統一 size resolution(Rating default 'xs')
+    // 尺寸解析(field-context useResolvedFieldSize):prop > Field 明確指定的 size > Field 預設 md > 表格 surface size > md。
+    // 不傳 fallback:傳了會排在 Field 預設與 surface size 前面(那是 Switch / Checkbox 的 'md' 寫法,表格格子就接不到 surface size);
+    // Rating 在表格格子裡要跟表格(rating.spec.md「Size」:使用時機 = 跟所在容器)。
+    // 執行期傳 'xs'(型別已拒,JS consumer / 舊 d.ts 仍可能傳)→ 映到 sm 並 dev-warn(靜默映射 = 零訊號);閘 scripts/rating-field-size-invariant.mjs(meta test scripts/test-rating-field-size-invariant.mjs)。
+    const legacyXs = (sizeProp as string | undefined) === 'xs'
+    if (legacyXs && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+      console.warn('[DS] Rating size="xs" 已於 2026-09-27 退役(改為 sm;元件只有內容高,列高由所在的列供給)。')
+    }
+    const size = useResolvedFieldSize<RatingSize>(legacyXs ? 'sm' : sizeProp)
     const [internalValue, setInternalValue] = React.useState(defaultValue)
     const [hoverValue, setHoverValue] = React.useState<number | null>(null)
+    const valueTextId = React.useId()
     const isControlled = value !== undefined
     const currentValue = isControlled ? value : internalValue
-    const displayValue = hoverValue ?? currentValue
+    // 可以點的評分只有整顆:外部給小數時四捨五入成整顆,畫面、鍵盤起點、讀屏念的值三者同一個數
+    // (否則 4.7 按 ← 會變 3.7、讀屏念 3.7 卻畫 4 顆)
+    const wholeValue = Math.max(0, Math.min(max, Math.round(currentValue)))
+    const displayValue = hoverValue ?? wholeValue
     const iconPx = SIZE_PX[size]
     const isInteractive = !readOnly && !disabled && !loading
 
+    // ── 唯讀 = 精簡版「★ 4.7 (12,843)」────────────────────────────────────────
+    // 世界級:Fluent 2 把唯讀拆成 RatingDisplay,`compact`「Renders a single filled star, with the value
+    // written next to it」、`count`「formatted with a thousands separator … displayed next to the value」
+    // (github.com/microsoft/fluentui react-rating `RatingDisplay.types.ts`,2026-09-26 讀 master)。
+    // 本 DS 不另拆元件:唯讀一律走這條,互動才畫五顆星(user 2026-09-26 選的是「唯讀一律精簡版」)。
+    // 星走 icon tier(16 / 16 / 20);星 ↔ 數值的縫三個尺寸都是 gap-1 4px —— Rating 內只有一種縫(可以點的星與星之間也是 4px),
+    // user 2026-09-27 拍板(原話「我覺得星號與文字gap應該跟這個一樣都是4px吧？」→「照你建議」);Fluent 2 RatingDisplay 16px 星 + 12px 字
+    // 亦是 4px、Tag 資料指示器圖示 ↔ 文字 4px。出處、實量與世界級對照見 rating.spec.md「唯讀精簡版」。
+    if (readOnly) {
+      const shown = Math.max(0, Math.min(max, currentValue))
+      return (
+        <div
+          ref={ref}
+          role="img"
+          data-size={size}
+          // Field 內:名稱 = 欄位標籤 + 數值(role=img 的子內容讀屏不念,只指標籤會只聽到「滿意度」聽不到分數);
+          // standalone 沒有 labelId → 走 consumer 的 aria-label(規格必填)
+          aria-labelledby={fieldCtx?.labelId ? `${fieldCtx.labelId} ${valueTextId}` : undefined}
+          aria-disabled={disabled || undefined}
+          aria-busy={loading || undefined}
+          className={cn(
+            // 不換行:星、數值、評論數是同一個值,窄容器裡折行會把整列撐高一倍(lg 實測 48px)。
+            // 高度 = 星與文字行高的較大者(sm/md 21、lg 24),沒有容器;星 ↔ 數值 gap-1(Rating 內只有一種縫)
+            'inline-flex items-center whitespace-nowrap gap-1',
+            fieldDisplayTextClass(size),
+            (disabled || loading) && 'opacity-disabled pointer-events-none',
+            className,
+          )}
+          {...props}
+        >
+          <Icon size={size === 'lg' ? ICON_SIZE.lg : ICON_SIZE.sm} fill={FILL_FILLED} stroke="none" aria-hidden
+            className="shrink-0" style={{ color: FILL_FILLED }} />
+          <span id={valueTextId} aria-hidden className="text-foreground tabular-nums">
+            {formatRatingValue(shown)}
+            {count !== undefined && <span className="text-fg-secondary">{` (${count.toLocaleString()})`}</span>}
+          </span>
+        </div>
+      )
+    }
+
     const setValue = (v: number) => {
       if (!isControlled) setInternalValue(v)
       onChange?.(v)
@@ -139,14 +179,14 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
 
     const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
       if (!isInteractive) return
-      const step = precision === 'half' ? 0.5 : 1
+      const step = 1 // 只有整顆(rating.spec.md「Interactive vs ReadOnly」)
       // Full ARIA slider pattern(WAI-ARIA):Arrow / Home / End 支援 — D4 UX audit 2026-04-22
       if (e.key === 'ArrowRight' || e.key === 'ArrowUp') {
         e.preventDefault()
-        setValue(Math.min(max, currentValue + step))
+        setValue(Math.min(max, wholeValue + step))
       } else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') {
         e.preventDefault()
-        setValue(Math.max(0, currentValue - step))
+        setValue(Math.max(0, wholeValue - step))
       } else if (e.key === 'Home') {
         e.preventDefault()
         setValue(0)
@@ -160,16 +200,18 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
       <div
         ref={ref}
         role={isInteractive ? 'slider' : 'img'}
+        data-size={size}
         // a11y(#30):role=slider 必有 accessible name(WAI-ARIA APG slider pattern)。
         //   Field 內 → 自動 aria-labelledby 指向 FieldLabel 的 id(fieldCtx.labelId,免填);
         //   Standalone → 仍需 consumer 傳 aria-label。對齊 TimePicker / DatePicker 同 canonical
         //   (time-picker.tsx:313 / date-picker.tsx:514:aria-labelledby={fieldCtx?.labelId})。
         //   置於 {...props} 前,consumer 顯式傳的 aria-labelledby 仍可覆寫。
         aria-labelledby={fieldCtx?.labelId}  // 2026-06-12 修:readonly/disabled(role=img)也需 accessible name,labelledby 對 img 合法
-        aria-valuenow={isInteractive ? currentValue : undefined}
+        aria-valuenow={isInteractive ? wholeValue : undefined}
         aria-valuemin={isInteractive ? 0 : undefined}
         aria-valuemax={isInteractive ? max : undefined}
-        aria-valuetext={isInteractive ? `${currentValue} of ${max} stars` : undefined}
+        // 讀屏文字中文(全庫 SR label 中文,2026-07-04;同 spec 唯讀範例「平均評分 4.7 星，共 5 星」的說法)
+        aria-valuetext={isInteractive ? `${wholeValue} 星,共 ${max} 星` : undefined}
         aria-disabled={disabled || undefined}
         // a11y: 刻意不設 aria-readonly — readOnly 時 role=img(axe aria-allowed-attr 禁 img 用 aria-readonly,2026-04-25);
         //       interactive 時 role=slider 但必非 readOnly(isInteractive = !readOnly)。兩 state 皆不該有此屬性,故省略。
@@ -177,40 +219,39 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
         tabIndex={isInteractive ? 0 : undefined}
         onKeyDown={handleKeyDown}
         onMouseLeave={() => setHoverValue(null)}
+        // 星與星之間的縫(`gap-1`;元件只有內容高,沒有上下留白):指標從某顆星移進來時,那顆星的預覽照舊亮著
+        // (只有離開整個元件才收);亮著時在這裡點下去 = 確認正在預覽的值(AI 建議,2026-09-26 列在
+        // 「其餘建議」裡、user 未另提 → 照建議做,AI 判讀;hit-area-canonical.md 滑過原則一-6)。
+        // 點在星上由星自己處理(e.target 是星,不是容器),不會重複送出。
+        onClick={isInteractive ? (e) => {
+          if (e.target === e.currentTarget && hoverValue !== null) setValue(hoverValue)
+        } : undefined}
         className={cn(
-          'inline-flex items-center gap-1',
-          // Container 對齊 field-height family,讓 Rating 可與 Input/Select/Button 並排 row-align
-          CONTAINER_HEIGHT[size],
-          'rounded-md',
-          // disabled 跟 loading 視覺相同(composite uniform dim),semantic 由 aria-disabled / aria-busy 區分
-          (disabled || loading) && 'opacity-disabled pointer-events-none',
+          // 元件只有內容高(= 星高);列高由所在的列供給(見檔頭「高度模型」)。焦點框跟著這個內容盒(rounded-md)
+          'inline-flex items-center gap-1 rounded-md',
+          // 預覽亮著時縫裡點得到 → 縫裡也是手形(與星同一個游標)
+          isInteractive && hoverValue !== null && 'cursor-pointer',
+          // disabled 跟 loading 視覺相同(composite uniform dim),semantic 由 aria-disabled / aria-busy 區分。
+          // 事件仍全部擋在星上(子元素 pointer-events-none;容器此時沒有任何 handler),容器自己留著接指標
+          // 只為了掛禁止符號 —— 容器也 pointer-events-none 的話游標由外層決定,永遠是箭頭
+          //(hit-area-canonical.md 滑過原則一-3「停用的用禁止符號」;field-controls.spec.md「游標指引」)。
+          (disabled || loading) && 'opacity-disabled cursor-not-allowed [&>*]:pointer-events-none',
           className,
         )}
         {...props}
       >
         {Array.from({ length: max }, (_, i) => {
           const starValue = i + 1
-          const fillRatio = Math.max(0, Math.min(1, displayValue - i)) // 0..1
-          const isHalf = precision === 'half' && fillRatio > 0 && fillRatio < 1
-
           return (
             <StarIcon
               key={i}
               Icon={Icon}
               sizePx={iconPx}
-              fillRatio={fillRatio}
-              isHalf={isHalf}
+              // 只有整顆:displayValue 已是整數(wholeValue 四捨五入,同 Zag rating-group 沒開半顆時 `Math.round`)
+              filled={displayValue >= starValue}
               interactive={isInteractive}
-              onHover={(halfFirst) => {
-                if (!isInteractive) return
-                const v = precision === 'half' && halfFirst ? starValue - 0.5 : starValue
-                setHoverValue(v)
-              }}
-              onClick={(halfFirst) => {
-                if (!isInteractive) return
-                const v = precision === 'half' && halfFirst ? starValue - 0.5 : starValue
-                setValue(v)
-              }}
+              onHover={() => { if (isInteractive) setHoverValue(starValue) }}
+              onClick={() => { if (isInteractive) setValue(starValue) }}
             />
           )
         })}
@@ -220,74 +261,47 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
 )
 Rating.displayName = 'Rating'
 
-// ── StarIcon: 單顆星 + half-precision overlay ─────────────────────────────
+// ── StarIcon: 單顆整星(可以點的評分用;唯讀精簡版直接畫一顆實心星)─────────────
 
 interface StarIconProps {
   Icon: LucideIcon
   sizePx: number
-  fillRatio: number // 0..1
-  isHalf: boolean
+  filled: boolean
   interactive: boolean
-  onHover: (halfFirst: boolean) => void
-  onClick: (halfFirst: boolean) => void
+  onHover: () => void
+  onClick: () => void
 }
 
 const FILL_FILLED = 'var(--warning)' // yellow-6 — 黃星 convention
 const FILL_EMPTY = 'var(--divider)' // 灰色空星(neutral-4 借 divider semantic alias,user 2026-05-09 拍板;對齊 Material rgba(0,0,0,0.26) muted-fill canonical)
 
-function StarIcon({ Icon, sizePx, fillRatio, isHalf, interactive, onHover, onClick }: StarIconProps) {
+/** 唯讀數值:整數照原樣,小數取一位(4 → "4"、4.7 → "4.7"、4.25 → "4.3");不走 locale,避免小數點變逗號 */
+function formatRatingValue(value: number): string {
+  return Number.isInteger(value) ? String(value) : (Math.round(value * 10) / 10).toString()
+}
+
+function StarIcon({ Icon, sizePx, filled, interactive, onHover, onClick }: StarIconProps) {
   // a11y(2026-04-25 axe nested-interactive fix):inner 點擊目標改 <span>(非 interactive
   // element),不會跟外層 role='slider' 形成 nested-interactive 違規。鍵盤控制統一在外層
   // slider 的 arrow keys,inner 只處理 mouse click 定位。Ant Rate / Material MUI 同模式。
-  if (!isHalf) {
-    // Full: 一整顆 fill(filled 或 empty)
-    const fill = fillRatio >= 1 ? FILL_FILLED : FILL_EMPTY
-    return (
-      <span
-        role="presentation"
-        onMouseEnter={interactive ? () => onHover(false) : undefined}
-        onClick={interactive ? () => onClick(false) : undefined}
-        className={cn(
-          'inline-flex',
-          interactive ? 'cursor-pointer' : 'cursor-default',
-        )}
-        style={{ color: fill }}
-        aria-hidden
-      >
-        {/* stroke="none" 移除 Lucide Star 預設的 outline stroke(lucide defaultAttributes
-            strokeWidth=2 + stroke=currentColor 會畫輪廓),讓星星是純 fill-only 的 shape——
-            fill 與 outline 同色視覺上仍有亮度差。
-            世界級對照:Ant Rate / Material MUI Rating 皆純 fill,無 outline stroke。*/}
-        <Icon size={sizePx} fill={fill} stroke="none" className="shrink-0" />
-      </span>
-    )
-  }
-
-  // Half: 兩個重疊 icon,左半 filled / 右半 empty + 兩個 hover zone 切半星
+  const fill = filled ? FILL_FILLED : FILL_EMPTY
   return (
-    <span aria-hidden className="relative inline-flex" style={{ width: sizePx, height: sizePx }}>
-      <Icon size={sizePx} fill={FILL_EMPTY} stroke="none" aria-hidden className="absolute inset-0" style={{ color: FILL_EMPTY }} />
-      <span className="absolute inset-0 overflow-hidden" style={{ width: sizePx * fillRatio }}>
-        <Icon size={sizePx} fill={FILL_FILLED} stroke="none" aria-hidden style={{ color: FILL_FILLED }} />
-      </span>
-      {interactive && (
-        <>
-          <span
-            role="presentation"
-            onMouseEnter={() => onHover(true)}
-            onClick={() => onClick(true)}
-            className="absolute inset-y-0 left-0 w-1/2 cursor-pointer"
-            aria-hidden
-          />
-          <span
-            role="presentation"
-            onMouseEnter={() => onHover(false)}
-            onClick={() => onClick(false)}
-            className="absolute inset-y-0 right-0 w-1/2 cursor-pointer"
-            aria-hidden
-          />
-        </>
+    <span
+      role="presentation"
+      onMouseEnter={interactive ? onHover : undefined}
+      onClick={interactive ? onClick : undefined}
+      className={cn(
+        'inline-flex',
+        interactive ? 'cursor-pointer' : 'cursor-default',
       )}
+      style={{ color: fill }}
+      aria-hidden
+    >
+      {/* stroke="none" 移除 Lucide Star 預設的 outline stroke(lucide defaultAttributes
+          strokeWidth=2 + stroke=currentColor 會畫輪廓),讓星星是純 fill-only 的 shape——
+          fill 與 outline 同色視覺上仍有亮度差。
+          世界級對照:Ant Rate / Material MUI Rating 皆純 fill,無 outline stroke。*/}
+      <Icon size={sizePx} fill={fill} stroke="none" className="shrink-0" />
     </span>
   )
 }
@@ -307,7 +321,7 @@ export const ratingMeta = {
   tokens: {
     bg: ['bg-transparent'],
     fg: [],
-    ring: ['ring-ring'],
+    ring: ['--ring'],
   },
 } as const
 

package/src/components/ScrollArea/scroll-area.anatomy.stories.tsx

@@ -445,7 +445,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"詳 `scroll-area.spec.md` 「A11y 預設」段。摘要(Radix primitive + 本 DS 橋接):\n\n-   鍵盤捲動  :本 DS 在 Viewport 加  tabIndex={0}  使其可被鍵盤聚焦(Radix 不自動標 focusable,Safari 尤其需要),聚焦後支援  ArrowUp/Down/Left/Right  /  PageUp/Down  /  Home/End \n-   Focus 可見  :聚焦的 Viewport 顯示 DS focus ring(focus-visible:outline-ring,inset 2px)\n-   Scrollbar 非 tab stop  :scrollbar thumb 不搶焦點,使用鍵盤的使用者透過 viewport 捲動(Radix 內建)\n-   Pointer 支援  :thumb 可拖曳,track 可 click-to-jump(Radix 內建)\n\n本元件已內建 tabIndex 與 focus ring(滿足 axe scrollable-region-focusable);但 Viewport 預設無 role / accessible name——scroll 區域有具體語意(如「留言列表」「程式碼區塊」)時,consumer 應提供 aria-label,否則 SR 只報「可捲動區域」無內容描述;純視覺裝飾容器可省略。"}</p>
+      <p className="whitespace-pre-line">{"詳 `scroll-area.spec.md` 「A11y 預設」段。摘要(Radix primitive + 本 DS 橋接):\n\n-   鍵盤捲動  :本 DS 在 Viewport 加  tabIndex={0}  使其可被鍵盤聚焦(Radix 不自動標 focusable,Safari 尤其需要),聚焦後支援  ArrowUp/Down/Left/Right  /  PageUp/Down  /  Home/End \n-   Focus 可見  :聚焦的 Viewport 顯示 DS 焦點框(focus-visible:focus-ring-inset,往內 2px)\n-   Scrollbar 非 tab stop  :scrollbar thumb 不搶焦點,使用鍵盤的使用者透過 viewport 捲動(Radix 內建)\n-   Pointer 支援  :thumb 可拖曳,track 可 click-to-jump(Radix 內建)\n\n本元件已內建 tabIndex 與 focus ring(滿足 axe scrollable-region-focusable);但 Viewport 預設無 role / accessible name——scroll 區域有具體語意(如「留言列表」「程式碼區塊」)時,consumer 應提供 aria-label,否則 SR 只報「可捲動區域」無內容描述;純視覺裝飾容器可省略。"}</p>
     </div>
   ),
 }

package/src/components/ScrollArea/scroll-area.principles.stories.tsx

@@ -130,8 +130,9 @@ export const UsageGuidance: Story = {
         <div className="w-[320px]">
           <ScrollArea className="h-[180px] border border-border rounded-md bg-surface">
             <div className="p-2">
+              {/* 靜態示意列(無 onClick、不能聚焦)不給 hover 底色(item-anatomy.spec.md「選中 × 互動疊加」:hover 要誠實回答「再點會發生什麼」) */}
               {NOTION_PAGES.map((p) => (
-                <div key={p} className="px-3 py-1.5 text-body hover:bg-neutral-hover rounded">{p}</div>
+                <div key={p} className="px-3 py-1.5 text-body">{p}</div>
               ))}
             </div>
           </ScrollArea>
@@ -169,8 +170,9 @@ export const UsageGuidance: Story = {
           <ScrollArea className="h-[220px] border border-success/40 rounded-md bg-surface">
             <div className="p-3">
               <div className="text-body font-medium mb-2">單層 ScrollArea</div>
+              {/* 靜態示意列不給 hover 底色(同上) */}
               {NOTION_PAGES.map((p) => (
-                <div key={p} className="px-2 py-1.5 text-body hover:bg-neutral-hover rounded">{p}</div>
+                <div key={p} className="px-2 py-1.5 text-body">{p}</div>
               ))}
             </div>
           </ScrollArea>
@@ -193,8 +195,9 @@ export const OrientationChoice: Story = {
         <div className="w-[280px]">
           <ScrollArea className="h-[180px] border border-border rounded-md bg-surface">
             <div className="p-2">
+              {/* 靜態示意列(無 onClick、不能聚焦)不給 hover 底色(item-anatomy.spec.md「選中 × 互動疊加」:hover 要誠實回答「再點會發生什麼」) */}
               {NOTION_PAGES.map((p) => (
-                <div key={p} className="px-3 py-1.5 text-body hover:bg-neutral-hover rounded">{p}</div>
+                <div key={p} className="px-3 py-1.5 text-body">{p}</div>
               ))}
             </div>
           </ScrollArea>

package/src/components/ScrollArea/scroll-area.spec.md

@@ -101,7 +101,7 @@ ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、
 Radix primitive + 本 DS a11y 橋接:
 
 - **鍵盤捲動**:本 DS 在 Viewport 加 `tabIndex={0}`(預設)使其可被鍵盤聚焦(Radix 不自動把 scroll container 標 focusable,Safari 尤其需要;此即 axe `scrollable-region-focusable` fix)。聚焦後 `ArrowUp/Down/Left/Right` / `PageUp/Down` / `Home/End` 捲動為瀏覽器原生行為,非 Radix 提供。**`viewportTabIndex={-1}` opt-out(2026-07-14)**:內容已有自帶 focusable + 鍵盤處理的元素(如 TimePicker `role="listbox"` `tabIndex={0}`)時傳 `-1`,消除「Viewport+內容雙 tab stop、焦點落 Viewport 時方向鍵觸發原生捲動非元件行為」;axe 由內部 focusable 內容滿足。**`viewportTabIndex={null}` composite opt-out(2026-07-31)**:ScrollArea 被 `role="menu"` 等 ARIA composite 當純結構 wrapper、鍵盤與 focus 由其 item family own 時,完全省略 viewport `tabindex`;`-1` 仍會留下 `div[tabindex]`,不能滿足 composite 的 required-children 結構
-- **Focus 可見**:聚焦的 Viewport 顯示 DS focus ring(`focus-visible:outline-ring`,inset 2px),非瀏覽器原生 focus ring
+- **Focus 可見**:聚焦的 Viewport 顯示 DS 焦點框(`focus-visible:focus-ring-inset`,往內 2px),非瀏覽器原生 focus ring(2026-09-24 訂正,原 `focus-visible:outline-ring` 是已退役的手寫 outline 寫法,`scroll-area.tsx:69` 實為 `focus-ring-inset`)
 - **Scrollbar 非 tab stop**:scrollbar thumb 不搶焦點,使用鍵盤的使用者透過 viewport 捲動(Radix 內建)
 - **Pointer 支援**:thumb 可拖曳,track 可 click-to-jump(Radix 內建)
 
@@ -151,6 +151,8 @@ Radix Viewport 內建 wrapper `min-width:100%; display:table`——這是**水
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `data-table-known-defects.spec.md`
 - `dialog.spec.md`
 - `file-viewer.spec.md`
 - `overlay-surface.spec.md`
+- `sidebar.spec.md`

package/src/components/ScrollArea/scroll-area.stories.tsx

@@ -165,9 +165,11 @@ export const VerticalIssueList: Story = {
         長 issue 清單(12 筆),容器固定 320px 高。macOS / Windows 呈現一致,不吃寬度。
       </p>
       <ScrollArea className="h-[320px] border border-border rounded-lg">
+        {/* 列是靜態 div(無 onClick、不能聚焦)→ 不給 hover 底色與 cursor-pointer:hover 回饋要誠實回答「再點會發生什麼」
+            (item-anatomy.spec.md「選中 × 互動疊加」表)。本則示範的是 ScrollArea 捲動,不是可點的議題列 */}
         <div className="p-2">
           {LINEAR_ISSUES.map((issue) => (
-            <div key={issue.id} className="flex items-center gap-3 px-3 py-2 rounded-md hover:bg-neutral-hover cursor-pointer">
+            <div key={issue.id} className="flex items-center gap-3 px-3 py-2">
               <span className="text-caption font-mono text-fg-muted shrink-0 w-20">{issue.id}</span>
               <span className="text-body flex-1 truncate">{issue.title}</span>
               <span className="inline-flex items-center gap-1.5 text-footnote shrink-0">
@@ -194,8 +196,9 @@ export const SidebarNav: Story = {
           {NOTION_NAV.map((group) => (
             <div key={group.section} className="mb-4">
               <div className="px-2 py-1 text-footnote text-fg-muted font-medium">{group.section}</div>
+              {/* 同上:靜態示意列不給 hover / cursor-pointer。真的側欄導覽請用 Sidebar(SidebarMenuButton;SidebarContent 自帶 ScrollArea) */}
               {group.items.map((item) => (
-                <div key={item} className="px-2 py-1.5 rounded-md text-body hover:bg-neutral-hover cursor-pointer truncate">
+                <div key={item} className="px-2 py-1.5 text-body truncate">
                   {item}
                 </div>
               ))}

package/src/components/ScrollArea/scroll-area.tsx

@@ -120,7 +120,7 @@ export const scrollAreaMeta = {
   tokens: {
     bg: [],
     fg: [],
-    ring: [],
+    ring: ['focus-ring-inset'],
   },
 } as const
 

package/src/components/SegmentedControl/segmented-control.anatomy.stories.tsx

@@ -289,7 +289,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"  ARIA / Pattern  :繼承 Radix toggle-group primitive 的無障礙預設——整組 role=\"group\",每個 item role=\"radio\"(type=\"single\" 互斥選一),鍵盤導覽由 primitive 處理。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組(只有一個 tab 停留點,落在選中項;沒選就落在上次 focus 過的 item,初次進入才是第一項)\n- ←/→ — 在 item 之間移動 roving focus(只移焦點,不切換選取)。WAI-ARIA APG 對水平 segmented/radio group 的主要導覽鍵\n- ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix toggle-group 未鎖 orientation(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵\n- Enter / Space — 選取目前 focus 的 item\n\n  Focus  :採 roving tabindex——整組共用一個 tab 停留點,方向鍵在 item 間移動焦點(選取仍需 Enter/Space/click);不是 Dialog 那種把焦點關在裡面的 focus trap。Focus ring 對齊 Button:focus-visible:ring-2 ring-ring ring-offset-1(box-shadow ring,非 CSS outline)。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
+      <p className="whitespace-pre-line">{"  ARIA / Pattern  :繼承 Radix toggle-group primitive 的無障礙預設——整組 role=\"group\",每個 item role=\"radio\"(type=\"single\" 互斥選一),鍵盤導覽由 primitive 處理。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組(只有一個 tab 停留點,落在選中項;沒選就落在上次 focus 過的 item,初次進入才是第一項)\n- ←/→ — 在 item 之間移動 roving focus(只移焦點,不切換選取)。WAI-ARIA APG 對水平 segmented/radio group 的主要導覽鍵\n- ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix toggle-group 未鎖 orientation(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵\n- Enter / Space — 選取目前 focus 的 item\n\n  Focus  :採 roving tabindex——整組共用一個 tab 停留點,方向鍵在 item 間移動焦點(選取仍需 Enter/Space/click);不是 Dialog 那種把焦點關在裡面的 focus trap。Focus ring 對齊 Button:全域 :focus-visible 外描邊(outline: 2px solid var(--ring),往外 2px;元件不寫任何焦點框 class,只加 focus-visible:z-20 讓往外長的框壓在相鄰 item 之上)。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
     </div>
   ),
 }

package/src/components/SegmentedControl/segmented-control.spec.md

@@ -218,7 +218,7 @@ Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只
 
 ### focus-visible
 
-由底層 ToggleGroup 處理——左右箭頭在 items 間移動 focus，空白/Enter 選取。Focus ring 對齊 Button：`ring-2 ring-ring ring-offset-1`。
+由底層 ToggleGroup 處理——左右箭頭在 items 間移動 focus，空白/Enter 選取。焦點框對齊 Button：全域 `:focus-visible` 外描邊（`styles/base.css` 的 `outline: 2px solid var(--ring)`，往外 `outline-offset: 2px`；item 不寫任何 ring / outline class，只加 `focus-visible:z-20` 把聚焦 item 提到相鄰 item 之上，讓外描邊浮在 `-ml-px` 重疊的鄰居 border 之上——與選中態 `z-10` 同一種手法；幾何 SSOT `ds-canonical/references/focus-canonical.md`「框怎麼畫」）。
 
 ---
 
@@ -276,7 +276,7 @@ Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只
 - ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix `toggle-group` 未鎖 `orientation`(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵
 - Enter / Space — 選取目前 focus 的 item
 
-**Focus**:Radix primitive 採 roving tabindex（整組共用單一 tab 停留點，方向鍵在 item 間移動焦點，不切換選取），非 Dialog 式 focus trap / restoration。Focus ring 對齊 Button focus-visible canonical（`focus-visible:ring-2 ring-ring ring-offset-1`——box-shadow ring，非 CSS outline）。
+**Focus**:Radix primitive 採 roving tabindex（整組共用單一 tab 停留點，方向鍵在 item 間移動焦點，不切換選取），非 Dialog 式 focus trap / restoration。焦點框對齊 Button focus-visible canonical（全域 `:focus-visible` 外描邊 `outline: 2px solid var(--ring)`，往外 2px——CSS outline，非 box-shadow ring；item 不寫任何 ring class）。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 

package/src/components/SegmentedControl/segmented-control.tsx

@@ -167,7 +167,8 @@ const itemVariants = cva(
     'relative inline-flex items-center justify-center',
     'whitespace-nowrap font-medium',
     'border border-border bg-surface text-fg-secondary',
-    'transition-colors duration-150',
+    // 不寫 transition-colors:hover 的外框與字色一律瞬間(tokens/motion/motion.spec.md「hover 回饋不做過渡」;2026-09-26 由底色延伸到字色與外框,待辦總帳 L9 / N4(3))。
+    // 選中的外框與字色跟 hover 是同一組 CSS 屬性,滑鼠點選時指標必在項目上 → 選中變色一併瞬間(與 Chip 同一處理)。
     'cursor-pointer select-none',
     'focus-visible:z-20',
     // disabled：cursor-not-allowed + 鎖住 hover 色（不用 pointer-events-none，否則 cursor 無法變）
@@ -315,7 +316,7 @@ export const segmentedControlMeta = {
   tokens: {
     bg: ['bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'], // selected 態 cva data-[state=on]:text-primary 實際消費(2026-07-06 選中改 base)
-    ring: ['ring-ring'],
+    ring: ['--ring'],
   },
   defaultSize: 'md',
 } as const