页面开发

这套流程面向熟悉 C#/.NET、但不熟悉 React/TypeScript 的开发者。页面开发的目标是“填写业务契约”，不是重新设计颜色、布局和状态。

概念映射

C#/.NET 概念	前端对应	规则
Typed API Client	`@bitz/platform-sdk`	不手写 DTO，不在页面直接 `fetch`
Application Query	Query hook / loader	编排读模型和页面状态
Command	mutation hook	使用统一成功、错误和失效策略
Authorization Policy	PermissionGate / FeatureGate	只优化 UX，后端仍是事实源
Razor Component 参数	React props	保持显式、只读
Result / ProblemDetails	SDK error model	不解析私有错误字符串
Integration Test	Playwright user flow	覆盖真实交互和状态转换

六步开发

继承 Profile：产品决定 Theme、Mode、Density、Shell 和 Workspace，页面不改。
选 Recipe：List、Detail、Edit、Wizard、Dashboard 或 Identity。
选契约：找到 generated SDK Query/Command 和服务器权限码。
填内容：声明列、字段、验证、文案与业务操作。
补状态：实现 Loading、Empty、Error、Unauthorized、Disabled 等适用状态。
过门禁：lint、typecheck、测试、build、代表视觉矩阵和 Design Guardian。

Recipe

Recipe	固定组成
List	PageHeader + QueryToolbar + AppliedSummary + DataToolbar + ServerDataTable + Pagination
Detail	PageHeader + Summary + LocalTabs + ActivityTimeline
Edit	FormSection + FieldGroup + ValidationSummary + ActionBar
Wizard	Stepper + StepPanel + SaveDraft + Review
Dashboard	QueryToolbar + MetricStrip + WorkQueue + DenseTable
Identity	IdentityShell + FormState + Recovery/Verification Action + Security Context

业务开发者负责 SDK、权限、字段、列、文案和操作。Design System 负责颜色、阴影、行高、断点、焦点、错误和加载骨架。

目录与依赖

页面进入 apps/app 的对应 feature/route。
基础组件从 @bitz/components 导入。
复合 Pattern/Recipe 从 @bitz/widgets 或后续专用包导入。
后端调用只经 @bitz/platform-sdk 单一 request pipeline。
Token 由 @bitz/materials 生成并注入；页面不直接导入 Source。

不要深入 package 私有路径，不要复制组件源码到页面。

页面红线

不写品牌 Hex/OKLCH、任意渐变、彩色阴影或页面私有主题。
不手写后端 DTO、散落 fetch 或本地 HTTP adapter。
不把 TenantId、Role、Permission 或 refresh token 写入 localStorage。
不用前端隐藏替代服务器 Authorization。
不为当前页另造 Shell、Tab、筛选器或数据表格。
不只实现成功状态。

导航与 Tabs

先判断它属于哪一层，再选择组件：

跨业务域是一级模块导航，由 Shell 从服务端菜单生成；
同一业务域内切页面是当前模块导航，Side 放在二级面板，Top 放在 Secondary bar；
同时打开多个 URL/资源才是 Managed Workspace Tabs；
当前页面内部内容分区才使用 WorkspaceLocalTabs。

业务页面不得把 Shell 已显示的模块入口再复制到 WorkspaceHeader。Local Tabs 保持一排并映射 URL 或稳定状态；它们的吸附、横向溢出、选中态和键盘语义由 widget 负责，页面只提供任务名和内容。

提交前

当前可运行：

# 从 frontend/ 根目录运行当前真实存在的门禁。
cd frontend
yarn install --immutable
yarn lint
yarn typecheck
yarn build

受影响 package 还要运行其 Vitest；涉及布局、主题、密度、窄屏或可访问性时运行 yarn workspace @bitz/app test:visual（首次运行先执行 test:visual:install）。独立 Design Lab 与统一 ui:check 仍是后续能力，不得假装已经可用。

UI 切片的评审结论应包含：

Design Guardian: pass | changes-required
Contract: Theme / Mode / Density / Shell / Workspace / Recipe
States verified: default, hover, active, focus-visible, disabled, loading, and applicable data states
Accessibility verified: contrast, keyboard, text zoom, narrow viewport, and reduced-motion
Exceptions: none | ADR/ledger reference
Visual baseline: unchanged | intentional update reference

完整规则见 Design System 1.2 和实现与符合性门禁。