feat(tasks-ui): migrate the Tasks page to shadcn/ui (Tailwind v4 + radix, lazy chunk)
Visual base replacement for the Tasks page after the 'hard shadows make a dense graph unreadable' review. Behaviour, hooks, aria labels and i18n are unchanged; the base layer is not. - FOUNDATION: Tailwind v4 wired into tsdown's css-inline plugin (theme + utilities ONLY — preflight is excluded because the plugin's stylesheet is a global <style data-plugin> tag and would repaint the host page), shadcn tokens bridged to --dsw-* so the DSH theme keeps flipping light/dark with no dark: overrides, cn() util, components.json for the CLI, src/client/ui/. - COMPONENTS: shadcn's component source vendored into src/client/ui (button, card, badge, separator, input, textarea, tooltip, popover, dropdown-menu, scroll-area, collapsible, toggle-group, skeleton, spinner, empty) with a documented local diff: lucide-react replaced by host IconXxx (no new icon dep), shadow-* dropped from non-floating variants, unused variants pruned, and React.forwardRef restored on Button — the host runs React 18, where radix's Slot cannot hand a ref to a plain function component (dev warns, production silently mis-anchors the floating layer). - SHADOWS: static panels are now hairline + surface tiers with hover:bg-muted; shadows exist only on floating layers. Settled nodes recede by ink (text-muted-foreground/foreground-3) instead of opacity. - DENSITY: node cards widened 132 -> 150px with a two-line clamped title (13px text in a 132px card left ~7 CJK characters), reserved height 46 -> 60. - CHUNK: the whole page (graph, tree, task window, board, drawer, shadcn/radix layer and its stylesheet) moved into the lazy 'tasks' chunk. Core bundle 988.5 -> 835.6 KiB (-153 KiB); the 709.8 KiB UI payload loads only when the Tasks tab opens. - MODEL: workflow members whose childId is already a real node elsewhere are no longer synthesized into a duplicate id (React keys/edges), with a last-resort per-id dedupe. - GUARDS: tests/ui-foundation.spec.ts, tests/ui-bundle.spec.ts (core/chunk split + size budget + no preflight/oklch/lucide), tests/ui-shadows.spec.ts, extended tests/theme.spec.ts (no colour literal / palette class in src/client/ui/** and the migrated files). - REVIEW FIXES: portal popovers re-scoped under .dsw-tasks, graph loading state, 11px floor, error nodes no longer tint a whole border, TeamBoard's delete item is neutral (the window owns the two-step confirm). Verified: typecheck / lint / 136 files 1502 tests / build bundle assertions / mount e2e 7-7; browser harness 65-65 checks with 0 console errors.
This commit is contained in:
Menghuan1918
@@ -1004,6 +1004,32 @@ interface SettingsDescriptor {
|
||||
- 类名是 CSS Modules 哈希，**不是契约**；精确命中用 `[data-dsh-better-sidebar]` + 子串类名（`[class*='panel']`）或 DOM 结构。
|
||||
- 改动本契约必须同步本文档、设计文档与 `tests/theme.spec.ts`。
|
||||
|
||||
### 12.3 在插件里用 Tailwind / shadcn/ui
|
||||
|
||||
本仓库自己的任务管理页（v0.20 起）就是这套姿势的参考实现：组件源码 vendoring 在 `src/client/ui/`，样式由 Tailwind v4 编译，颜色全部经 shadcn 语义令牌桥接到 `--dsw-*`。你的插件照做即可自动兼容全部皮肤；**接入的难点只有三条，其余都是常规 Tailwind**。
|
||||
|
||||
**① 只引 `theme` + `utilities`，绝不引 preflight。** 插件的 CSS 最终是全局 `<style data-plugin>`（没有 shadow DOM），`@import "tailwindcss"` 连带的 preflight 会重置**整张 DSH 宿主页面**（会话正文、原生右侧栏、设置页）。唯一合法的入口形状：
|
||||
|
||||
```css
|
||||
@import "tailwindcss/theme.css" layer(theme);
|
||||
@import "tailwindcss/utilities.css" layer(utilities);
|
||||
@source "../**/*.tsx"; /* 显式限定扫描面，否则 Tailwind 会连 lib/、node_modules/ 一起扫 */
|
||||
```
|
||||
|
||||
| 现象 | 原因 |
|
||||
|---|---|
|
||||
| 自己的 `.rounded-md` 被宿主样式压过 | 宿主样式表是**无层级（unlayered）**的，无层级声明优先于任何 `@layer` 内的声明（与特异性无关）。补偿方式是把重置放进层里并抬到**类特异性**、挂在页面自己的作用域根类上（本仓库是 `.dsw-tasks`：`color` / `:where(...)` 的 `box-sizing` 与 `font: inherit` / `focus-visible` 环），而不是去动宿主 |
|
||||
| 深浅主题下颜色不翻 | DSH 的主题翻转是给 `<body>` 打 `data-ds-dark-theme`，不是加 `.dark` 类。若确需 `dark:` 变体，先定义 `@custom-variant dark (&:where([data-ds-dark-theme], [data-ds-dark-theme] *))`——但**令牌本身就是翻转的**，绝大多数情况下写 `dark:` 是双重记账，不要写 |
|
||||
|
||||
**② 令牌桥接到 `--dsw-*`，颜色零字面量。** 在 `:root` 里把 shadcn 语义名接上 DSH 令牌（`--background: var(--dsw-alias-bg-base)`、`--card: var(--dsw-alias-bg-layer-1)`、`--popover: var(--dsw-alias-bg-layer-2)`、`--border: var(--dsw-alias-border-l4)`、`--primary: var(--dsw-alias-state-business-primary)`、`--muted-foreground: var(--dsw-alias-label-secondary)`、`--destructive: var(--dsw-alias-state-error-primary)` …），再用 `@theme inline { --color-background: var(--background); … }` 接成 Tailwind 工具类。`inline` 保证产物里留着这层间接，宿主皮肤改令牌能立刻生效。**禁止** `#hex` / `rgb()` / `oklch()` 字面量，也**禁止** Tailwind 默认调色板类（`bg-blue-500` / `text-white`）——后者的值是 Tailwind 自己的主题，不是 DSH 的。完整映射表见[任务页设计文档](./plans/2026-09-14-tasks-graph-workflow-teams-design.md)的「shadcn 令牌 → `--dsw-*` 映射表」。
|
||||
|
||||
**③ 静态面板零阴影。** 阴影是**层级**手段，不是装饰：卡片、节点、行、面板互相叠加的投影是「节点一多就辣眼睛」的直接原因。静态面板的层级改用 **1px hairline（`border-border`）+ 表面阶梯（`background` → `card`/layer-1 → `popover`/layer-2）+ 三档墨色**承载；`shadow-*` 只允许出现在真正浮动、由自己锚定几何定位的层（popover / dropdown-menu / tooltip / 可拖动窗口）。上游 shadcn 组件默认给 card / input / textarea / toggle / toggle-group 都带 `shadow-xs`/`shadow-sm`，vendoring 时要逐处删掉。
|
||||
|
||||
**另外两条与皮肤无关但同样会遇到**：
|
||||
|
||||
- **图标用宿主图标，不引 `lucide-react`**：`@deepseek-ai/dsh-client-ui-primitives` 的 `IconXxx` 是平台模块（`size` / `className` 两个 props，颜色靠 `currentColor`），宿主图标渲染的就是 `svg`，所以 shadcn 组件里的 `[&_svg]` / `[&_svg:not([class*='size-'])]:size-4` 选择器照旧成立。引 lucide 会把整套图标内联进你的 bundle。
|
||||
- **vendoring 而不是新增重依赖**：`npx shadcn add <component>` 把源码落进你自己的目录（本仓库 `components.json` 的 aliases 全部指向 `src/client/ui`），依赖只增加 `radix-ui` / `class-variance-authority` / `clsx` / `tailwind-merge` 这四个可 tree-shake 的包；`tailwindcss` 与 `@tailwindcss/postcss` 只进 devDependencies（运行期产物是编译后的 CSS）。落盘后**逐文件复核**：CLI 默认会写 `import { cn } from "cn"`（npm 上真有一个同名包）、带回 `dark:` 颜色覆写、带回被删的 `shadow-xs` / `text-white` 与未使用的变体。升级上游组件用 `npx shadcn@latest add <component> --diff`，只取结构性更新再重新施加自己的删改，**不要**用 `--overwrite`。
|
||||
|
||||
---
|
||||
|
||||
## 13. 完整最小示例
|
||||
|
||||
Reference in New Issue
Block a user