react-vite-dashboard

Stitch 到 React + Vite 仪表板

你是一名前端工程师，负责根据 Stitch 屏幕构建数据密集型仪表板。目标技术栈：React 18、Vite、TypeScript、TanStack Query、React Router，以及用于链上读取的可选 ethers v6 或 viem。

先决条件

• 已配置 Stitch MCP（设置指南）
• 项目 DESIGN.md（请参阅 design-md 技能），以确保设计令牌的精确还原
• Vite + React + TypeScript 脚手架（npm create vite@latest）

工作流

1. 发现 MCP 前缀 — 运行 list_tools，记录 Stitch 前缀（例如 stitch:）。
2. 获取屏幕 — 使用项目 ID 和屏幕 ID 调用 [prefix]:get_screen。
3. 下载资源 — 将 HTML/截图保存到 .stitch/designs/{screen}.html 和 .png。
4. 读取 DESIGN.md — 将 colors.*、typography.*、spacing.* 映射为 src/index.css 中的 CSS 变量。
5. 生成组件 — 拆分到 src/components/、src/pages/、src/hooks/。
6. 接入数据 — 使用 TanStack Query 进行异步获取；保持展示组件纯粹。

HTML → React 映射

模式	实现方式
布局网格 / flex	使用与 DESIGN.md 间距令牌一致的 Tailwind 工具类或 CSS 模块
卡片 / 面板	使用 <section>，并采用令牌化的圆角；在强制颜色模式下提供阴影回退样式
表格	使用语义化的 <table> 或 TanStack Table；表格数据绝不能只用 div 网格呈现
按钮	使用带有可见焦点环的 <button type="button">（除非 DESIGN.md 定义了焦点令牌，否则保留浏览器默认样式）
表单	使用 <label htmlFor> + <input id>；通过 aria-describedby 关联错误信息
加载状态	使用骨架屏组件；获取数据期间在容器上设置 aria-busy
钱包连接	在 WalletProvider 中隔离；生成的代码中绝不能嵌入私钥

DESIGN.md 集成

/* src/index.css — example token bridge */
:root {
  --color-primary: /* from DESIGN.md colors.primary */;
  --font-body: /* typography.body-md.fontFamily */;
}

发布 UI 前，请在本地运行 design.md 检查器：

npx @google/design.md lint DESIGN.md

Web3 仪表板约定

• 通过 useReadContract（viem/wagmi）或 ethers Contract + TanStack Query queryFn 进行只读合约调用。
• 使用 formatUnits 格式化代币数量；在设置页脚中显示网络名称和链 ID。
• 用通俗易懂的语言呈现交易错误；若存在 txHash，则链接到区块浏览器。
• 对 Gas 敏感的流程：批量读取，避免在渲染循环中重复执行 eth_call。

文件结构

src/
├── components/     # Presentational UI from Stitch
├── pages/          # Route-level screens
├── hooks/          # useQuery wrappers, wallet hooks
├── lib/            # ABI helpers, formatters
└── styles/         # Token CSS variables

质量检查清单

• WCAG 2.2 AA：DESIGN.md 中定义的组件配对对比度通过检查器验证
• 支持键盘导航：焦点顺序与视觉顺序一致
• 响应式：在 375px 和 1280px 宽度下测试
• 仓库中没有密钥：RPC URL 从环境变量读取（VITE_* 前缀仅用于公共端点）
• TypeScript 严格模式：合约 ABI 中不使用 any

Stitch 文档说明

打开 stitch.withgoogle.com/docs 上的链接时，如果相对路径导航错误地发生重定向，请使用完整的 https://stitch.withgoogle.com/docs/... URL。