@qijenchen/design-system 0.1.0-beta.25 → 0.1.0-beta.27

package/ds-canonical/hooks/check_opacity_token_usage.sh

@@ -105,7 +105,7 @@ if [ -n "$HITS_RADIUS" ]; then
   VIOLATIONS="${VIOLATIONS}\n   [radius out-of-range] $(echo "$HITS_RADIUS" | tr '\n' ' ')"
 fi
 
-# 7) Shadow Tailwind size(shadow-sm/md/lg/xl/2xl/inner — DS 用 shadow-[var(--elevation-*)])
+# 7) Shadow Tailwind size(shadow-sm/md/lg/xl/2xl/inner — DS 用 shadow-[var(--elevation-N)] N∈{100,200,300})
 HITS_SHADOW=$(echo "$NEW_CONTENT" | grep -oE "\bshadow-(sm|md|lg|xl|2xl|inner)\b" | sort -u || true)
 if [ -n "$HITS_SHADOW" ]; then
   VIOLATIONS="${VIOLATIONS}\n   [elevation size] $(echo "$HITS_SHADOW" | tr '\n' ' ')"

package/ds-canonical/hooks/lib/_token_hygiene.sh

@@ -6,7 +6,7 @@
 #    (these are shadcn safety-net aliases; our DS code MUST use direct tokens)
 # 2. Tailwind v4 `[--foo]` shorthand — must be `var(--foo)` wrapped; historical bug:
 #    Sidebar's `w-[--sidebar-width]` broke 8 places (silent fail, no error)
-# 3. Hardcoded Tailwind shadow — `shadow-sm/md/lg/xl/2xl` is forbidden; must use `shadow-[var(--elevation-*)]`
+# 3. Hardcoded Tailwind shadow — `shadow-sm/md/lg/xl/2xl` is forbidden; must use `shadow-[var(--elevation-N)] N∈{100,200,300}`
 # 4. Native overflow-{auto,scroll} without ScrollArea — cross-OS scrollbar drift
 #    (macOS overlay 不吃寬 / Windows always-visible 吃 17px = 跨 OS 跑版)
 #    應改用 ScrollArea(Components/ScrollArea/)— overlay scrollbar 跨 OS 一致
@@ -52,7 +52,7 @@ fi
 
 # ── Check 3: Hardcoded Tailwind shadow ────────────────────────────────────────
 # shadow-sm/md/lg/xl/2xl 是 Tailwind 預設,繞過 elevation token 系統——禁止.
-# 允許:shadow-none / shadow-[var(--elevation-*)] / shadow-[calc(...)]
+# 允許:shadow-none / shadow-[var(--elevation-N)] N∈{100,200,300} / shadow-[calc(...)]
 SHADOW_PATTERN='\bshadow-(sm|md|lg|xl|2xl|inner)\b'
 SHADOW_HITS=$(grep -nE "$SHADOW_PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
 if [ -n "$SHADOW_HITS" ]; then

package/ds-canonical/hooks/retired/check_container_breathing.sh

@@ -121,7 +121,7 @@ while IFS= read -r LINE || [ -n "$LINE" ]; do
   視覺邊界:${REASONS# }
   > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
   判斷: 視覺容器(bg/border/shadow)必有 inner padding,不讓內容物貼容器邊。
-        建議:chrome 層用 p-[var(--layout-space-loose/tight)] / px-3 等。
+        建議:chrome 層用 p-[var(--layout-space-N) N∈{loose,tight}] / px-3 等。
         若是 (a) chrome primitive override 刻意 p-0,(b) 父容器另外提供 padding,
         (c) 子元件自帶足夠 padding → 加 // @breathing-exempt-next 到此行上一行。
         SSOT: patterns/element-anatomy/element-anatomy.spec.md「視覺容器 breathing invariant」"

package/ds-canonical/references/tailwind-gotchas.md

@@ -58,7 +58,7 @@
 
 | 類別 | 為什麼禁止 | 改用 |
 |------|----------|------|
-| `shadow-sm/md/lg/xl/2xl` | 繞過 elevation token 系統,沒跟 dark mode 調整聯動 | `shadow-[var(--elevation-100/200/300)]` |
+| `shadow-sm/md/lg/xl/2xl` | 繞過 elevation token 系統,沒跟 dark mode 調整聯動 | 用 `shadow-[var(--elevation-N)]` 其中 N ∈ `{100, 200, 300}`(per elevation.spec.md tier)|
 | 硬寫色值 `#xxx`, `rgb(...)`, `bg-red-500` | 繞過 semantic token,dark mode / brand swap 會斷 | 對應 semantic token |
 | Tailwind 預設 typography `text-xs/sm/base/lg` | 我們有自己的 `text-caption/body/body-lg/h1/h2` 系統 | 用我們的 typography token |
 | 硬寫 px 值 `w-[48px]` 當有 token | 失去 token 關聯,改值時零散處要一起改 | 對應 token 或 calc() |

package/ds-canonical/rules/ui-development.md

@@ -52,7 +52,7 @@ paths:
 
 1. **CSS variable 必 `var()` 包覆** — `w-[var(--foo)]` 而非 `w-[--foo]`(v4 silent 失效)
 2. **自訂 utility 必在 `lib/utils.ts` 註冊 group** — 否則 tailwind-merge 誤判 strip
-3. **禁 `shadow-sm/md/lg` / `text-xs/sm/base` / 硬寫色值** — 用 `shadow-[var(--elevation-*)]` / `text-body`
+3. **禁 `shadow-sm/md/lg` / `text-xs/sm/base` / 硬寫色值** — 用 `shadow-[var(--elevation-N)]` (N ∈ {100,200,300}) / `text-body`
 4. **禁 shadcn compat alias**(`bg-popover` / `text-muted-foreground` / `bg-accent` 等)— 用 direct token
 5. **禁 primitive 色名作 utility**(`bg-neutral-3` / `text-blue-6`)— 用 semantic utility 或 `bg-[var(--color-blue-6)]`
 

package/ds-canonical/skills/design-system-audit/references/audit-prompts.md

@@ -614,7 +614,7 @@ Forbidden in our code (these SHOULD be migrated to direct tokens):
 - `bg-card` / `text-card-foreground` → `bg-surface` / `text-foreground`
 - `text-primary-foreground` → `text-white`
 - `border-input` → `border-border`
-- `shadow-md / shadow-sm / shadow-lg / shadow-xl / shadow-2xl` → `shadow-[var(--elevation-*)]`
+- `shadow-md / shadow-sm / shadow-lg / shadow-xl / shadow-2xl` → `shadow-[var(--elevation-N)]` (N ∈ {100,200,300})
 
 OK (these are OUR approved tokens, not shadcn aliases):
 - `bg-muted` (semantic.css keeps --muted as real token)

package/ds-canonical/templates/_README.md

@@ -0,0 +1,23 @@
+// AUTO-GENERATED canonical reference from product-workspace/apps/template/src/App.tsx
+# DS canonical templates
+
+This directory ships **canonical app templates** for consumer apps to mirror.
+Per user 2026-05-27「ds repo push main → PW template 永遠 latest」directive.
+
+## Files
+
+- `dashboard-app.tsx` — AppShell + Sidebar + DashboardPage canonical full composition
+  (aligned with `sidebar.stories.tsx#IconCollapse` + `header-canonical.spec.md:57-72`)
+
+## Sync mechanism
+
+DS bump → `ssot-sync-dispatch.yml` dispatch → PW `sync-design-system.yml` 收 event:
+1. `npm update` design-system + storybook-config(既有)
+2. **NEW**: pull `node_modules/@qijenchen/design-system/ds-canonical/templates/dashboard-app.tsx`
+   diff against PW `apps/template/src/App.tsx`
+3. If drift → auto-create PR(NOT direct push to main — user review)
+
+Fork users 從 PW main fork → 取到當下最新 canonical baseline。Fork 後 diverge customization 是 fork user 自己責任。
+
+## SSOT chain
+DS canonical(此 file)→ npm pkg ship → PW sync auto-PR → fork user fork 取 latest.

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

@@ -0,0 +1,145 @@
+// 完整 AppShell 範例 — 對齊 DS canonical `sidebar.stories.tsx#IconCollapse` baseline
+// (per `.claude/rules/story-rules.md`「Production-grade composition fidelity」+ M23(d) nearest-same-purpose canonical wins)
+//
+// @story-baseline: @qijenchen/design-system/components/Sidebar/sidebar.stories.tsx#IconCollapse
+//
+// SSOT 鐵律:
+//   - Consumer 只 import `@qijenchen/design-system` public exports
+//   - 禁修改 DS source(走 fork DS repo)
+//   - 視覺 token 透過 DS 提供的 `@qijenchen/design-system/styles/tokens` 載入
+//
+// Fork user 替換步驟:
+//   1. 替換 NAV array(新 product 的真實導覽項)
+//   2. 替換 WorkspaceBrand 內 workspace 名 / Avatar 顏色
+//   3. 替換 DashboardPage 為真實業務 widgets(DataTable / Chart / Card 等 DS 元件)
+//   4. 替換 PageHeader rightSlot 的 primary action(若有)
+
+import { useState } from 'react'
+import {
+  AppShell,
+  SidebarProvider,
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarTrigger,
+  TooltipProvider,
+  Avatar,
+  ItemAvatar,
+  Button,
+} from '@qijenchen/design-system'
+import { LayoutDashboard, Users, Settings, FileText, BarChart3 } from 'lucide-react'
+
+const NAV = [
+  { id: 'dashboard', label: 'Dashboard', icon: LayoutDashboard },
+  { id: 'customers', label: 'Customers', icon: Users },
+  { id: 'orders', label: 'Orders', icon: FileText },
+  { id: 'reports', label: 'Reports', icon: BarChart3 },
+  { id: 'settings', label: 'Settings', icon: Settings },
+] as const
+
+// ── Sidebar(對齊 DS IconCollapse baseline:collapsible="icon" + WorkspaceBrand + footer)──
+function AppSidebar() {
+  return (
+    <Sidebar collapsible="icon">
+      <SidebarHeader>
+        {/* Chrome header avatar canonical(per header-canonical.spec.md:57-72):chrome header 不是 row context → raw <Avatar size={24}>,禁用 <ItemAvatar>(會誤啟動 row anatomy lookup)*/}
+        <div className="flex items-center gap-2 min-w-0 group-data-[collapsible=icon]:justify-center">
+          <Avatar alt="Acme Product" size={24} shape="square" color="blue" solid />
+          <span className="text-body-lg font-medium truncate group-data-[collapsible=icon]:hidden">Acme Product</span>
+        </div>
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {NAV.map(({ id, label, icon }) => (
+                <SidebarMenuItem key={id}>
+                  <SidebarMenuButton id={id} startIcon={icon} tooltip={label}>
+                    {label}
+                  </SidebarMenuButton>
+                </SidebarMenuItem>
+              ))}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarFooter>
+        {/* 對齊 DS canonical UserFooter(sidebar.stories.tsx):asChild + <div role="group"> + data-sidebar="menu-label" 必有,否則 SidebarMenuButton 把 children 全 wrap 進 ItemLabel 視覺垂直 stack */}
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton asChild>
+              <div role="group" aria-label="當前使用者">
+                <ItemAvatar alt="Current user" color="blue" />
+                <span data-sidebar="menu-label" className="min-w-0 flex-1 truncate">當前使用者</span>
+              </div>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarFooter>
+    </Sidebar>
+  )
+}
+
+// ── PageHeader(對齊 DS canonical chrome-header pattern:fixed --chrome-header-height + SidebarTrigger + title)──
+// SidebarTrigger 必有(primary-sidebar mode 的 menu toggle 入口,⌘B keyboard shortcut)
+function PageHeader({ title, rightSlot }: { title: string; rightSlot?: React.ReactNode }) {
+  return (
+    <header className="flex items-center gap-2 h-[var(--chrome-header-height)] px-[var(--layout-space-loose)] bg-surface border-b border-divider">
+      <SidebarTrigger />
+      <h1 className="text-body-lg font-medium flex-1 truncate">{title}</h1>
+      {rightSlot}
+    </header>
+  )
+}
+
+function DashboardPage() {
+  return (
+    <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] space-y-6">
+      <section>
+        <h2 className="text-h5 mb-2">Today</h2>
+        <p className="text-body text-fg-secondary">
+          替換為真實業務 — 訂單 / 收入 / 待處理任務等 dashboard widgets。Consume DS components
+          (DataTable / Chart / Card / Stat 等),never modify DS source。
+        </p>
+      </section>
+      <section className="grid grid-cols-3 gap-4">
+        {['Revenue', 'Active customers', 'Pending orders'].map((label) => (
+          <div key={label} className="rounded-lg border border-divider bg-surface p-4">
+            <div className="text-caption text-fg-secondary">{label}</div>
+            <div className="text-h3 mt-1">—</div>
+          </div>
+        ))}
+      </section>
+    </div>
+  )
+}
+
+export default function App() {
+  const [activeId, setActiveId] = useState<string>('dashboard')
+  const current = NAV.find((n) => n.id === activeId) ?? NAV[0]
+  // TooltipProvider self-wrap(Storybook story render 跳過 main.tsx → App 必自帶 TooltipProvider context)
+  return (
+    <TooltipProvider delayDuration={500} skipDelayDuration={300}>
+      <SidebarProvider activeId={activeId} onActiveChange={setActiveId}>
+        <AppShell
+          layout="primary-sidebar"
+          sidebar={<AppSidebar />}
+          header={
+            <PageHeader
+              title={current.label}
+              rightSlot={<Button variant="primary" size="md">New customer</Button>}
+            />
+          }
+        >
+          <DashboardPage />
+        </AppShell>
+      </SidebarProvider>
+    </TooltipProvider>
+  )
+}