web-rules

React 19 + Next.js 16 + Tailwind CSS 最佳实践

针对使用 React 19、Next.js 16 App Router 和 Tailwind CSS 4 构建的 Web 应用的全面严格规则参考。包含 6 个类别中的 34 条规则。每条规则都以「始终／绝不」指令的形式陈述，并附有量化影响、错误示例和正确示例。

技术栈约定

所有指南均基于以下假设：

• React 19 默认使用 Server Components；仅在需要交互时使用 Client Components（在顶部添加 'use client'）
• Next.js 16 App Router，使用 app/ 目录、layout.tsx、page.tsx、loading.tsx、error.tsx、not-found.tsx、并行路由和拦截路由
• Server Actions 用于数据变更（'use server'）——绝不使用 useEffect 获取数据
• Tailwind CSS 4，使用 @theme 指令、dark: 变体、容器查询和标准 4pt 间距刻度
• lucide-react 作为标准图标系统
• 不使用 CSS-in-JS（不使用 styled-components 或 emotion）——仅使用 Tailwind 工具类；条件类使用 clsx + tailwind-merge 提供的 cn()
• 弹窗、浮层、下拉菜单、工具提示和 Toast 优先使用 shadcn/ui 基础组件（基于 Radix）

适用场景

遇到以下情况时，请参考这些规则：

• 构建任何面向用户的路由、布局或组件
• 审查 PR 中的设计／用户体验／无障碍回退问题
• 选择呈现方式（对话框、浮层或全页面）
• 使用 Server Actions 和 useFormState / useOptimistic 实现表单
• 配置加载和错误边界
• 设计引导、权限或设置流程
• 确保深色模式、焦点管理和键盘导航端到端正常工作

按优先级排列的规则类别

优先级	类别	影响	前缀
1	导航	CRITICAL	nav-
2	交互设计	CRITICAL	inter-
3	无障碍	CRITICAL	acc-
4	用户反馈	HIGH	feed-
5	用户体验模式	HIGH	ux-
6	视觉设计	HIGH	vis-

快速参考

1. 导航（CRITICAL）

• nav-primary - 使用顶部导航（3–7 个分区）或侧边栏；桌面端绝不只使用汉堡菜单
• nav-app-router - 使用 App Router 布局、并行路由，并通过 <Link> 实现所有内部导航
• nav-page-actions - 将主要操作放在页面标题区域；绝不把它们藏在滚动区域中

2. 交互设计（CRITICAL）

• inter-touch-targets - 触摸目标最小为 44×44 px（WCAG 2.5.5）
• inter-pointer-patterns - 使用标准的悬停／点击／长按模式；绝不自创模式
• inter-microinteractions - 始终在 100ms 内通过视觉反馈确认交互
• inter-keyboard-navigation - 每个交互元素都必须可通过键盘访问和操作
• inter-drag-drop - 提供拖拽操作时，始终提供可通过键盘访问的替代方式
• inter-revalidation - 数据变更后使用 revalidatePath/revalidateTag；绝不依赖客户端刷新
• inter-row-actions - 每个列表只使用一种「行操作」模式（更多菜单、悬停操作或滑动）
• inter-search - 将搜索输入的防抖时间设为 200–300ms，并在 URL 中体现查询条件

3. 无障碍（严重）

• acc-labels - 每个交互元素都有可访问名称
• acc-text-scaling - 浏览器缩放至 200% 时，所有文本都能缩放，且不会出现水平滚动
• acc-color-contrast - WCAG AA：正文文本对比度为 4.5:1，大号文本和 UI 为 3:1
• acc-reduce-motion - 遵循 prefers-reduced-motion: reduce
• acc-color-independent - 绝不单独依靠颜色传达含义
• acc-focus-management - 始终显示可见的焦点环；将焦点限制在模态框内
• acc-relative-units - 文本和间距使用 rem；绝不使用 px 固定文本大小
• acc-responsive-layout - 每种布局在 320 px 宽度下都能正常显示，且不会出现水平滚动

4. 用户反馈（高）

• feed-loading-states - 始终使用 loading.tsx 或 <Suspense>，并配备与最终布局一致的骨架屏
• feed-error-states - 每个路由段都要有带“重试”操作的 error.tsx
• feed-toasts - 仅使用 toast 确认不会阻塞的操作
• feed-success-confirmation - 每项破坏性或不可逆操作都要提供明确、可见的反馈予以确认
• feed-empty-states - 空状态要说明原因并提供后续操作

5. UX 模式（高）

• ux-onboarding - 引导流程不超过 3 个屏幕，且始终可以跳过
• ux-permissions - 在相关操作中请求浏览器权限，而不是在页面加载时请求
• ux-modality - 根据内容的重要程度选择对话框 / 弹出层 / 全页形式；绝不叠加模态框
• ux-destructive-confirmation - 破坏性操作需要用户输入文字确认，或提供撤销时限
• ux-data-entry - 使用 Server Actions + 渐进增强；输入时绝不禁用提交操作
• ux-undo - 日常操作优先提供撤销，而不是确认
• ux-settings - 设置变更后自动保存；绝不要求点击“保存”按钮

6. 视觉设计（高）

• vis-dark-mode - 使用 CSS 自定义属性 + dark: 变体；绝不硬编码 text-black/bg-white
• vis-icon-system - 使用 lucide-react，描边宽度为 1.5px，标准尺寸为 size-4/size-5
• vis-spacing - 使用 Tailwind 4 pt 间距刻度和容器查询；绝不使用临时的 px 外边距

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响等级
• 规则模板 - 添加新规则时使用的模板

参考文件

文件	说明
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板