cogover-fe

Cogover Frontend Skill

强制流程

采用路由表 + 按需参考模式。此文件 = 索引。详细内容位于 reference/。

收到任务时：

1. 阅读此文件（已加载）→ 确定相关的 reference 文件
2. 使用 Read 工具从 {skill_base_dir}/reference/<name>.md 读取
3. 实现时应用相关规则。严格遵守 DO/DON'T
4. 提交/i18n → 阅读 {skill_base_dir}/reference/commit-convention.md 或 i18n-translation.md

绝对禁止（关键——最高优先级）：

• 在任何情况下都绝不使用已弃用的组件/hook/API（带有 @deprecated JSDoc、名称带有 Legacy/Old/V1 后缀，或在 @stringeecom/ui-kit / reference 文件中标注为 deprecated）。此规则不可违背——违反即立即拒绝 PR，没有例外。
• 使用 @stringeecom/ui-kit 中的任何组件前：检查 JSDoc @deprecated 和对应的 reference 文件。如果已弃用 → 使用 JSDoc/reference 中注明的替代方案。
• 看到旧代码使用已弃用的组件时 → 不要复制该模式，必须使用新版。
• 绝不在 react-hook-form 中使用 register() 或非受控输入。始终使用受控组件（@stringeecom/ui-kit 中的 Controlled*）。如果尚不存在 → 按 RULE-FORM-04 新建。详情：uikit-form-react-hook-form

规则：

• 仅阅读当前任务相关的 reference，不要全部阅读
• 复杂任务 → 并行发起多个 Read 调用
• 委派给 subagent → 将 reference 内容传入 prompt（subagent 无法读取 skill 文件）
• 导入组件/hook → 始终从 @stringeecom/ui-kit 导入
• 内部导入 → 当相对路径超过 2 层 ..（即 ../../../... 起）时，使用路径别名 src/foo/bar。允许使用 ./、../、../../ 层级的相对路径。详情：internal-import-path
• Link 和 useNavigate → 始终从 @stringeecom/ui-kit 导入（封装会自动附加 appSlug）。例外：StringeeUtilProvider 设置文件和 id、account 两个项目。详情：uikit-link-navigate
• 新增文本 → 先写越南语，按需进行 i18n 翻译
• Date/Time → 始终使用 dayjs
• 除非用户要求，否则不要自行创建 git commit
• 将独立任务拆分后 → 并行交由 sub agent 处理

样式基础（编写 UI 时必须遵守）：

• 颜色 → 使用已配置的 tokens（text-primary-main、bg-surface-default），不要使用原始 hex/rgb/Tailwind 默认值（bg-blue-500）
• 间距 → 使用 rem（p-[1rem]、gap-[0.5rem]），不要使用 px（p-[16px]）。换算：1rem = 16px
• 排版 → 使用 prose-* 类（prose-body2、prose-h2），不要使用 text-[14px] font-semibold
• className → 使用 cx()，并按关注点分组传参；不要使用字符串拼接/模板字面量
• Tokens → 先检查 tailwind.config.js，不要硬编码值

Reference 文件

基础与工作流

color-palette-usage · cx-class-grouping · spacing-rem-only · tokens-tailwind-config · typography-prose-classes · no-auto-markdown · no-typescript-any · prettier-and-lint-check · uikit-import-source · internal-import-path · uikit-text-vietnamese-first · uikit-no-auto-commit · uikit-parallel-sub-agents · commit-convention · i18n-translation

数据与查询

data-model/object · data-model/field · data-model/record · data-model/related-list · uikit-tanstack-query-hooks · dayjs-date-time

表单系统

uikit-form-react-hook-form · uikit-form-builder · uikit-form-item · uikit-form-control-label

页面模式

page-list-resource — 10 条规则（RULE-LIST-PAGE-01→10）：目录结构、类型、选项、FormProvider+URL 同步、表格+防抖、辅助函数、列 hook、FilterMenu、ActionMenu、数据流

常用组件

uikit-alert · uikit-avatar · uikit-avatar-field · uikit-breadcrumbs · uikit-button · uikit-button-group · uikit-icon-button · uikit-tooltip · uikit-smart-tooltip · uikit-checkbox · uikit-checkbox-group · uikit-ckeditor · uikit-collapsible-container · uikit-confirm-modal · uikit-copy-link-button · uikit-created-by-info · uikit-date-picker · uikit-date-range-calendar · uikit-date-range-picker · uikit-draggable-wrapper · uikit-draggable-item · uikit-drawer · uikit-file-preview · uikit-filter-generator · uikit-filter-generator-base · uikit-help-button · uikit-horizontal-steps · uikit-insert-field-object-v2 · uikit-insert-field-object-button-v2 · uikit-insert-field-object-button-wrapper2 · uikit-layout-select-button · uikit-limitable-list · uikit-link-navigate · uikit-list-view-table · uikit-modal · uikit-option-table · uikit-popper · uikit-reaction · uikit-resize-bar · uikit-skeleton · uikit-step-progress-bar · uikit-steps · uikit-stringee-dnd-context · uikit-table · uikit-table-settings · uikit-tabs · uikit-tag · uikit-text-link · uikit-vertical-steps · uikit-usage-help-button

表单输入

uikit-duration-input · uikit-duration-range-input · uikit-email-input · uikit-emoji-control-picker · uikit-emoji-picker · uikit-file-input · uikit-input-group · uikit-input-number · uikit-markdown-editor · uikit-monaco-editor · uikit-multiple-select · uikit-phone-input · uikit-radio · uikit-radio-group · uikit-rating · uikit-search-input · uikit-select · uikit-slider · uikit-switch · uikit-tags-input · uikit-text-field · uikit-time-picker · uikit-time-range-picker · uikit-time-select · uikit-tree-select · uikit-url-input

Hooks

uikit-use-force-update · uikit-use-get-data-field-by-slug · uikit-use-get-data-field-option-label · uikit-use-get-field-label · uikit-use-get-layout · uikit-use-get-record-page-link · uikit-use-get-state-from-search-params · uikit-use-histories-state · uikit-use-merge-record-filters · uikit-use-merged-refs · uikit-use-replace-record-value · uikit-use-save-to-search-params · uikit-use-sync-state

通知与 Toast

uikit-toast-message — ToastContainer、ToastMessage、showToastMessage、showBrowserNotification（7 条规则：RULE-TOAST-01→07）

单元测试

uikit-unit-test — Vitest + React Testing Library + MSW。纯函数（.test.ts）、hooks（renderHook）、组件（render + userEvent）的模式。通过 MSW handlers 模拟 API，测试工具（renderComponent、renderWrapper），优先覆盖的文件

路径：{skill_base_dir}/reference/<name>.md