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

package/src/tokens/color/color.stories.tsx

@@ -0,0 +1,403 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import React from 'react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Color',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+色彩 token 系統。互動 / 狀態語意一律使用語義 token；categorical 靜態多色場景（Tag / Avatar / Calendar event）依 spec 直接消費 primitive 色票（見 color.spec.md「消費規則」）。
+
+完整規則：\`packages/design-system/src/tokens/color/color.spec.md\`
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function SwatchBg({
+  bg,
+  label,
+  desc,
+  bordered = false,
+}: {
+  bg: string
+  label: string
+  desc: string
+  bordered?: boolean
+}) {
+  return (
+    <div className="space-y-1.5">
+      <div
+        className={`h-14 w-full rounded-md ${bordered ? 'border border-border' : ''}`}
+        style={{ background: bg }}
+      />
+      <code className="block text-caption font-medium">{label}</code>
+      <span className="block text-caption text-fg-muted">{desc}</span>
+    </div>
+  )
+}
+
+function SwatchText({
+  className,
+  label,
+  desc,
+}: {
+  className: string
+  label: string
+  desc: string
+}) {
+  return (
+    <div className="border-b border-border py-3 last:border-0">
+      <p className={`text-body mb-1 ${className}`}>
+        此操作將永久刪除該筆資料，確認後無法復原。
+      </p>
+      <div className="flex gap-3">
+        <code className="text-caption font-medium">{label}</code>
+        <span className="text-caption text-fg-muted">{desc}</span>
+      </div>
+    </div>
+  )
+}
+
+function SectionLabel({ children }: { children: React.ReactNode }) {
+  return (
+    <p className="text-caption font-medium uppercase tracking-wider text-fg-muted">
+      {children}
+    </p>
+  )
+}
+
+
+// ── 1. Primitives ────────────────────────────────────────────────────────────
+
+export const Primitives: Story = {
+  name: '原始色票',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '原始色票（Layer 1）。互動 / 狀態語意**不得直接使用** primitive，一律透過語義 token；例外：Tag / Avatar / Calendar 等 categorical 多色區分場景直接消費 primitive（color.spec.md「消費規則」）。\n\n' +
+          '**已映射為語義 token 的色相：** blue → primary、deep-orange → error + notification、green → success、yellow → warning\n\n' +
+          '**其餘色相（orange、amber、lime、turquoise、indigo、purple、magenta、red）** 保留給 data visualization、categorization tag、avatar 等需要多色區分的場景。',
+      },
+    },
+  },
+  render: () => {
+    const SEMANTIC_MAP: Record<string, string> = {
+      blue: 'primary',
+      'deep-orange': 'error + notification',
+      green: 'success',
+      yellow: 'warning',
+    }
+    const HUES: Array<{ name: string; suffix?: string }> = [
+      { name: 'neutral', suffix: '-opaque' },
+      { name: 'blue' },
+      { name: 'deep-orange' },
+      { name: 'orange' },
+      { name: 'amber' },
+      { name: 'yellow' },
+      { name: 'lime' },
+      { name: 'green' },
+      { name: 'turquoise' },
+      { name: 'indigo' },
+      { name: 'purple' },
+      { name: 'magenta' },
+      { name: 'red' },
+    ]
+    return (
+      <div className="space-y-1 max-w-2xl">
+        <div className="grid pb-2 border-b border-border mb-2" style={{ gridTemplateColumns: '160px repeat(9, 1fr)' }}>
+          <span className="text-caption text-fg-muted">hue</span>
+          {[1,2,3,4,5,6,7,8,9].map(n => (
+            <span key={n} className="text-caption text-fg-muted text-center">{n}</span>
+          ))}
+        </div>
+        {HUES.map(({ name, suffix = '' }) => {
+          const semantic = SEMANTIC_MAP[name]
+          return (
+            <div key={name} className="grid items-center gap-x-1 py-0.5" style={{ gridTemplateColumns: '160px repeat(9, 1fr)' }}>
+              <div className="flex items-center gap-1.5 truncate">
+                <span className="text-caption text-fg-muted">{name}</span>
+                {semantic && <span className="text-footnote text-[var(--primary)] font-medium">→ {semantic}</span>}
+              </div>
+              {[1,2,3,4,5,6,7,8,9].map(n => (
+                <div
+                  key={n}
+                  className="h-6 rounded-md border border-[var(--black-a06)]"
+                  style={{ background: `var(--color-${name}-${n}${suffix})` }}
+                  title={`--color-${name}-${n}${suffix}`}
+                />
+              ))}
+            </div>
+          )
+        })}
+        <p className="pt-3 text-caption text-fg-muted">
+          neutral 顯示 opaque 版本。-6 為基底色，其餘由相對色語法推導。無 → 標記的色相保留給 data visualization / categorization。
+        </p>
+      </div>
+    )
+  },
+}
+
+
+// ── 2. Surface ───────────────────────────────────────────────────────────────
+
+export const Surface: Story = {
+  name: '表面層',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Surface = 空間容器（內容坐在上面的背景），不帶語義。' +
+          'canvas → surface → surface-raised 三層由底到高疊加。overlay / tooltip 也屬於 surface（空間用途）。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-xl space-y-4">
+      <div className="grid grid-cols-3 gap-4">
+        <SwatchBg bg="var(--canvas)"         bordered label="bg-canvas"         desc="頁面最底層背景" />
+        <SwatchBg bg="var(--surface)"        bordered label="bg-surface"        desc="card、sidebar、table" />
+        <SwatchBg bg="var(--surface-raised)" bordered label="bg-surface-raised" desc="modal、popover、dropdown" />
+      </div>
+      <div className="grid grid-cols-2 gap-4 max-w-sm">
+        <div className="space-y-1.5">
+          <div className="h-14 w-full rounded-md border border-border" style={{ background: 'var(--overlay)' }} />
+          <code className="block text-caption font-medium">bg-overlay</code>
+          <span className="block text-caption text-fg-muted">dialog backdrop 遮罩</span>
+        </div>
+        <div className="space-y-1.5">
+          <div className="h-14 w-full rounded-md flex items-center justify-center" style={{ background: 'var(--tooltip)' }}>
+            <span className="text-caption text-white">tooltip</span>
+          </div>
+          <code className="block text-caption font-medium">bg-tooltip</code>
+          <span className="block text-caption text-fg-muted">tooltip 深色底（不透明）</span>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+
+// ── 3. Text ──────────────────────────────────────────────────────────────────
+
+export const Text: Story = {
+  name: '文字色',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '文字從主要資訊到 disabled 的四個層級。一律使用 neutral alpha token，疊加在任何背景都能維持對比。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-xl">
+      <SwatchText className="text-foreground"   label="text-foreground"   desc="主要文字、一般資訊" />
+      <SwatchText className="text-fg-secondary" label="text-fg-secondary" desc="次要資訊、helper text" />
+      <SwatchText className="text-fg-muted"     label="text-fg-muted"     desc="placeholder、caption、弱化 icon" />
+      <SwatchText className="text-fg-disabled"  label="text-fg-disabled"  desc="disabled 文字" />
+      <div className="mt-4 flex items-center gap-3 px-3 py-2 rounded-md" style={{ backgroundColor: 'var(--primary)' }}>
+        <span style={{ color: 'var(--on-emphasis)' }} className="text-body font-medium">text-on-emphasis</span>
+        <span style={{ color: 'var(--on-emphasis)' }} className="text-caption opacity-80">Avatar color variant / Steps filled indicator 等飽和色底的對比文字</span>
+      </div>
+    </div>
+  ),
+}
+
+
+// ── 4. Semantic ──────────────────────────────────────────────────────────────
+
+export const Semantic: Story = {
+  name: '語義色',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Primary = 互動入口（按鈕、連結）。Info = 系統狀態（in-progress、active）。subtle 為淡底填充，用於 badge、banner、checked 背景（Tag 的多色淡底走 categorical primitive step-1，非 semantic subtle，見「原始色票」）。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-2xl space-y-8">
+
+      {/* Action */}
+      <div>
+        <SectionLabel>Action — Primary</SectionLabel>
+        <div className="mt-3 grid grid-cols-2 gap-3 max-w-xs">
+          <SwatchBg bg="var(--primary)"        label="bg-primary"        desc="按鈕、連結、focus ring" />
+          <SwatchBg bg="var(--primary-subtle)" bordered label="bg-primary-subtle" desc="淡底 / checked 底" />
+        </div>
+      </div>
+
+      {/* Status */}
+      <div>
+        <SectionLabel>Status</SectionLabel>
+        <div className="mt-3" style={{ display: 'grid', gridTemplateColumns: '44px 1fr 1fr 1fr 1fr', gap: '8px', alignItems: 'start' }}>
+          <div />
+          {['Info', 'Error', 'Success', 'Warning'].map(n => (
+            <span key={n} className="text-caption text-fg-muted text-center block">{n}</span>
+          ))}
+          <span className="text-caption text-fg-muted self-center">Base</span>
+          <SwatchBg bg="var(--info)"    label="bg-info"    desc="資訊 / 進行中 / active" />
+          <SwatchBg bg="var(--error)"   label="bg-error"   desc="錯誤 / 危險" />
+          <SwatchBg bg="var(--success)" label="bg-success" desc="成功" />
+          <SwatchBg bg="var(--warning)" label="bg-warning" desc="警告" />
+          <span className="text-caption text-fg-muted self-center">Subtle</span>
+          <SwatchBg bg="var(--info-subtle)"    bordered label="bg-info-subtle"    desc="淡底" />
+          <SwatchBg bg="var(--error-subtle)"   bordered label="bg-error-subtle"   desc="淡底" />
+          <SwatchBg bg="var(--success-subtle)" bordered label="bg-success-subtle" desc="淡底" />
+          <SwatchBg bg="var(--warning-subtle)" bordered label="bg-warning-subtle" desc="淡底" />
+        </div>
+      </div>
+
+      {/* Other */}
+      <div>
+        <SectionLabel>Other</SectionLabel>
+        <div className="mt-3 grid grid-cols-2 gap-3 max-w-xs">
+          <SwatchBg bg="var(--notification)" label="bg-notification" desc="未讀計數 / 通知紅點" />
+          <SwatchBg bg="var(--brand)"        label="bg-brand"        desc="品牌色，固定色" />
+        </div>
+      </div>
+
+      {/* Border */}
+      <div>
+        <SectionLabel>Border</SectionLabel>
+        <div className="mt-3 space-y-2.5">
+          {[
+            { label: 'border-border',  desc: '元件標準邊框',   style: { border: '2px solid var(--border)' } },
+            { label: 'border-divider', desc: '分隔線（比 border 更淡）', style: { borderBottom: '2px solid var(--divider)' } },
+          ].map(({ label, desc, style }) => (
+            <div key={label} className="flex items-center gap-4">
+              <div className="h-10 w-24 rounded-md bg-surface" style={style} />
+              <div>
+                <code className="text-caption font-medium">{label}</code>
+                <span className="ml-2 text-caption text-fg-muted">{desc}</span>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+
+    </div>
+  ),
+}
+
+
+// ── 5. Interactive ───────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
+  name: '互動色',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '互動色的三種狀態。使用語義 token（`bg-primary-hover`），不直接引用 primitive step。\n\n' +
+          '```tsx\n' +
+          '<a className="text-primary hover:text-primary-hover">連結</a>\n' +
+          '<button className="bg-primary hover:bg-primary-hover active:bg-primary-active" />\n' +
+          '```\n\n' +
+          '> 色盤對應（內部實作）：-1 = subtle、-5 = hover、-6 = base、-7 = active。\n\n' +
+          '---\n\n' +
+          '#### Neutral Interaction\n\n' +
+          '低調互動背景，用於 list row、tree node。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-lg space-y-8">
+      {/* Colored interactive states */}
+      {[
+        { name: 'Primary', prefix: 'primary', hover: '--primary-hover', base: '--primary', active: '--primary-active' },
+        { name: 'Info',    prefix: 'info',    hover: '--info-hover',    base: '--info',    active: '--info-active' },
+        { name: 'Error',   prefix: 'error',   hover: '--error-hover',   base: '--error',   active: '--error-active' },
+        { name: 'Success', prefix: 'success', hover: '--success-hover', base: '--success', active: '--success-active' },
+        { name: 'Warning', prefix: 'warning', hover: '--warning-hover', base: '--warning', active: '--warning-active' },
+      ].map(({ name, prefix, hover, base, active }) => (
+        <div key={name}>
+          <span className="text-caption text-fg-muted mb-1.5 block">{name}</span>
+          <div className="grid grid-cols-3 gap-2">
+            <SwatchBg bg={`var(${hover})`}  label="hover"  desc={`bg-${prefix}-hover`} />
+            <SwatchBg bg={`var(${base})`}   label="base"   desc={`bg-${prefix}`} />
+            <SwatchBg bg={`var(${active})`} label="active" desc={`bg-${prefix}-active`} />
+          </div>
+        </div>
+      ))}
+
+      {/* Ghost */}
+      <div>
+        <SectionLabel>Neutral Interaction — Default family（hover/active）+ Selected family（持續選中）</SectionLabel>
+        <div className="mt-3 space-y-1">
+          {[
+            { label: '正常狀態（無背景）', bg: 'transparent',                    token: '' },
+            { label: 'Hover 回饋',         bg: 'var(--neutral-hover)',        token: 'bg-neutral-hover' },
+            { label: 'Active 回饋（:active click）', bg: 'var(--neutral-active)', token: 'bg-neutral-active' },
+            { label: 'Selected 持續選中',   bg: 'var(--neutral-selected)',     token: 'bg-neutral-selected' },
+            { label: 'Selected + Hover（切換鈕專屬，變淺）', bg: 'var(--neutral-selected-hover)', token: 'bg-neutral-selected-hover' },
+            { label: 'Selected + 鍵盤焦點（深一階）', bg: 'var(--neutral-selected-focus)', token: 'bg-neutral-selected-focus' },
+            { label: 'Selected + Active（按壓專屬）', bg: 'var(--neutral-selected-active)', token: 'bg-neutral-selected-active' },
+            { label: 'Disabled 狀態',      bg: 'var(--bg-disabled)',          token: 'bg-disabled' },
+          ].map(({ label, bg, token }) => (
+            <div
+              key={label}
+              className="flex items-center gap-3 rounded-md px-3 py-2 text-body"
+              style={{ background: bg }}
+            >
+              <span className="h-4 w-4 shrink-0 rounded-md bg-[var(--fg-disabled)]" />
+              <span className="flex-1 text-fg-disabled">{label}</span>
+              {token && <code className="text-caption text-fg-muted">{token}</code>}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+}
+export const FunctionalHighlight: Story = {
+  name: '反白與搜尋配對',
+  render: () => (
+    <div className="max-w-xl space-y-6">
+      <section className="space-y-2">
+        <h3 className="text-body font-medium">文字反白(::selection)</h3>
+        <p data-selection-demo className="rounded-md border border-border bg-surface p-4 text-body">
+          第三季營收報告已於 10 月 14 日送交財務委員會審閱,附件包含分區銷售明細與年度預測修正。
+        </p>
+        <span className="block text-caption text-fg-muted">
+          此段由 play 自動反白 — 底色 <code>--text-selection</code>(blue-5 @ 30% 半透明,字色不變)
+        </span>
+      </section>
+      <section className="space-y-2">
+        <h3 className="text-body font-medium">頁內搜尋配對(Ctrl+F)</h3>
+        <p className="rounded-md border border-border bg-surface p-4 text-body">
+          搜尋「報表」:月度<mark className="rounded-xs bg-search-match text-inherit">報表</mark>
+          已歸檔;季度<mark className="rounded-xs bg-search-match-current text-inherit">報表</mark>
+          為目前所在配對,尚待審核;年度<mark className="rounded-xs bg-search-match text-inherit">報表</mark>
+          排定下週產出。
+        </p>
+        <span className="block text-caption text-fg-muted">
+          全部配對 <code>bg-search-match</code>(amber-3)/ 目前這一筆 <code>bg-search-match-current</code>(amber-5)— 雙檔制對齊 VS Code find 與瀏覽器原生慣例
+        </span>
+      </section>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const target = canvasElement.querySelector('[data-selection-demo]')
+    if (target) {
+      const range = document.createRange()
+      range.selectNodeContents(target)
+      const selection = window.getSelection()
+      selection?.removeAllRanges()
+      selection?.addRange(range)
+    }
+  },
+}

package/src/tokens/color/primitives.css

@@ -26,7 +26,9 @@
 
    Scale 推導規則（相對公式，確保任何 base-6 亮度都能產生單調色階）：
    較亮方向: L = l + (1 − l) × F   F: 1=0.90  2=0.75  3=0.58  4=0.40  5=0.20
-   較暗方向: L = l × D             D: 7=0.82  8=0.62  9=0.44  10=0.28  (dark 1=0.18)
+   較暗方向: L = l × D             D: 7=0.82  8=0.62  9=0.44  10=0.28
+   dark step-1 例外(2026-07-04 Q10 統一): 全 12 色相 alpha 公式 oklch(from base-6 l c h / calc(0.12/l))
+     — 感知亮度統一(高亮色相除以較大 l 得較低 alpha),透明疊底不隨 surface 漂移;對齊 Radix Colors dark alpha
    C×（不變）:
      lighter: 1=0.14  2=0.22  3=0.45  4=0.75  5=0.90
      darker:  7=0.93  8=0.82  9=0.65  10=0.48  (dark 5=0.98, dark 7=0.88)
@@ -245,6 +247,13 @@
 
 }
 
+/* Tailwind bridge for absolute anchors.
+   Keep the bridge in the primitive color SSOT so text-white/bg-white ship to consumers. */
+@theme inline {
+  --color-white: oklch(1 0 0);
+  --color-black: oklch(0 0 0);
+}
+
 
 /* ── Layer 1 — Dark Mode Overrides ── */
 [data-theme="dark"] {
@@ -276,7 +285,10 @@
   --color-neutral-9-opaque: color-mix(in srgb, white var(--_na9), black);
 
   /* Blue */
-  --color-blue-6:  oklch(0.60 0.22 258);
+  /* 2026-07-16 user 拍板:dark 主色對比升級 — 0.60→0.63(≈#2C84FF,對齊 Apple dark systemBlue)。
+     card/table/浮層 surface 上互動文字 4.07-4.10:1(AA ✗)→ 4.63-4.67:1(AA ✓);canvas 5.53:1。
+     其餘 1-10 階不手動指定,由本基準經下方既有相對公式自動推導(單一基準,設計語言不變)。 */
+  --color-blue-6:  oklch(0.63 0.22 258);
   --color-blue-1:  oklch(from var(--color-blue-6) l c h / calc(0.12 / l));
   --color-blue-2:  oklch(from var(--color-blue-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-blue-3:  oklch(from var(--color-blue-6) calc(l * 0.44) calc(c * 0.82) h);
@@ -301,7 +313,7 @@
 
   /* Orange */
   --color-orange-6:  oklch(0.76 0.16 57);
-  --color-orange-1:  oklch(from var(--color-orange-6) calc(l * 0.18) calc(c * 0.48) h);
+  --color-orange-1:  oklch(from var(--color-orange-6) l c h / calc(0.12 / l)); /* 2026-07-04 Q10 拍板:統一 dark step-1 alpha 公式(原 opaque l*0.18 為 2026-05 遷移漏轉;Radix Colors dark alpha 全色相一致) */
   --color-orange-2:  oklch(from var(--color-orange-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-orange-3:  oklch(from var(--color-orange-6) calc(l * 0.44) calc(c * 0.82) h);
   --color-orange-4:  oklch(from var(--color-orange-6) calc(l * 0.62) calc(c * 0.93) h);
@@ -313,7 +325,7 @@
 
   /* Amber */
   --color-amber-6:  oklch(0.82 0.15 76);
-  --color-amber-1:  oklch(from var(--color-amber-6) calc(l * 0.18) calc(c * 0.48) h);
+  --color-amber-1:  oklch(from var(--color-amber-6) l c h / calc(0.12 / l)); /* 2026-07-04 Q10:同上統一 alpha 公式 */
   --color-amber-2:  oklch(from var(--color-amber-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-amber-3:  oklch(from var(--color-amber-6) calc(l * 0.44) calc(c * 0.82) h);
   --color-amber-4:  oklch(from var(--color-amber-6) calc(l * 0.62) calc(c * 0.93) h);
@@ -337,7 +349,7 @@
 
   /* Lime */
   --color-lime-6:  oklch(0.84 0.19 122);
-  --color-lime-1:  oklch(from var(--color-lime-6) calc(l * 0.18) calc(c * 0.48) h);
+  --color-lime-1:  oklch(from var(--color-lime-6) l c h / calc(0.12 / l)); /* 2026-07-04 Q10:同上統一 alpha 公式 */
   --color-lime-2:  oklch(from var(--color-lime-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-lime-3:  oklch(from var(--color-lime-6) calc(l * 0.44) calc(c * 0.82) h);
   --color-lime-4:  oklch(from var(--color-lime-6) calc(l * 0.62) calc(c * 0.93) h);
@@ -360,7 +372,11 @@
   --color-green-10: oklch(from var(--color-green-6) calc(l + (1 - l) * 0.75) calc(c * 0.14) h);
 
   /* Turquoise */
-  --color-turquoise-6:  oklch(0.57 0.10 225);
+  /* 2026-07-16 user 拍板修正:原 oklch(0.57 0.10 225)為複製 spec 假想範例的錯值 — 全 12 色相唯一
+     dark 改色相(196→225 = 偏藍)、唯一 L 降(其餘全升)、唯一 C 升,三重違反設計語言。
+     修回 H=196(同 light,Apple systemBlue/Teal dark 同樣色相恆定);L 照 11 色相經驗律內插
+     (L≤0.58 → +0.05 / L≥0.70 → +0.03;0.64 居中 → +0.04)= 0.68;C 照 ×0.95 2dp 慣例 = 0.09。 */
+  --color-turquoise-6:  oklch(0.68 0.09 196);
   --color-turquoise-1:  oklch(from var(--color-turquoise-6) l c h / calc(0.12 / l));
   --color-turquoise-2:  oklch(from var(--color-turquoise-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-turquoise-3:  oklch(from var(--color-turquoise-6) calc(l * 0.44) calc(c * 0.82) h);
@@ -409,7 +425,7 @@
 
   /* Red */
   --color-red-6:  oklch(0.51 0.21 25);
-  --color-red-1:  oklch(from var(--color-red-6) calc(l * 0.18) calc(c * 0.48) h);
+  --color-red-1:  oklch(from var(--color-red-6) l c h / calc(0.12 / l)); /* 2026-07-04 Q10:同上統一 alpha 公式 */
   --color-red-2:  oklch(from var(--color-red-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-red-3:  oklch(from var(--color-red-6) calc(l * 0.44) calc(c * 0.82) h);
   --color-red-4:  oklch(from var(--color-red-6) calc(l * 0.62) calc(c * 0.93) h);