@qijenchen/design-system 0.1.0-beta.65 → 0.1.0-beta.67

package/dist/components/Notice/notice.d.ts

@@ -6,10 +6,13 @@ import * as React from 'react';
 /**
  * Notice — Toast / Alert 共用的視覺佈局層
  *
- * ── Typography: md tier ──
- * title: text-body (14px) leading-compact — 有 description 時加 font-medium
- * description: text-body (14px) leading-compact + text-fg-secondary (neutral-8)
+ * ── Typography: Family 2 reading-md(2026-06-15 user 拍板,off-grid 偏移收斂)──
+ * title: text-body (14px) default leading 1.5 — 有 description 時加 font-medium
+ * description: text-body (14px) default leading 1.5 + text-fg-secondary (neutral-8)
  * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。
+ * **行高 = reading 預設 1.5**(非 compact):Notice 是 Family 2 reading consumer,
+ * ItemContent 預設 mode='reading' + gap token `--item-gap-label-desc-reading` 名實相符。
+ * 原 `leading-compact`(1.3)= reading-gap + scanning-行高 混搭的 off-grid 偏移,已移除。
  *
  * ── Padding（固定,不隨 density 變） ──
  * px = px-4（16px）

package/dist/components/Notice/notice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../../src/components/Notice/notice.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAM9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAUhF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAM3D,CAAA;AAQD,MAAM,WAAW,WACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAC3D,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAA;CAC7C;AAED,QAAA,MAAM,MAAM,oFA0DX,CAAA;AA+BD,wBAAgB,eAAe,IAAI,MAAM,GAAG,OAAO,CAGlD;AAID,eAAO,MAAM,UAAU;;;;;;;;;;;CAeb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../../src/components/Notice/notice.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAM9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAUhF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAM3D,CAAA;AAYD,MAAM,WAAW,WACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAC3D,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAA;CAC7C;AAED,QAAA,MAAM,MAAM,oFA8DX,CAAA;AA+BD,wBAAgB,eAAe,IAAI,MAAM,GAAG,OAAO,CAGlD;AAID,eAAO,MAAM,UAAU;;;;;;;;;;;CAeb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/Notice/notice.js

@@ -3,7 +3,7 @@ import * as React from "react";
 import { XCircle, TriangleAlert, CircleCheck, Info, X } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { Button } from "../Button/button.js";
-import { ItemPrefix, ItemContent } from "../../patterns/element-anatomy/item-anatomy.js";
+import { ItemPrefix, ItemContent, ItemSuffix } from "../../patterns/element-anatomy/item-anatomy.js";
 const VARIANT_ICON = {
   neutral: null,
   info: Info,
@@ -20,7 +20,11 @@ const SUBTLE_ICON_COLOR = {
 };
 const NOTICE_LAYOUT = [
   "flex items-start gap-2 w-full",
-  "text-body leading-compact",
+  // 2026-06-15 user 拍板:Notice = 乾淨 Family 2 reading-md consumer。
+  // 原 `leading-compact`(1.3)是 off-grid 偏移(reading gap token + scanning 行高混搭、未文件化),
+  // 已移除 → label/desc 走 text-body reading 預設 1.5,與 ItemContent 預設 mode='reading' + gap
+  // token `--item-gap-label-desc-reading` 名實相符。詳 notice.spec.md「Typography」段。
+  "text-body",
   "px-4 py-3"
 ].join(" ");
 const Notice = React.forwardRef(
@@ -54,8 +58,12 @@ const Notice = React.forwardRef(
               labelClassName: description ? "font-medium" : void 0
             }
           ),
-          (endContent || dismissible) && // @row-slot-handcraft-allow: Notice 是非-row alert（非 item-anatomy row），此 end slot 是 Notice 自身 layout 的 dismiss/endContent 容器，不是 row prefix/suffix → 不消費 ItemPrefix/ItemSuffix
-          /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 shrink-0 h-[1lh]", children: [
+          (endContent || dismissible) && // 2026-06-15 user 拍板:消費 ItemSuffix primitive(原手刻 div + @row-slot-handcraft-allow
+          // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix
+          // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal
+          // 預設 false 故無 row inline-action 機制干擾。內裝 dismiss = Button iconOnly dismiss xs(banner
+          // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。
+          /* @__PURE__ */ jsxs(ItemSuffix, { children: [
             endContent,
             dismissible && /* @__PURE__ */ jsx(
               Button,

package/dist/components/Notice/notice.js.map

@@ -1 +1 @@
-{"version":3,"file":"notice.js","sources":["../../../src/components/Notice/notice.tsx"],"sourcesContent":["/**\n * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。\n * 不進 root barrel front-door;由 Alert / Toast wrap 消費,end-user app 請用 wrapper 元件。\n */\nimport * as React from 'react'\nimport { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Button } from '@/design-system/components/Button/button'\nimport { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * Notice — Toast / Alert 共用的視覺佈局層\n *\n * ── Typography: md tier ──\n * title: text-body (14px) leading-compact — 有 description 時加 font-medium\n * description: text-body (14px) leading-compact + text-fg-secondary (neutral-8)\n * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。\n *\n * ── Padding（固定,不隨 density 變） ──\n * px = px-4（16px）\n * py = py-3（12px）\n * gap = gap-2（8px）\n * Toast/Alert 是浮動通知,不是工作區域元件——density 控制表單/選單的緊湊度,\n * 通知的尺寸應該固定,不隨 density 縮放。\n *\n * ── Icon: md tier ──\n * icon size: 16px（ICON_SIZE.md）\n *\n * ── Dismiss X(chrome corner close,Cat 3 Action group region)──\n * 用 Button iconOnly dismiss **size=\"xs\"** — 非 Inline Action、非自刻 button。\n * Rationale(Notification banner family canonical):\n * - Notice / Alert / Toast 屬 **notification banner family**(ephemeral、px-4 py-3 固定不隨 density),\n *   dismiss 是邊角小 affordance,xs 視覺不搶眼不跟 content 競爭。見 `overlay-surface.spec.md`\n *   「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;xs 只用於 notification banner family)\n * - Close 左側可加 refresh / share(action group region),皆統一 xs\n * - `dismiss` prop 自動套 variant=\"text\" + fg-muted override\n * SSOT:patterns/element-anatomy/inline-action.spec.md「Dismiss canonical — X close only」\n *      + components/Alert/alert.spec.md「Chrome corner close X canonical」。\n */\n\nexport type NoticeVariant = 'neutral' | 'info' | 'success' | 'warning' | 'error'\n\nconst VARIANT_ICON: Record<NoticeVariant, LucideIcon | null> = {\n  neutral: null,\n  info: Info,\n  success: CircleCheck,\n  warning: TriangleAlert,\n  error: XCircle,\n}\n\nexport const SUBTLE_ICON_COLOR: Record<NoticeVariant, string> = {\n  neutral: 'text-fg-muted',\n  info: 'text-info-text',\n  success: 'text-success-text',\n  warning: 'text-warning-text',\n  error: 'text-error-text',\n}\n\nconst NOTICE_LAYOUT = [\n  'flex items-start gap-2 w-full',\n  'text-body leading-compact',\n  'px-4 py-3',\n].join(' ')\n\nexport interface NoticeProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {\n  variant?: NoticeVariant\n  title: React.ReactNode\n  description?: React.ReactNode\n  endContent?: React.ReactNode\n  dismissible?: boolean\n  onDismiss?: () => void\n  /** ARIA label for the dismiss button. Override for i18n. Default: \"關閉通知\" */\n  dismissAriaLabel?: string\n  iconClassName?: string\n  /**\n   * ARIA role 由 wrapping consumer 決定(Alert / Toast / 自管 host),Notice 預設不帶 role。\n   * Notice 是 layout primitive,Alert / Toast 是 live region 擁有者——避免 nested live region\n   * 造成 screen reader 重複朗讀。明文傳遞才覆寫。\n   */\n  role?: 'status' | 'alert'\n  /**\n   * 對應 role 的 aria-live 策略,wrapping consumer 決定;Notice 預設 undefined 不帶 live region。\n   */\n  'aria-live'?: 'polite' | 'assertive' | 'off'\n}\n\nconst Notice = React.forwardRef<HTMLDivElement, NoticeProps>(\n  (\n    {\n      variant = 'neutral',\n      title,\n      description,\n      endContent,\n      dismissible = true,\n      onDismiss,\n      dismissAriaLabel = '關閉通知', // i18n-allow: DS default; consumer override via dismissAriaLabel prop\n      iconClassName,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    const StatusIcon = VARIANT_ICON[variant]\n\n    return (\n      <div\n        ref={ref}\n        className={cn(NOTICE_LAYOUT, className)}\n        {...props}\n      >\n        {StatusIcon && (\n          <ItemPrefix>\n            <StatusIcon size={16} className={cn('shrink-0', iconClassName)} aria-hidden />\n          </ItemPrefix>\n        )}\n\n        {/* Title + description 消費 ItemContent primitive(SSOT)。\n            Label 有 desc 時 font-medium(Notice idiom:title 跟 desc 對照時 title 要更重)。 */}\n        <ItemContent\n          label={title}\n          description={description}\n          labelClassName={description ? 'font-medium' : undefined}\n        />\n\n        {(endContent || dismissible) && (\n          // @row-slot-handcraft-allow: Notice 是非-row alert（非 item-anatomy row），此 end slot 是 Notice 自身 layout 的 dismiss/endContent 容器，不是 row prefix/suffix → 不消費 ItemPrefix/ItemSuffix\n          <div className=\"flex items-center gap-2 shrink-0 h-[1lh]\">\n            {endContent}\n            {dismissible && (\n              <Button\n                data-dismiss\n                iconOnly\n                dismiss\n                size=\"xs\"\n                startIcon={XIcon}\n                aria-label={dismissAriaLabel}\n                onClick={onDismiss}\n              />\n            )}\n          </div>\n        )}\n      </div>\n    )\n  },\n)\nNotice.displayName = 'Notice'\n\n// Singleton MutationObserver + subscription fan-out(2026-04-22 D3 perf audit):\n// 先前每個 useInverseTheme consumer(Alert / Toast / Notice instance 等)各建一個 MO,\n// N 個 Notice = N 個 observers。singleton 共用一個 MO + pub/sub 讓 theme swap 只做一次 DOM read。\nlet themeObserverStarted = false\nconst themeSubscribers = new Set<() => void>()\n\nfunction getInverseTheme(): 'dark' | 'light' {\n  if (typeof document === 'undefined') return 'dark'\n  const current = document.documentElement.getAttribute('data-theme') ?? 'light'\n  return current === 'dark' ? 'light' : 'dark'\n}\n\nfunction startThemeObserver() {\n  if (themeObserverStarted || typeof document === 'undefined') return\n  themeObserverStarted = true\n  const root = document.documentElement\n  const observer = new MutationObserver(() => {\n    themeSubscribers.forEach((cb) => cb())\n  })\n  observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] })\n}\n\nfunction subscribe(cb: () => void): () => void {\n  startThemeObserver()\n  themeSubscribers.add(cb)\n  return () => themeSubscribers.delete(cb)\n}\n\nexport function useInverseTheme(): 'dark' | 'light' {\n  // useSyncExternalStore canonical (React 18+):單一 external source 被 N consumers 訂閱\n  return React.useSyncExternalStore(subscribe, getInverseTheme, getInverseTheme)\n}\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const noticeMeta = {\n  component: 'Notice',\n  family: 2, // Family 2（List item layout）消費者 — 對齊 notice.spec.md frontmatter family: 2 + body「Layout Family」段\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default'], // 無互動 layout primitive(spec「邊界案例」:不擁有 disabled;hover / focus 屬內嵌 dismiss Button)\n  tokens: {\n    bg: [],\n    fg: ['text-error-text', 'text-fg-muted', 'text-fg-secondary', 'text-info-text', 'text-success-text', 'text-warning-text'],\n    ring: [],\n  },\n} as const\n\nexport { Notice }\n"],"names":["XIcon"],"mappings":";;;;;;AA0CA,MAAM,eAAyD;AAAA,EAC7D,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,OAAO;AACT;AAEO,MAAM,oBAAmD;AAAA,EAC9D,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,OAAO;AACT;AAEA,MAAM,gBAAgB;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAyBV,MAAM,SAAS,MAAM;AAAA,EACnB,CACE;AAAA,IACE,UAAU;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,IACd;AAAA,IACA,mBAAmB;AAAA;AAAA,IACnB;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EAAA,GAEL,QACG;AACH,UAAM,aAAa,aAAa,OAAO;AAEvC,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,WAAW,GAAG,eAAe,SAAS;AAAA,QACrC,GAAG;AAAA,QAEH,UAAA;AAAA,UAAA,cACC,oBAAC,YAAA,EACC,UAAA,oBAAC,YAAA,EAAW,MAAM,IAAI,WAAW,GAAG,YAAY,aAAa,GAAG,eAAW,MAAC,GAC9E;AAAA,UAKF;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,OAAO;AAAA,cACP;AAAA,cACA,gBAAgB,cAAc,gBAAgB;AAAA,YAAA;AAAA,UAAA;AAAA,WAG9C,cAAc;AAAA,UAEd,qBAAC,OAAA,EAAI,WAAU,4CACZ,UAAA;AAAA,YAAA;AAAA,YACA,eACC;AAAA,cAAC;AAAA,cAAA;AAAA,gBACC,gBAAY;AAAA,gBACZ,UAAQ;AAAA,gBACR,SAAO;AAAA,gBACP,MAAK;AAAA,gBACL,WAAWA;AAAAA,gBACX,cAAY;AAAA,gBACZ,SAAS;AAAA,cAAA;AAAA,YAAA;AAAA,UACX,EAAA,CAEJ;AAAA,QAAA;AAAA,MAAA;AAAA,IAAA;AAAA,EAIR;AACF;AACA,OAAO,cAAc;AAKrB,IAAI,uBAAuB;AAC3B,MAAM,uCAAuB,IAAA;AAE7B,SAAS,kBAAoC;AAC3C,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,UAAU,SAAS,gBAAgB,aAAa,YAAY,KAAK;AACvE,SAAO,YAAY,SAAS,UAAU;AACxC;AAEA,SAAS,qBAAqB;AAC5B,MAAI,wBAAwB,OAAO,aAAa,YAAa;AAC7D,yBAAuB;AACvB,QAAM,OAAO,SAAS;AACtB,QAAM,WAAW,IAAI,iBAAiB,MAAM;AAC1C,qBAAiB,QAAQ,CAAC,OAAO,GAAA,CAAI;AAAA,EACvC,CAAC;AACD,WAAS,QAAQ,MAAM,EAAE,YAAY,MAAM,iBAAiB,CAAC,YAAY,GAAG;AAC9E;AAEA,SAAS,UAAU,IAA4B;AAC7C,qBAAA;AACA,mBAAiB,IAAI,EAAE;AACvB,SAAO,MAAM,iBAAiB,OAAO,EAAE;AACzC;AAEO,SAAS,kBAAoC;AAElD,SAAO,MAAM,qBAAqB,WAAW,iBAAiB,eAAe;AAC/E;AAIO,MAAM,aAAa;AAAA,EACxB,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU,CAAA;AAAA,EAGV,OAAO,CAAA;AAAA,EAGP,QAAQ,CAAC,SAAS;AAAA;AAAA,EAClB,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA,IACJ,IAAI,CAAC,mBAAmB,iBAAiB,qBAAqB,kBAAkB,qBAAqB,mBAAmB;AAAA,IACxH,MAAM,CAAA;AAAA,EAAC;AAEX;"}
+{"version":3,"file":"notice.js","sources":["../../../src/components/Notice/notice.tsx"],"sourcesContent":["/**\n * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。\n * 不進 root barrel front-door;由 Alert / Toast wrap 消費,end-user app 請用 wrapper 元件。\n */\nimport * as React from 'react'\nimport { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Button } from '@/design-system/components/Button/button'\nimport { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * Notice — Toast / Alert 共用的視覺佈局層\n *\n * ── Typography: Family 2 reading-md(2026-06-15 user 拍板,off-grid 偏移收斂)──\n * title: text-body (14px) default leading 1.5 — 有 description 時加 font-medium\n * description: text-body (14px) default leading 1.5 + text-fg-secondary (neutral-8)\n * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。\n * **行高 = reading 預設 1.5**(非 compact):Notice 是 Family 2 reading consumer,\n * ItemContent 預設 mode='reading' + gap token `--item-gap-label-desc-reading` 名實相符。\n * 原 `leading-compact`(1.3)= reading-gap + scanning-行高 混搭的 off-grid 偏移,已移除。\n *\n * ── Padding（固定,不隨 density 變） ──\n * px = px-4（16px）\n * py = py-3（12px）\n * gap = gap-2（8px）\n * Toast/Alert 是浮動通知,不是工作區域元件——density 控制表單/選單的緊湊度,\n * 通知的尺寸應該固定,不隨 density 縮放。\n *\n * ── Icon: md tier ──\n * icon size: 16px（ICON_SIZE.md）\n *\n * ── Dismiss X(chrome corner close,Cat 3 Action group region)──\n * 用 Button iconOnly dismiss **size=\"xs\"** — 非 Inline Action、非自刻 button。\n * Rationale(Notification banner family canonical):\n * - Notice / Alert / Toast 屬 **notification banner family**(ephemeral、px-4 py-3 固定不隨 density),\n *   dismiss 是邊角小 affordance,xs 視覺不搶眼不跟 content 競爭。見 `overlay-surface.spec.md`\n *   「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;xs 只用於 notification banner family)\n * - Close 左側可加 refresh / share(action group region),皆統一 xs\n * - `dismiss` prop 自動套 variant=\"text\" + fg-muted override\n * SSOT:patterns/element-anatomy/inline-action.spec.md「Dismiss canonical — X close only」\n *      + components/Alert/alert.spec.md「Chrome corner close X canonical」。\n */\n\nexport type NoticeVariant = 'neutral' | 'info' | 'success' | 'warning' | 'error'\n\nconst VARIANT_ICON: Record<NoticeVariant, LucideIcon | null> = {\n  neutral: null,\n  info: Info,\n  success: CircleCheck,\n  warning: TriangleAlert,\n  error: XCircle,\n}\n\nexport const SUBTLE_ICON_COLOR: Record<NoticeVariant, string> = {\n  neutral: 'text-fg-muted',\n  info: 'text-info-text',\n  success: 'text-success-text',\n  warning: 'text-warning-text',\n  error: 'text-error-text',\n}\n\nconst NOTICE_LAYOUT = [\n  'flex items-start gap-2 w-full',\n  // 2026-06-15 user 拍板:Notice = 乾淨 Family 2 reading-md consumer。\n  // 原 `leading-compact`(1.3)是 off-grid 偏移(reading gap token + scanning 行高混搭、未文件化),\n  // 已移除 → label/desc 走 text-body reading 預設 1.5,與 ItemContent 預設 mode='reading' + gap\n  // token `--item-gap-label-desc-reading` 名實相符。詳 notice.spec.md「Typography」段。\n  'text-body',\n  'px-4 py-3',\n].join(' ')\n\nexport interface NoticeProps\n  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {\n  variant?: NoticeVariant\n  title: React.ReactNode\n  description?: React.ReactNode\n  endContent?: React.ReactNode\n  dismissible?: boolean\n  onDismiss?: () => void\n  /** ARIA label for the dismiss button. Override for i18n. Default: \"關閉通知\" */\n  dismissAriaLabel?: string\n  iconClassName?: string\n  /**\n   * ARIA role 由 wrapping consumer 決定(Alert / Toast / 自管 host),Notice 預設不帶 role。\n   * Notice 是 layout primitive,Alert / Toast 是 live region 擁有者——避免 nested live region\n   * 造成 screen reader 重複朗讀。明文傳遞才覆寫。\n   */\n  role?: 'status' | 'alert'\n  /**\n   * 對應 role 的 aria-live 策略,wrapping consumer 決定;Notice 預設 undefined 不帶 live region。\n   */\n  'aria-live'?: 'polite' | 'assertive' | 'off'\n}\n\nconst Notice = React.forwardRef<HTMLDivElement, NoticeProps>(\n  (\n    {\n      variant = 'neutral',\n      title,\n      description,\n      endContent,\n      dismissible = true,\n      onDismiss,\n      dismissAriaLabel = '關閉通知', // i18n-allow: DS default; consumer override via dismissAriaLabel prop\n      iconClassName,\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    const StatusIcon = VARIANT_ICON[variant]\n\n    return (\n      <div\n        ref={ref}\n        className={cn(NOTICE_LAYOUT, className)}\n        {...props}\n      >\n        {StatusIcon && (\n          <ItemPrefix>\n            <StatusIcon size={16} className={cn('shrink-0', iconClassName)} aria-hidden />\n          </ItemPrefix>\n        )}\n\n        {/* Title + description 消費 ItemContent primitive(SSOT)。\n            Label 有 desc 時 font-medium(Notice idiom:title 跟 desc 對照時 title 要更重)。 */}\n        <ItemContent\n          label={title}\n          description={description}\n          labelClassName={description ? 'font-medium' : undefined}\n        />\n\n        {(endContent || dismissible) && (\n          // 2026-06-15 user 拍板:消費 ItemSuffix primitive(原手刻 div + @row-slot-handcraft-allow\n          // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix\n          // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal\n          // 預設 false 故無 row inline-action 機制干擾。內裝 dismiss = Button iconOnly dismiss xs(banner\n          // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。\n          <ItemSuffix>\n            {endContent}\n            {dismissible && (\n              <Button\n                data-dismiss\n                iconOnly\n                dismiss\n                size=\"xs\"\n                startIcon={XIcon}\n                aria-label={dismissAriaLabel}\n                onClick={onDismiss}\n              />\n            )}\n          </ItemSuffix>\n        )}\n      </div>\n    )\n  },\n)\nNotice.displayName = 'Notice'\n\n// Singleton MutationObserver + subscription fan-out(2026-04-22 D3 perf audit):\n// 先前每個 useInverseTheme consumer(Alert / Toast / Notice instance 等)各建一個 MO,\n// N 個 Notice = N 個 observers。singleton 共用一個 MO + pub/sub 讓 theme swap 只做一次 DOM read。\nlet themeObserverStarted = false\nconst themeSubscribers = new Set<() => void>()\n\nfunction getInverseTheme(): 'dark' | 'light' {\n  if (typeof document === 'undefined') return 'dark'\n  const current = document.documentElement.getAttribute('data-theme') ?? 'light'\n  return current === 'dark' ? 'light' : 'dark'\n}\n\nfunction startThemeObserver() {\n  if (themeObserverStarted || typeof document === 'undefined') return\n  themeObserverStarted = true\n  const root = document.documentElement\n  const observer = new MutationObserver(() => {\n    themeSubscribers.forEach((cb) => cb())\n  })\n  observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] })\n}\n\nfunction subscribe(cb: () => void): () => void {\n  startThemeObserver()\n  themeSubscribers.add(cb)\n  return () => themeSubscribers.delete(cb)\n}\n\nexport function useInverseTheme(): 'dark' | 'light' {\n  // useSyncExternalStore canonical (React 18+):單一 external source 被 N consumers 訂閱\n  return React.useSyncExternalStore(subscribe, getInverseTheme, getInverseTheme)\n}\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const noticeMeta = {\n  component: 'Notice',\n  family: 2, // Family 2（List item layout）消費者 — 對齊 notice.spec.md frontmatter family: 2 + body「Layout Family」段\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default'], // 無互動 layout primitive(spec「邊界案例」:不擁有 disabled;hover / focus 屬內嵌 dismiss Button)\n  tokens: {\n    bg: [],\n    fg: ['text-error-text', 'text-fg-muted', 'text-fg-secondary', 'text-info-text', 'text-success-text', 'text-warning-text'],\n    ring: [],\n  },\n} as const\n\nexport { Notice }\n"],"names":["XIcon"],"mappings":";;;;;;AA6CA,MAAM,eAAyD;AAAA,EAC7D,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,OAAO;AACT;AAEO,MAAM,oBAAmD;AAAA,EAC9D,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,OAAO;AACT;AAEA,MAAM,gBAAgB;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAyBV,MAAM,SAAS,MAAM;AAAA,EACnB,CACE;AAAA,IACE,UAAU;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,IACd;AAAA,IACA,mBAAmB;AAAA;AAAA,IACnB;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EAAA,GAEL,QACG;AACH,UAAM,aAAa,aAAa,OAAO;AAEvC,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,WAAW,GAAG,eAAe,SAAS;AAAA,QACrC,GAAG;AAAA,QAEH,UAAA;AAAA,UAAA,cACC,oBAAC,YAAA,EACC,UAAA,oBAAC,YAAA,EAAW,MAAM,IAAI,WAAW,GAAG,YAAY,aAAa,GAAG,eAAW,MAAC,GAC9E;AAAA,UAKF;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,OAAO;AAAA,cACP;AAAA,cACA,gBAAgB,cAAc,gBAAgB;AAAA,YAAA;AAAA,UAAA;AAAA,WAG9C,cAAc;AAAA;AAAA;AAAA;AAAA;AAAA,+BAMb,YAAA,EACE,UAAA;AAAA,YAAA;AAAA,YACA,eACC;AAAA,cAAC;AAAA,cAAA;AAAA,gBACC,gBAAY;AAAA,gBACZ,UAAQ;AAAA,gBACR,SAAO;AAAA,gBACP,MAAK;AAAA,gBACL,WAAWA;AAAAA,gBACX,cAAY;AAAA,gBACZ,SAAS;AAAA,cAAA;AAAA,YAAA;AAAA,UACX,EAAA,CAEJ;AAAA,QAAA;AAAA,MAAA;AAAA,IAAA;AAAA,EAIR;AACF;AACA,OAAO,cAAc;AAKrB,IAAI,uBAAuB;AAC3B,MAAM,uCAAuB,IAAA;AAE7B,SAAS,kBAAoC;AAC3C,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,UAAU,SAAS,gBAAgB,aAAa,YAAY,KAAK;AACvE,SAAO,YAAY,SAAS,UAAU;AACxC;AAEA,SAAS,qBAAqB;AAC5B,MAAI,wBAAwB,OAAO,aAAa,YAAa;AAC7D,yBAAuB;AACvB,QAAM,OAAO,SAAS;AACtB,QAAM,WAAW,IAAI,iBAAiB,MAAM;AAC1C,qBAAiB,QAAQ,CAAC,OAAO,GAAA,CAAI;AAAA,EACvC,CAAC;AACD,WAAS,QAAQ,MAAM,EAAE,YAAY,MAAM,iBAAiB,CAAC,YAAY,GAAG;AAC9E;AAEA,SAAS,UAAU,IAA4B;AAC7C,qBAAA;AACA,mBAAiB,IAAI,EAAE;AACvB,SAAO,MAAM,iBAAiB,OAAO,EAAE;AACzC;AAEO,SAAS,kBAAoC;AAElD,SAAO,MAAM,qBAAqB,WAAW,iBAAiB,eAAe;AAC/E;AAIO,MAAM,aAAa;AAAA,EACxB,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU,CAAA;AAAA,EAGV,OAAO,CAAA;AAAA,EAGP,QAAQ,CAAC,SAAS;AAAA;AAAA,EAClB,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA,IACJ,IAAI,CAAC,mBAAmB,iBAAiB,qBAAqB,kBAAkB,qBAAqB,mBAAmB;AAAA,IACxH,MAAM,CAAA;AAAA,EAAC;AAEX;"}

package/ds-canonical/references/story-baseline-registry.json

@@ -36,6 +36,12 @@
           "regex": "<SidebarHeader[^>]*>[[:space:]]*<div[^>]*flex-col",
           "severity": "block",
           "rationale": "SidebarHeader brand 必單行(Fixed-h chrome 不可成長,sidebar.spec.md SidebarHeader 段 2026-06-12 明文)。flex-col 直接子層 = logo name 下加副標的結構簽名 — shadcn TeamSwitcher demo prior 滲漏;plan/org 資訊歸 workspace switcher dropdown row,非常駐 header"
+        },
+        {
+          "id": "sidebar-footer-two-line",
+          "regex": "<SidebarFooter[^>]*>.{0,400}(text-xs|leading-tight)",
+          "severity": "block",
+          "rationale": "SidebarFooter user 區必單行(名字 only;職稱/email 等身份資訊歸 ItemAvatar hoverCard 的 ProfileCard,sidebar.stories.tsx UserFooter canonical)。shadcn nav-user 的「name + email text-xs 兩行」是強 LLM 先驗,且 text-xs 違反 chrome typography canonical(sidebar.spec『chrome 內 text 一律 text-body-lg』);400 字元窗限制 greediness"
         }
       ]
     },
@@ -88,6 +94,12 @@
           "regex": "<ChromeHeader[^>]*>.{0,160}<span[[:space:]]+className=\"[^\"]*flex-1[^\"]*\">",
           "severity": "block",
           "rationale": "ChromeHeader title 該用 <h1 className=\"text-body-lg font-medium\"> 緊鄰 SidebarTrigger,不該用 <span flex-1> 撐空間造成 toggle + title 巨大間距"
+        },
+        {
+          "id": "chromeheader-subtitle-second-line",
+          "regex": "<(ChromeHeader|PageHeader)[^>]*>[[:space:]]*<div[^>]*flex-col",
+          "severity": "block",
+          "rationale": "Chrome 家族永遠 single-row(header-canonical.spec.md:47,剛性 --chrome-header-height);title 下加副標/description = LLM 先驗回填(Polaris Page subtitle / Tailwind UI page heading 先驗),頁面說明文字歸 content 區,非 chrome。flex-col 直接子層 = 兩行結構簽名"
         }
       ]
     }

package/ds-canonical/skills/design-system-audit/SKILL.md

@@ -188,7 +188,7 @@ User 2026-05-15 verbatim 抓「DS 深度稽核漏 storybook content quality」+
 | 68 | **Stories-vs-spec canonical drift**(2026-05-27 codify per user「DS 自己 stories 教錯 = consumer 抄 stories 抄錯」root cause)| 對每 component `*.stories.tsx` + `*.anatomy.stories.tsx` + `*.principles.stories.tsx` grep:含 `<SidebarHeader>` 內 `<ItemAvatar>` / 同類 spec 明文禁止的 pattern → 違反(DS 教 consumer 錯 pattern,類似 2026-05-27 sidebar 3 stories 在 WorkspaceBrand 用 ItemAvatar 違反 chrome header canonical)。**主防線 = R8 registry**(`.claude/references/story-baseline-registry.json` requiredHelpers / antiPatterns + `check_story_invariants.sh` R8/R9 機械攔)+ `check_chrome_header_avatar_canonical.sh` / `check_sidebar_menu_button_implicit_wrap.sh` 具體錨例 hook;`// @canonical-pattern:` / `// @anti-pattern:` 文字 marker **降格為建議性輔助**(2026-06-12 R2 拍板 — 全庫僅 sidebar.stories 2 處採用且無機械強制 = 紙防線,不再「必加」;存在時 audit 順驗其與 spec 一致)。配 Dim 53(spec-vs-code)+ 本 dim(spec-vs-stories)雙向 drift verify;系統性 stories drift audit run via design-system-audit Dim 68 batch sweep |
 | 69 | **Consumer no-DS-catalog enforcement**(2026-05-27 M31 codex synthesis per user「眼不見為淨」+「做產品真的能使用跟 ds repo 一模一樣的元件做產品嗎?」)| 對 consumer `apps/**/*.stories.tsx` grep:basename 為 `EveryDsComponent` / `AllDsComponents` / catalog naming + `Object.keys(DS).map` iterate-render + mass hand-mock(≥5 distinct `<DS.X>` 單 file)→ 違反(DS catalog 是 DS Storybook 唯一 SSOT,consumer 重寫必 drift,2026-05-27 錨例 7 bug)。Hook `check_consumer_app_invariants.sh(r1,2026-06-11 merge)` PostToolUse Write/Edit BLOCKER,escape `// @consumer-catalog-allow:`。允許 portal proxy(iframe to DS Storybook)|
 | 70 | **Consumer @story-baseline enforcement**(2026-05-27 M31 codex synthesis)| 對 consumer `apps/**/*.stories.tsx` grep:用高風險 DS primitive(DataTable / Dialog / Sheet / Popover / DropdownMenu / Tooltip / HoverCard / LinkInput / RadioGroup / CircularProgress / AppShell / Sidebar)但無 `// @story-baseline: <DS-story-path>#<exportName>` marker → 違反(consumer 必 reference DS canonical story 才 enable visual diff CI)。Hook `check_consumer_app_invariants.sh(r2,2026-06-11 merge)` PostToolUse BLOCKER,escape `// @story-baseline-allow:`。SSOT mapping → `ds-story-manifest.json`(DS package ship)|
-| 71 | **Consumer DS primitive misuse anti-pattern**(2026-05-27 per user「做產品真的要能使用跟 ds repo 一模一樣的元件」)| 對 consumer `apps/**/*.{tsx,ts}` production + stories grep:`<CircularProgress size={N}>` literal number 覆蓋 default 24 / `<RadioGroupItem>` 無 `<SelectionItem control={...}>` wrap / `<DataTable columns={[single-col]}>` minimal / `<LinkInput placeholder=...>` 無 `value` prop / `<Empty title=...>` 無 icon AND 無 description / Overlay story 無 `defaultOpen` 視覺 snapshot 看不到 content / **硬寫色值-字級-shadow 繞 token(`bg-[#hex]` / `text-[14px]` / `shadow-md`,2026-06-02 Pattern 8,CF conformance-model 主防線)**。Hook `check_consumer_app_invariants.sh(r3,2026-06-11 merge)` BLOCKER。Per-violation cite spec.md file:line。Escape `// @ds-misuse-allow:` |
+| 71 | **Consumer DS primitive misuse anti-pattern**(2026-05-27 per user「做產品真的要能使用跟 ds repo 一模一樣的元件」)| 對 consumer `apps/**/*.{tsx,ts}` production + stories grep:`<CircularProgress size={N}>` literal number 覆蓋 default 24 / `<RadioGroupItem>` 無 `<SelectionItem control={...}>` wrap / `<DataTable columns={[single-col]}>` minimal / `<LinkInput placeholder=...>` 無 `value` prop / `<Empty title=...>` 無 icon AND 無 description / Overlay story 無 `defaultOpen` 視覺 snapshot 看不到 content / **硬寫色值-字級-shadow 繞 token(`bg-[#hex]` / `text-[14px]` / `shadow-md`,2026-06-02 Pattern 8,CF conformance-model 主防線)** / **AppShell slot 餵 raw element(`sidebar={<div>}` 等,2026-06-12 Pattern 9,app-shell.spec:296-299)**。**判斷層補掃(2026-06-12 fork 四不像 + 先驗滲漏 anchor;hook 零誤判原則不上 regex)**:(a) page-level entry 手拼 raw 殼而無 `<DS.AppShell>`(對照 app-shell.spec「何時用/不用」表;愈不用 DS 愈不觸 hook = 反直覺洞)(b) 手刻 right panel(`w-[Npx] border-l` div,該走 `aside={<AppShellAside>}`)(c) ChromeHeader/頁頂 tabs 沒走 `withTabs` lockstep(header-canonical.spec「withTabs 連動」段)(d) BulkActionBar 內 primary 鈕 / 浮層 shadow(bulk-action-bar.spec 禁止事項 — regex 無法 bound 到 actions slot,判斷層接)(e) FileViewer toolbar 加鈕不走 `onCapabilitiesChange`(file-viewer.spec:183-194;R9 skip-list 豁免該家族故無寫入網)(f) chrome 面(ChromeHeader/SidebarFooter)title 下第二行(registry 簽名涵蓋 stories;fork production code 由本 dim 接)。Hook `check_consumer_app_invariants.sh(r3,2026-06-11 merge)` BLOCKER。Per-violation cite spec.md file:line。Escape `// @ds-misuse-allow:` |
 | 72 | **DS API surface tightening**(2026-05-27 — 治標 vs 治本)| Hook 71 偵測 anti-pattern 是 lint 層攔截;治本要 DS API design 強到 misuse 即 fail tsc。Audit:逐 component review API surface — `size?: number` 該改 `'sm'\|'md'\|'lg'` enum / `columns: Column[]` 該加 min length runtime check / `title` + `description` 該有 type-level XOR / Overlay primitive `defaultOpen` 該 require explicit。配套 codify in `tightening-roadmap.md`(若存在;不存在則以 `props-naming.md` + 各 spec API 段為準,對齊 audit-prompts.md dim 72),分 quarter ship。對應 Dim 71 是攔當前 misuse,本 dim 是消除未來 misuse 可能 |
 | 73 | **Full-story visual+interaction sweep enforce**(2026-05-27 codex M31 P0 finding)| Audit report JSON `storyResults.length === manifest.totalStories`(916)。Sample < 916 = reject(per user「不准抽樣」)。Hook `check_full_story_visual_interaction_sweep.sh` PostToolUse audit-report.json BLOCKER。Escape `"_sampling_allowed": "<rationale>"`(極罕見)|
 | 74 | **Overlay open/focus/Escape probe**(2026-05-27 codex M31 P0 finding + user 7-bug 錨點「overlay 沒彈出」)| Consumer story 用 Tooltip / Popover / Dialog / Sheet / DropdownMenu / HoverCard Trigger 必含 `defaultOpen` OR `open={true}` OR `play()` interaction click。Trigger-only catalog = reject(visual snapshot 看不到 content)。Hook `check_overlay_open_focus_escape_probe.sh` BLOCKER。HoverCard exception via `@story-trait-allow: missing-opensnapshot` per codex |

package/ds-canonical/templates/dashboard-app.tsx

@@ -34,6 +34,7 @@ import {
   SidebarMenuItem,
   SidebarMenuButton,
   SidebarTrigger,
+  ChromeHeader,
   TooltipProvider,
   Avatar,
   ItemAvatar,
@@ -92,15 +93,19 @@ function AppSidebar() {
   )
 }
 
-// ── PageHeader(對齊 DS canonical chrome-header pattern:fixed --chrome-header-height + SidebarTrigger + title)──
+// ── PageHeader(消費 DS ChromeHeader primitive,2026-06-12 修:原手刻 <header className=...>
+// 繞過 header-canonical 全部機械簽名 + 違反「消費 primitive 不 hand-craft」canonical;
+// 對齊 _demo-helpers.tsx PageHeader 同款消費形)──
 // SidebarTrigger 必有(primary-sidebar mode 的 menu toggle 入口,⌘B keyboard shortcut)
-function PageHeader({ title, rightSlot }: { title: string; rightSlot?: React.ReactNode }) {
+// rightSlot 用 JSX.Element(非 React.ReactNode):workspace 內 app 自帶 @types/react 副本與
+// DS 套件 .d.ts 解析的 ReactNode 版本不相容(bigint 差異)— Element 兩邊皆可指派
+function PageHeader({ title, rightSlot }: { title: string; rightSlot?: JSX.Element }) {
   return (
-    <header className="flex items-center gap-2 h-[var(--chrome-header-height)] px-[var(--layout-space-loose)] bg-surface border-b border-divider">
+    <ChromeHeader className="bg-surface">
       <SidebarTrigger />
       <h1 className="text-body-lg font-medium flex-1 truncate">{title}</h1>
       {rightSlot}
-    </header>
+    </ChromeHeader>
   )
 }
 

package/llms-full.txt

@@ -1,6 +1,6 @@
 # @qijenchen/design-system — 完整設計參考(llms-full)
 
-> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.65。
+> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.67。
 
 # Components
 

package/llms.txt

@@ -1,7 +1,7 @@
 # @qijenchen/design-system
 
 > World-class React design system(Radix/shadcn + Tailwind v4 + 自訂 design token)。
-> 54 components + 4 public patterns + design tokens。v0.1.0-beta.65。
+> 54 components + 4 public patterns + design tokens。v0.1.0-beta.67。
 
 本檔由 source(spec.md frontmatter + Storybook index)build-time 自動生成,**禁手改**(CI --check drift gate 守)。
 每元件 / pattern 的完整 variants / sizes / 禁止事項 全文見 [llms-full.txt](./llms-full.txt)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.65",
+  "version": "0.1.0-beta.67",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",

package/src/components/AppShell/app-shell.spec.md

@@ -297,6 +297,7 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 - ❌ 禁:`sidebar={<div>...</div>}`(應傳 `<Sidebar>` primitive,確保視覺 SSOT。型別上收 ReactNode、不做機械強制 — React 型別強制易被 wrapper 包一層繞過,世界級 shell 元件皆收 ReactNode;本約定靠 story 示範 + audit 把關。2026-06-10 user 拍板 2a:措辭「必」→「應」對齊 code 真實)
 - ❌ 禁:`header={<header>...</header>}`(應傳 `<ChromeHeader>` 或消費 `header-canonical` 派生 header;同上,型別不機械強制)
 - ❌ 禁:AppShell.Main 自加 padding(違反 layoutSpace 規則 1B)
+- ❌ 禁:AppShellAside header 加第二行 / actions(header = 單行 title + close X,API typed `title: string` 結構鎖;說明文字歸 aside body — 2026-06-12 fork-drift 防線)
 - ✅ 必:`layout` mode 在 product 啟動時固定,**不在 runtime 切換**(切換 = product 角色變動 = 應該重 mount app)
 
 ---

package/src/components/Notice/notice.anatomy.stories.tsx

@@ -122,14 +122,14 @@ export const Overview: Story = {
               <tr>
                 <Td mono>title</Td>
                 <Td>單行必填</Td>
-                <Td mono>text-body leading-compact</Td>
+                <Td mono>text-body(reading 1.5)</Td>
                 <Td mono>14px / 有 desc 時 font-medium</Td>
               </tr>
               <tr>
                 <Td mono>description</Td>
                 <Td>可選輔助文字</Td>
                 <Td mono>text-fg-secondary</Td>
-                <Td mono>14px leading-compact</Td>
+                <Td mono>14px(reading 1.5)</Td>
               </tr>
               <tr>
                 <Td mono>endContent</Td>
@@ -265,7 +265,7 @@ function NoticeInspector() {
 │  h-[1lh]      min-w-0 flex-1                   h-[1lh]           │
 └──────────────────────────────────────────────────────────────────┘
 
-text-body = 14px   leading-compact = 1.3
+text-body = 14px   reading 行高 = 1.5(Family 2 reading-md,2026-06-15 收斂)
 固定 md tier — 不隨 density 變(通知是跨 density 一致的訊息載體)`}
             </pre>
           </div>
@@ -350,7 +350,7 @@ text-body = 14px   leading-compact = 1.3
               </tr>
               <tr>
                 <Td mono>title font</Td>
-                <Td mono>text-body · leading-compact</Td>
+                <Td mono>text-body · reading 1.5 · font-medium</Td>
               </tr>
               <tr>
                 <Td mono>desc font</Td>

package/src/components/Notice/notice.spec.md

@@ -29,11 +29,15 @@ Notice 是純視覺 primitive，不是獨立使用的元件。消費者：
 
 ## Typography
 
-md tier，固定不隨 density 變：
-- title: `text-body`（14px）`leading-compact`（1.3）— 有 description 時加 `font-medium`
-- description: `text-body`（14px）`leading-compact` + `text-fg-secondary`（neutral-8）
+**Family 2 reading-md consumer（2026-06-15 user 拍板,off-grid 偏移收斂）**，md tier 固定不隨 density 變：
+- title: `text-body`（14px）**default leading 1.5** — 有 description 時加 `font-medium`
+- description: `text-body`（14px）**default leading 1.5** + `text-fg-secondary`（neutral-8）
+- label↔desc gap: `--item-gap-label-desc-reading`（ItemContent 預設 mode=`reading` size=`md` 自動選）
+- icon: 16px（`ICON_SIZE.md`，item-anatomy.tsx）
 
-相同 body 字級,層級靠 font-weight / color 區分。
+相同 body 字級,層級靠 font-weight / color 區分（不靠 font-size,亦不靠 compact 行高）。
+
+> **為何 reading-md 而非 compact（2026-06-15 codify，根治 off-grid 偏移）**：Notice 同時服務 title-only（多數）與 title+desc、Alert（banner）與 Toast（snackbar）。原本 root 套 `leading-compact`(1.3) 形成「reading gap token + scanning 行高」混搭,落在 ItemContent 4 個合法 mode（reading-md/reading-lg/scanning-md/scanning-lg）**之外**的第五種組合（label 14 + desc 14 + 行高 1.3）且未文件化 → 違反 `item-anatomy.spec.md`「偏離 canonical 必明文 rationale」。收斂為純 **reading-md**：title-only 14px 對齊 Ant/Material title-only norm（scanning-lg 的 16px 過大）；desc 維持 14px 可讀（scanning-md 的 12px caption 對通知訊息過小）；title↔desc 階層由 `font-medium` 承載已足夠。對照 FileItem（顯式 `mode="scanning"` + 文件化 = 正確消費範例,file-item.tsx:13/214）。
 
 ## Padding（固定）
 

package/src/components/Notice/notice.tsx

@@ -6,15 +6,18 @@ import * as React from 'react'
 import { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { Button } from '@/design-system/components/Button/button'
-import { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 /**
  * Notice — Toast / Alert 共用的視覺佈局層
  *
- * ── Typography: md tier ──
- * title: text-body (14px) leading-compact — 有 description 時加 font-medium
- * description: text-body (14px) leading-compact + text-fg-secondary (neutral-8)
+ * ── Typography: Family 2 reading-md(2026-06-15 user 拍板,off-grid 偏移收斂)──
+ * title: text-body (14px) default leading 1.5 — 有 description 時加 font-medium
+ * description: text-body (14px) default leading 1.5 + text-fg-secondary (neutral-8)
  * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。
+ * **行高 = reading 預設 1.5**(非 compact):Notice 是 Family 2 reading consumer,
+ * ItemContent 預設 mode='reading' + gap token `--item-gap-label-desc-reading` 名實相符。
+ * 原 `leading-compact`(1.3)= reading-gap + scanning-行高 混搭的 off-grid 偏移,已移除。
  *
  * ── Padding（固定,不隨 density 變） ──
  * px = px-4（16px）
@@ -58,7 +61,11 @@ export const SUBTLE_ICON_COLOR: Record<NoticeVariant, string> = {
 
 const NOTICE_LAYOUT = [
   'flex items-start gap-2 w-full',
-  'text-body leading-compact',
+  // 2026-06-15 user 拍板:Notice = 乾淨 Family 2 reading-md consumer。
+  // 原 `leading-compact`(1.3)是 off-grid 偏移(reading gap token + scanning 行高混搭、未文件化),
+  // 已移除 → label/desc 走 text-body reading 預設 1.5,與 ItemContent 預設 mode='reading' + gap
+  // token `--item-gap-label-desc-reading` 名實相符。詳 notice.spec.md「Typography」段。
+  'text-body',
   'px-4 py-3',
 ].join(' ')
 
@@ -124,8 +131,12 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
         />
 
         {(endContent || dismissible) && (
-          // @row-slot-handcraft-allow: Notice 是非-row alert（非 item-anatomy row），此 end slot 是 Notice 自身 layout 的 dismiss/endContent 容器，不是 row prefix/suffix → 不消費 ItemPrefix/ItemSuffix
-          <div className="flex items-center gap-2 shrink-0 h-[1lh]">
+          // 2026-06-15 user 拍板:消費 ItemSuffix primitive(原手刻 div + @row-slot-handcraft-allow
+          // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix
+          // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal
+          // 預設 false 故無 row inline-action 機制干擾。內裝 dismiss = Button iconOnly dismiss xs(banner
+          // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。
+          <ItemSuffix>
             {endContent}
             {dismissible && (
               <Button
@@ -138,7 +149,7 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
                 onClick={onDismiss}
               />
             )}
-          </div>
+          </ItemSuffix>
         )}
       </div>
     )

package/src/components/Sidebar/sidebar.spec.md

@@ -128,7 +128,9 @@ SidebarProvider              ← 全域 context（open 狀態、cookie、快捷
 - **Density**（md/lg）是**全域 UI 設定**,影響所有 `--field-height-*` tokens 的實際值
 - 兩者**獨立**:size="md" 在 density="md" 下是 32px row、在 density="lg" 下自動變 36px row
 
-**Chrome header 不跟 size 變**：`SidebarHeader` / `SidebarFooter` 固定用 `var(--chrome-header-height)`,只跟 **density** 連動,不跟 `size` prop 變——因為 header 是結構槽位,不是 row。
+**Chrome header 不跟 size 變**：`SidebarHeader` 固定用 `var(--chrome-header-height)`,只跟 **density** 連動,不跟 `size` prop 變——因為 header 是結構槽位,不是 row。**SidebarFooter 修正(2026-06-12 doc-to-code)**:footer 實作自 2026-04-14 起為 content-based(`flex flex-col py-2`,sidebar.tsx SidebarFooter,行為同 SidebarGroup),**非** fixed-h——單行高度由下方內容紀律保證,非結構鎖。
+
+**SidebarFooter user 區必單行(2026-06-12 明文,fork drift 防線)**:名字單行(`text-body-lg` truncate);職稱/email/工號等身份資訊歸 `ItemAvatar hoverCard` 的 ProfileCard(UserFooter canonical,sidebar.stories.tsx)。shadcn nav-user 的「name + email `text-xs` 兩行」是 demo 慣例非本 DS canonical(`text-xs` 同時違反下方 chrome typography 一律 `text-body-lg` 條);registry antiPattern `sidebar-footer-two-line` 機械攔。
 
 **SidebarHeader brand 必單行(2026-06-12 明文,fork drift anchor)**:Avatar 24 + 名稱單行,**無副標 slot**——Fixed-h chrome 結構上不可成長;plan/org 等第二行資訊歸 workspace switcher dropdown row,對齊 Slack/Notion/Linear 現行版單行。shadcn TeamSwitcher demo 的「Acme Inc + Enterprise」兩行是 demo 慣例非本 DS canonical(fork repo AI 曾以訓練先驗在 spec 沉默處回填此副標)。Registry antiPattern `sidebar-header-subtitle-second-line` 機械攔(flex-col 直接子層簽名)。
 
@@ -205,13 +207,13 @@ Gmail / Linear 的標準版型：上方 SidebarGroup 放扁平主導覽（Sideba
 
 ## Chrome header / footer 高度：density-responsive shared token
 
-`SidebarHeader` 和 `SidebarFooter` 的高度 = `var(--chrome-header-height)`，**不是寫死**，也**不是完全 content-based**。這個 token：
+`SidebarHeader` 的高度 = `var(--chrome-header-height)`，**不是寫死**，也**不是完全 content-based**(SidebarFooter 為 content-based,見上方 2026-06-12 修正)。這個 token：
 
 > **跨家族 SSOT pointer**:本元件 SidebarHeader 屬 **Chrome header(Fixed-h)家族**;border / padding / dismiss size / withTabs(tabs 進 header 時 border auto-suppress + tabs size 對應 + flush stack)的跨家族視覺契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify Sidebar 特有的高度 + token rationale。
 
 - md density: `3rem`（48px）
 - lg density: `3.5rem`（56px）
-- **跨元件共享**：sidebar header、sidebar footer、主內容 page header 都用同一個 token
+- **跨元件共享**：sidebar header、主內容 page header 都用同一個 token(sidebar footer 為 content-based,見上方 2026-06-12 修正)
 - **隨 density 同步變**
 
 ### 為什麼是這個設計（不是 h-12 寫死 或 py-3 純 padding）

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

@@ -55,7 +55,9 @@
 
 **用途**：頁面上的閱讀式單列。使用者讀取內容、需要 description 多行、looser density。
 
-**結構**：`[larger icon/avatar 20-24px] [content: label + multi-line description OK] [suffix action/button/counter]`，reading typography（default leading），字體略大於 Family 1。
+**結構**：`[icon/avatar 16-20px(`ICON_SIZE` sm/md=16, lg=20)] [content: label + multi-line description OK] [suffix action/button/counter]`，reading typography（default leading 1.5）。
+
+> **2026-06-15 修**：本行原寫 icon「20-24px」,與 item-anatomy.tsx 的 `ICON_SIZE = {sm:16, md:16, lg:20}` 常數打架（24px 不存在於常數,md 是 16 非 20+）。已對齊**實作真值 ICON_SIZE**。Family 2 與 Family 1 的 icon **px 值相同**（皆走 ICON_SIZE）;兩 family 的差別在 **typography 行高 + density**（reading 1.5 / scanning 1.3）+ description 多行能力,**不在 icon px**。
 
 **消費者**：
 
@@ -791,7 +793,7 @@ Block 模式時 checkbox 不在 label 第一行——它跟 avatar 在同一高
 | Consumer | Primitive 消費 | Rationale |
 |----------|--------------|-----------|
 | **FileItem**(rich + compact) | ✅ ItemContent + ItemPrefix(hover action 為 Button xs iconOnly,非 ItemInlineActionButton——2026-04-23 user 統一,見 file-item.tsx)| 純 row-item layout,完美 fit |
-| **Notice / Alert / Toast** | ✅ ItemContent + ItemPrefix | title+desc 標準 row-item 結構 |
+| **Notice / Alert / Toast** | ✅ ItemContent + ItemPrefix + ItemSuffix | 乾淨 reading-md consumer（2026-06-15 收斂:原 root `leading-compact` off-grid 偏移已移除、suffix 改消費 ItemSuffix;詳 notice.spec.md Typography 段）|
 | **ProfileCard** | ✅ ItemContent(+ `labelTruncate=false` + `labelClassName` escape hatch) | 偏離 rationale:card context 用 `text-body-lg font-medium`,非一般 body label |
 | **MenuItem** | ✅ ItemContent(`mode="scanning"` + `size="md"\|"lg"` 正交)+ `itemPrefixAlignVariants` cva SSOT | Content 用 ItemContent 配合 size-aware scanning mode(sm/md = caption / lg = body-compact);label+desc clamp 透過 className escape hatch(MenuItem 特化 labelMaxLines / descMaxLines 語意) |
 | **Sidebar / TreeView** | ✅ ItemPrefix(+ 其他 primitives) | Label-only(無 description),不需 ItemContent |

package/src/patterns/header-canonical/header-canonical.spec.md

@@ -288,6 +288,7 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 - ❌ Hardcode `h-16` / `h-14` / `h-12` 自寫 chrome header 高度 — 必 `--chrome-header-height`
 - ❌ Header 內 close X 用 `size="md"` 或 `size="lg"`(real grep 100% sm)
 - ❌ Tabs default 覆寫回 `size="md"`(W5 + W6)— cva default 已是 sm,不該寫回 md
+- ❌ ChromeHeader children 塞 `flex-col` 第二行(title + 副標/description)— Chrome 家族永遠 single-row(上方「為什麼兩家族」段);頁面說明文字歸 content 區 page heading,非 chrome(2026-06-12 fork-drift 防線,同 sidebar.spec.md SidebarHeader 必單行條;registry antiPattern `chromeheader-subtitle-second-line` 機械攔)
 
 ---