spark-app-template

Spark App Template

用途

Spark App Template 为构建 Web 应用提供默认配置和指导。当用户要求构建 Web 应用时，此技能会提供技术基础和设计方向，帮助创建功能完善的应用。

何时使用此技能

当用户：

• 想从零开始构建新的 Web 应用
• 询问“我应该使用什么技术栈？”
• 需要有关设计、样式或技术选择的指导
• 想要开始制作仪表板、交互式工具、数据应用或内容网站
• 请求帮助在框架、库或实现方式之间做出选择

请启用 Spark App Template。

快速入门工作流

重要：请严格按照以下顺序操作，以避免配置错误：

1. 创建项目：pnpm create vite@latest my-app --template react-ts
2. 安装基础依赖项：pnpm install
3. 配置 TypeScript 路径别名（tsconfig.json 和 tsconfig.app.json——参见下方步骤 1）
4. 安装 Tailwind 和工具：pnpm add -D tailwindcss @tailwindcss/vite @biomejs/biome
5. 配置 vite.config.ts：添加 Tailwind 插件和路径别名
6. 初始化 shadcn：pnpm dlx shadcn@latest init（正确配置别名后即可成功）
7. 安装所需的 shadcn 组件：pnpm dlx shadcn add button card avatar ...（编写组件之前）
8. 安装其他软件包：TanStack Router、Query、Zustand 等
9. 编写自定义组件（现在可以安全地从 @/components/ui/* 导入）
10. 配置路由和状态管理
11. 实现功能

步骤 3、6 和 7 必须严格按照此顺序执行，以避免 TypeScript 错误和 shadcn 安装失败。

复杂度级别

了解复杂度有助于选择合适的技术栈变体和设计方案：

1. 微型工具（单一用途）

   • 示例：计算器、转换器、颜色选择器、计时器
   • 技术栈：stacks/default-webapp.md
   • 重点：简单、聚焦的 UI，尽量减少状态

2. 内容展示（以信息为主）

   • 示例：着陆页、作品集、博客、文档
   • 技术栈：stacks/content-showcase.md
   • 重点：排版、阅读体验、视觉层次

3. 轻量应用（包含多个功能和基本状态）

   • 示例：待办事项列表、膳食规划工具、费用跟踪器
   • 技术栈：stacks/default-webapp.md
   • 重点：功能清晰、数据持久化、用户流程

4. 复杂应用（高级功能，包含多个视图）

   • 示例：CRM、分析仪表板、项目管理工具
   • 技术栈：stacks/complex-application.md 或 stacks/data-dashboard.md
   • 重点：导航、状态管理、性能优化

核心技术栈（共享基础）

所有 Spark App Template 应用都使用以下基础配置：

构建与开发

• 构建工具：Vite（最新稳定版）
• 框架：React 19+（利用新的编译器、钩子和功能）
• 语言：TypeScript
• 包管理器：pnpm
• 代码检查：Biome（复杂插件的备用方案为 ESLint）

路由与数据

• 路由：TanStack Router（基于文件、类型安全）
• 数据获取：TanStack Query
• 表单：react-hook-form + Zod 验证

样式与 UI

• 样式：Tailwind CSS v4+（现代 @import 语法）
• 组件：shadcn/ui（New York 风格，45+ 个组件）
• 图标：Lucide React（1000+ 个图标）
• 颜色系统：Radix Colors（OKLCH 格式）
• 主题：next-themes（默认单一主题，可选深色模式）

实用工具与增强功能

• 动画：Motion（原名 framer-motion）
• 通知：Sonner
• 实用工具：CVA（或 Tailwind Variants）+ clsx + tailwind-merge
• 错误处理：react-error-boundary

技术栈变体

所有变体都共享上述核心基础。这些模板会添加特定的软件包和设计指导：

默认 Web 应用（stacks/default-webapp.md）

• 适用场景：大多数应用、通用工具
• 附加软件包：无
• 设计重点：简洁、现代、实用

数据仪表板（stacks/data-dashboard.md）

• 适用场景：分析、管理面板、数据可视化
• 附加包：Recharts（图表）、date-fns（日期处理）
• 设计重点：数据密度、信息层级、浏览模式

内容展示（stacks/content-showcase.md）

• 适用场景：营销网站、作品集、博客、文档
• 附加包：marked（Markdown 解析）
• 设计重点：字体排印层级、阅读体验、留白

复杂应用（stacks/complex-application.md）

• 适用场景：多视图应用、SaaS 平台、企业工具
• 附加包：Zustand（状态管理）、date-fns
• 设计重点：导航模式、状态架构、性能

React 19+ 功能

启用以下现代 React 功能：

React Compiler

• 状态：React 19+ 中可用
• 优势：自动记忆化，显著加快初始加载和交互速度
• 设置：兼容 React 17+，通过 compiler config 配置

useActionState Hook

• 适用场景：表单处理、异步操作、加载状态
• 优势：简化状态管理，内置异步处理
• 模式：整合表单状态、待处理状态和错误处理

useOptimistic Hook

• 适用场景：在服务器确认前即时更新 UI
• 优势：提升感知性能，改善用户体验
• 模式：乐观更新，失败时自动回滚

Server Components

• 状态：React 19+ 中稳定（仅限框架模式）
• 框架：Next.js、TanStack Start
• 注意：对于 Vite + React SPA 应用，请使用客户端渲染

项目结构模板

my-app/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── biome.json
├── src/
│   ├── main.tsx              # App entry point
│   ├── App.tsx               # Root component
│   ├── index.css             # Global styles + theme
│   ├── components/
│   │   ├── ui/               # shadcn components (don't edit)
│   │   └── ...               # Custom components
│   ├── hooks/
│   │   └── use-mobile.tsx
│   ├── lib/
│   │   ├── utils.ts          # cn() utility
│   │   └── data.ts           # Data schemas (if needed)
│   └── routes/               # TanStack Router routes
│       └── __root.tsx
└── public/                   # Static assets

设计理念

优秀的 Web 应用不止于实现功能，更能唤起情感并创造令人难忘的体验。请遵循以下原则：

核心原则

1. 化繁为简：不断删减，直至得到最简单且有效的方案
2. 忠于材质：数字材质具有独特属性，应善加运用
3. 极致细节：卓越源于数百个经过深思熟虑的决策
4. 统一的设计语言：每个元素都应让人感觉属于一个统一系统
5. 鲜明的视觉形象：打造令人难忘的美学，而非千篇一律的模式

关键要求

• 使用 OKLCH 色彩格式（2026 年强制要求）
• 避免使用过度常见的字体：Inter、Roboto、Arial、Space Grotesk
• 选择有特色的字体排印：参见 references/typography-pairings.md
• 验证色彩对比度：WCAG AA（普通文本 4.5:1，大号文本 3:1）
• 默认使用单一主题：除非明确要求，否则不要启用暗色模式
• 可变字体：使用单个可变字体文件以提升性能

详尽的设计指南请参见 references/design-system.md。

性能目标（Core Web Vitals）

针对以下指标进行优化：

• INP（交互到下一次绘制）：< 200ms
• LCP（最大内容绘制）：< 2.5s
• CLS（累积布局偏移）：< 0.1

实现目标的工具：

• 使用 React Compiler 自动记忆化
• 使用 Vite 进行代码拆分和延迟加载
• 图像优化（WebP、AVIF、延迟加载）
• 字体优化（可变字体、font-display: swap）

详细的优化策略请参见 references/performance-checklist.md。

参考资料

在 references/ 目录中查阅详细指南：

1. design-system.md - 全面的设计理念、空间构图、背景和微交互
2. typography-pairings.md - 富有特色的字体组合及风格指南
3. color-palettes.md - 经过预先整理并通过 WCAG 验证的 OKLCH 调色板
4. component-patterns.md - 常见的 shadcn 组合方式和使用模式
5. performance-checklist.md - Web Vitals 优化、React Compiler 设置
6. prd-template.md - 用于新应用的简化规划框架
7. radix-migration-guide.md - 针对 Radix 问题的 Base UI 迁移路径

实施工作流

步骤 1：初始化项目

重要：运行 shadcn init 之前，先配置路径别名，以避免验证错误。

# Create Vite project
pnpm create vite@latest my-app --template react-ts
# Note: Working directory is now my-app/ - no need to cd

# Install dependencies
pnpm install

# Add Tailwind CSS and tooling
pnpm add -D tailwindcss@latest @tailwindcss/vite
pnpm add -D @biomejs/biome
pnpm add -D @tanstack/router-plugin

配置 TypeScript 路径别名（shadcn 必需）：

更新 tsconfig.json*：

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

更新 tsconfig.app.json*：

{
  "compilerOptions": {
    // ... existing options ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

更新 vite.config.ts*：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
import path from 'path'

export default defineConfig({
  plugins: [
    TanStackRouterVite(),
    react(),
    tailwindcss(),
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

* 配置示例基于 Vite + React + TypeScript 模板结构

现在运行 shadcn init 即可成功：

# Initialize shadcn (path aliases now configured)
pnpm dlx shadcn@latest init

# CRITICAL: Install shadcn components BEFORE writing custom components
# Identify which components you need first
pnpm dlx shadcn@latest add button card input form dialog avatar badge separator

# Add TanStack packages
pnpm add @tanstack/react-router @tanstack/react-query

# Add utilities
pnpm add lucide-react motion sonner react-hook-form zod @hookform/resolvers
pnpm add clsx tailwind-merge class-variance-authority
pnpm add react-error-boundary next-themes

步骤 2：配置项目

具体配置示例请参阅 stacks/ 中的技术栈模板。

步骤 3：创建 PRD（可选，但推荐）

使用 references/prd-template.md 进行规划：

• 目的和使命
• 复杂度
• 核心功能
• 设计方向
• 颜色和字体选择

步骤 4：先安装 shadcn 组件

重要：组件安装顺序

务必先安装 shadcn 组件，再编写导入这些组件的自定义组件。这样可以避免 TypeScript 错误和构建失败。

❌ 错误顺序（会导致错误）：

# 1. Write PersonDetail.tsx that imports '@/components/ui/card'
# 2. Run pnpm dlx shadcn add card
# 3. Fix TypeScript errors 'Cannot find module @/components/ui/card'

✅ 正确顺序：

# 1. Plan which shadcn components you need
#    Example: Card, Avatar, Badge, Separator, Button

# 2. Install ALL required shadcn components FIRST
pnpm dlx shadcn@latest add card avatar badge separator button

# 3. Verify installation
ls src/components/ui/  # Should show: card.tsx, avatar.tsx, badge.tsx, etc.

# 4. NOW write PersonDetail.tsx that imports from '@/components/ui/*'
#    TypeScript will have proper types and components will exist

规划清单：

1. 列出应用所需的所有 UI 组件
2. 确认哪些是 shadcn 组件（Card、Button 等）
3. 运行一条包含所有组件的 shadcn add 命令
4. 确认这些组件存在于 src/components/ui/
5. 编写导入这些组件的自定义组件

步骤 5：遵循最佳实践进行实现

• 遵循 shadcn 组件模式
• 在 :root CSS 变量中使用 OKLCH 颜色
• 实现响应式设计（移动端优先）
• 添加错误边界
• 优化图像和字体
• 测试 Core Web Vitals

常见模式

主题配置（index.css）

@import 'tailwindcss';

:root {
  /* OKLCH colors - mandatory format */
  --background: oklch(0.97 0.01 75);
  --foreground: oklch(0.25 0.02 55);
  --primary: oklch(0.52 0.14 155);
  --accent: oklch(0.72 0.13 55);

  /* Add more theme variables */
  --radius: 0.75rem;
}

@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-accent: var(--accent);

  /* Radius system */
  --radius-sm: calc(var(--radius) * 0.5);
  --radius-md: var(--radius);
  --radius-lg: calc(var(--radius) * 1.5);
}

注意：此处使用 Tailwind CSS v4+ 的 @import 语法。对于 v3，请改用 @tailwind 指令。

表单处理

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
});

function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: '', password: '' }
  });

  async function onSubmit(data: z.infer<typeof schema>) {
    // Handle form submission
  }

  return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;
}

数据获取

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

function UserList() {
  const queryClient = useQueryClient();

  const { data, isLoading } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers
  });

  const createUser = useMutation({
    mutationFn: createUserAPI,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    }
  });

  if (isLoading) return <LoadingSpinner />;
  return <UserGrid users={data} onCreate={createUser.mutate} />;
}

故障排除

Radix UI 的维护问题

Radix UI 的更新频率有所降低。对于新项目或迁移问题：

• 请参阅 references/radix-migration-guide.md，了解迁移到 Base UI 的路径
• shadcn/ui 现已支持将 Base UI 作为替代方案
• React Aria 也是一个出色的选择（由 Adobe 支持，具备更出色的无障碍功能）

性能问题

如果应用运行缓慢：

1. 启用 React Compiler，以自动进行记忆化
2. 在 Chrome DevTools 中检查 Core Web Vitals
3. 使用 references/performance-checklist.md
4. 考虑使用 TanStack Router 的延迟加载进行代码拆分

构建工具替代方案

稳定后，使用 Rolldown 打包器的较新版本 Vite 可能会加快构建速度。请关注稳定版发布。

系统要求

• Node.js：18+（或当前 LTS 版本）
• 包管理器：推荐使用 pnpm，以获得更好的性能
• 操作系统：macOS、Linux，或搭配 WSL2 的 Windows

后续步骤

完成脚手架搭建后：

1. 根据项目复杂度查看相应的技术栈模板
2. 参考设计指南进行样式设计
3. 创建 PRD，规划功能和设计
4. 遵循最佳实践进行实现
5. 针对 Core Web Vitals 进行优化
6. 部署到生产环境（Vercel、Netlify 等）

---

请记住：目标是构建功能完善且性能出色的 Web 应用。从简单开始，根据用户需求不断迭代，并优先考虑用户体验，而非技术复杂度。