前端项目规范
本页定义 AgileLabs Framework 项目中新建 Web 前端、管理后台和 ClientApp 前端入口的默认技术栈、主题模式与项目级依赖源约定。接口字段、返回包和时间格式规则，请继续阅读 前端对接规范；前端在 Drone 中的默认构建口径，请继续阅读 CI/CD 规范。
适用场景
- 新建 Web 前端、管理后台或与后端一起发布的
ClientApp项目。 - 需要为 AI Agent 和人工开发者提供统一默认脚手架约定的项目。
- 需要长期维持一致样式栈、图标体系和主题模式的团队。
必须遵守
- 新前端项目默认使用
tailwindcss v4作为样式层基础。 - 新前端项目默认使用
Font Awesome Free v6作为图标库。 - 新前端项目必须同时支持
light与dark两种主题模式，不允许只做单主题。 - 首屏默认按
prefers-color-scheme选择主题，同时必须提供手动切换入口，并持久化用户偏好。 - 前端项目级包源默认使用
https://npm.feinian.net，不依赖开发者本机私有的全局 registry 配置。 - 与该前端项目配套的后端包源默认使用
https://nuget.feinian.net；若工具需要 NuGet v3 源地址，则使用https://nuget.feinian.net/v3/index.json。 - 新模块不允许把多套样式体系、多套默认图标库或互相冲突的主题机制同时作为长期默认方案。
- 新前端项目必须基于共享设计令牌或主题变量组织颜色、字号、间距、圆角、阴影等视觉语义，不把这些规则散落在页面局部硬编码中。
- 页面与组件必须优先复用统一的排版、间距、按钮、表单、卡片和状态表达方式，不把“每页各写一套视觉规则”当成默认做法。
- 双主题不仅是切换
class，还必须让共享设计令牌同时覆盖light/dark两套视觉语义。
推荐做法
- 在项目级配置文件中显式声明包源，而不是只靠个人机器的全局设置。
- 用一套共享主题变量或设计令牌承接
light/dark颜色语义，再由tailwindcss v4负责页面和组件落地。 - 让设计令牌同时覆盖颜色、字号、间距、圆角、阴影和状态色，而不是只抽一层主题色后其余样式继续各页散写。
- 把按钮、表单、卡片、列表、空状态和反馈状态整理成统一的设计基线，优先复用，而不是页面独立发明视觉规则。
- 在应用启动早期读取主题偏好，避免首屏闪烁或先亮后暗的错帧。
- 将图标使用收敛到统一封装层或清晰导入约定，避免页面里随意混用多套图标来源。
- 对存量前端项目保留兼容时，显式写出偏差范围和迁移计划，不把旧方案继续扩散到新页面。
运作机制
- 本页负责前端项目默认技术栈、主题模式和依赖源约定，前端对接规范 负责 JSON 字段、返回包和时间格式，两者不要混写成一页。
tailwindcss v4提供统一样式基础，Font Awesome Free v6提供统一图标来源，目的是让组件、页面和 AI Agent 生成结果都建立在同一默认前提下。- 设计令牌负责沉淀颜色、字号、间距、圆角、阴影和状态语义，页面与组件负责基于这些令牌落地，不让视觉规则退化成零散硬编码。
- 主题解析顺序固定为：用户手动选择优先，其次是已持久化偏好，最后才是系统
prefers-color-scheme。 - 包源约定应落在项目级配置、脚手架或交付文档中，不能只存在于口头说明或某位开发者的本机环境里。
常见问题
- “现有前端项目已经在用其他样式栈，必须一次性切掉吗？” 不要求一次性重写，但必须把它标记为存量兼容方案，不再作为新项目默认值。
- “能不能局部页面临时用别的图标库？” 不建议把局部例外演变成第二套默认体系。确有需要时，应限定范围并在封装层隔离。
- “已经有 Tailwind 了，还需要强调设计规范吗？”
需要。
tailwindcss v4解决的是样式表达与落地效率，设计规范解决的是视觉语义统一、组件复用边界和双主题一致性，这两层不能互相替代。 - “为什么文档里写的是
https://nuget.feinian.net，命令行示例却可能带/v3/index.json？” 前者是项目级包仓库地址，后者是 NuGet 工具常用的 v3 源入口，语义一致，不算两套默认源。
相关检查
示例项目对照
- gmandarin-backend：适合对照多前端入口和站点托管方式。
- 托管前端：适合结合本页规则快速落地前端入口。
- 前端对接规范：适合同时核对接口契约与前端项目默认值的边界。
- CI/CD 规范：适合继续核对
pnpm、锁文件和前端构建步骤边界。