agilelabs-fx-docs main framework-standards/frontend-project.md

前端项目规范

本页定义 AgileLabs Framework 项目中新建 Web 前端、管理后台和 ClientApp 前端入口的默认技术栈、主题模式与项目级依赖源约定。接口字段、返回包和时间格式规则，请继续阅读 前端对接规范。

适用场景

  • 新建 Web 前端、管理后台或与后端一起发布的 ClientApp 项目。
  • 需要为 AI Agent 和人工开发者提供统一默认脚手架约定的项目。
  • 需要长期维持一致样式栈、图标体系和主题模式的团队。

必须遵守

  • 新前端项目默认使用 tailwindcss v4 作为样式层基础。
  • 新前端项目默认使用 Font Awesome Free v7 作为图标库。
  • 新前端项目必须同时支持 light 与 dark 两种主题模式，不允许只做单主题。
  • 首屏默认按 prefers-color-scheme 选择主题，同时必须提供手动切换入口，并持久化用户偏好。
  • 前端项目级包源默认使用 https://npm.feinian.net，不依赖开发者本机私有的全局 registry 配置。
  • 与该前端项目配套的后端包源默认使用 https://nuget.feinian.net；若工具需要 NuGet v3 源地址，则使用 https://nuget.feinian.net/v3/index.json。
  • 新模块不允许把多套样式体系、多套默认图标库或互相冲突的主题机制同时作为长期默认方案。

推荐做法

  • 在项目级配置文件中显式声明包源，而不是只靠个人机器的全局设置。
  • 用一套共享主题变量或设计令牌承接 light / dark 颜色语义，再由 tailwindcss v4 负责页面和组件落地。
  • 在应用启动早期读取主题偏好，避免首屏闪烁或先亮后暗的错帧。
  • 将图标使用收敛到统一封装层或清晰导入约定，避免页面里随意混用多套图标来源。
  • 对存量前端项目保留兼容时，显式写出偏差范围和迁移计划，不把旧方案继续扩散到新页面。

运作机制

  • 本页负责前端项目默认技术栈、主题模式和依赖源约定，前端对接规范 负责 JSON 字段、返回包和时间格式，两者不要混写成一页。
  • tailwindcss v4 提供统一样式基础，Font Awesome Free v7 提供统一图标来源，目的是让组件、页面和 AI Agent 生成结果都建立在同一默认前提下。
  • 主题解析顺序固定为：用户手动选择优先，其次是已持久化偏好，最后才是系统 prefers-color-scheme。
  • 包源约定应落在项目级配置、脚手架或交付文档中，不能只存在于口头说明或某位开发者的本机环境里。

常见问题

  • “现有前端项目已经在用其他样式栈，必须一次性切掉吗？” 不要求一次性重写，但必须把它标记为存量兼容方案，不再作为新项目默认值。
  • “能不能局部页面临时用别的图标库？” 不建议把局部例外演变成第二套默认体系。确有需要时，应限定范围并在封装层隔离。
  • “为什么文档里写的是 https://nuget.feinian.net，命令行示例却可能带 /v3/index.json？” 前者是项目级包仓库地址，后者是 NuGet 工具常用的 v3 源入口，语义一致，不算两套默认源。

相关检查

示例项目对照