@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/templates/shared/rules/fec-responsive-design.md

@@ -1,227 +1,50 @@
-# 响应式设计规则
+# Responsive design rules
 
-凡是任务涉及移动端适配、响应式布局、多端兼容时，都应用本文件。
+This document should be used whenever the task involves mobile adaptation, responsive layout, multi-device compatibility, touch targets or viewport behavior. This article only retains project-resident constraints; layout mode, container query, responsive tables, media and validation details are left to `fec-responsive-layout`.
 
-## 核心原则
+## Core Principles
 
-- **移动优先**: 从小屏幕开始设计，逐步增强到大屏幕
-- **内容优先**: 移动端优先展示核心内容，次要内容折叠或延后
-- **触摸友好**: 所有交互元素必须适配手指操作
-- **性能优先**: 移动端网络和设备性能较弱，需优化加载
-- **容器感知**: 可复用组件优先适配所在容器，而不是假设整页断点
-- **稳定尺寸**: 工具栏、表格列、棋盘、卡片网格和计数器需要稳定约束，避免状态变化导致布局跳动
+- **Mobile First**: Start designing for small screens and work your way up to large screens.
+- **Content Priority**: Small screens give priority to core tasks, key operations and feedback, and secondary content is folded, postponed or entered into the detail layer.
+- **Touch Friendly**: All interactive elements must adapt to finger operations, and key functions cannot rely solely on hover.
+- **Performance first**: The mobile network and device performance are weak, so first-screen resources, charts, animations, and large lists should be restrained.
+- **Container Aware**: Reusable components will first adapt to the container in which they are located, instead of assuming full page breakpoints.
+- **Stable size**: Toolbars, table columns, checkerboards, card grids and counters need stable constraints to avoid layout jumps caused by state changes.
 
-## 断点策略
+## Breakpoints and container strategies
 
-| 断点        | 宽度   | 设备            | Tailwind | 说明                 |
-| ----------- | ------ | --------------- | -------- | -------------------- |
-| **Mobile**  | 375px  | 手机竖屏        | （默认） | 基础样式，无媒体查询 |
-| **Tablet**  | 768px  | 平板 / 手机横屏 | `md:`    | 两列布局起点         |
-| **Desktop** | 1024px | 笔记本          | `lg:`    | 完整布局             |
-| **Large**   | 1280px | 桌面显示器      | `xl:`    | 宽屏优化             |
-| **XLarge**  | 1536px | 超宽屏          | `2xl:`   | 最大内容宽度         |
+- Default validation for 375px, 768px, 1024px, 1440px, and breakpoint intermediate values.
+- Use mobile-first `min-width` breakpoint; do not write the desktop style first and then use `max-width` to supplement the mobile version.
+- Tailwind prefixes are used from smallest to largest: default → `sm:` → `md:` → `lg:` → `xl:` → `2xl:`.
+- Page-level structures can use breakpoints; reusable components that will be placed into sidebars, pop-ups, cards, or main content areas preferentially use container queries.
+- `min-width: 0`, `minmax()`, `aspect-ratio` and explicit overflow strategies must be taken into account when grid/flex children contain long text, charts, code, media or tables.
 
-### 移动优先 CSS
+## Touch target to interact with mobile terminal
 
-```css
-/* 基础样式 — 移动端 */
-.container {
-  padding: 16px;
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
+- When space permits, interaction targets such as buttons, links, and close buttons must be at least 44x44px; compact tool interfaces must be at least operable.
+- Avoid input box font size below 16px to prevent iOS Safari from automatically scaling.
+- Fixed bottom bar, action bar, drawer and dialog box must consider safe area and virtual keyboard.
+- Hover-only messages must have click, focus, or permanent visible alternatives.
+- After switching between horizontal and vertical screens, the main operation, focus position, scroll container and error prompts should still be accessible.
 
-/* Tablet — 768px+ */
-@media (min-width: 768px) {
-  .container {
-    padding: 24px;
-    flex-direction: row;
-    gap: 24px;
-  }
-}
+## Data intensive area
 
-/* Desktop — 1024px+ */
-@media (min-width: 1024px) {
-  .container {
-    max-width: 960px;
-    margin: 0 auto;
-    padding: 32px;
-  }
-}
-```
+- Tables, lists, boards, editors and canvases can be partially scrolled horizontally, but the page as a whole should not have unintentional horizontal overflow.
+- Data-intensive views on the mobile terminal need to define column priorities first: main identification, status and main operations are retained first; low-priority fields enter details, expand rows or drawers.
+- Small screens must still retain the ability to sort, filter, paging, and select.
+- Virtual scrolling only solves the problem of DOM quantity and cannot replace information hierarchy design.
 
-### Tailwind 移动优先
+## Responsive media
 
-Tailwind 默认移动优先，无前缀类作用于所有屏幕，前缀仅覆盖更大断点：
+- Images and videos must have stable size, `aspect-ratio` or container constraints to avoid pushing the layout after loading.
+- Use `srcset`, `sizes`, `picture` or frame picture components when multi-size resources are needed to avoid downloading large desktop images on mobile devices.
+- Media cropping must preserve the main information and do not crop out key areas of products, people, graphics or status to fill the card.
 
-```html
-<!-- 移动端: 单列, 小间距 | Tablet: 双列 | Desktop: 三列 -->
-<div
-  class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6 lg:gap-8"
->
-  <!-- 卡片: 移动端小字, Desktop 大字 -->
-  <div class="p-4 md:p-6 text-sm md:text-base">...</div>
-</div>
+## Checklist
 
-<!-- 导航: 移动端隐藏, Desktop 显示 -->
-<nav class="hidden md:flex">...</nav>
-
-<!-- 移动端汉堡菜单, Desktop 隐藏 -->
-<button class="md:hidden" aria-label="菜单">☰</button>
-```
-
-**关键约定**：
-
-- 始终使用 `min-width` 媒体查询（mobile-first），不用 `max-width`
-- Tailwind 前缀从小到大：`sm:` → `md:` → `lg:` → `xl:`
-- 不要在桌面端写默认样式然后用 `max-width` 覆盖移动端
-
-## 触摸目标
-
-| 元素        | 最小尺寸  | 说明                        |
-| ----------- | --------- | --------------------------- |
-| 按钮        | 44×44px   | WCAG 2.2 触摸目标要求       |
-| 链接        | 44×44px   | 可通过 padding 扩大点击区域 |
-| 表单输入    | 44px 高度 | 避免 iOS 自动缩放           |
-| 复选框/单选 | 24×24px   | 最小可见尺寸                |
-| 关闭按钮    | 44×44px   | 模态框、Toast 的关闭按钮    |
-
-```css
-/* 扩大点击区域（视觉尺寸不变） */
-.icon-button {
-  width: 24px;
-  height: 24px;
-  padding: 10px; /* 实际点击区域 44×44 */
-}
-
-/* 表单输入 — 避免 iOS 缩放 */
-input,
-select,
-textarea {
-  font-size: 16px; /* < 16px 时 iOS Safari 会自动缩放页面 */
-}
-```
-
-## 布局模式
-
-### Container Query
-
-当组件会出现在侧栏、弹窗、卡片和主内容区等不同容器时，优先使用容器查询：
-
-```css
-.summary-panel {
-  container-type: inline-size;
-}
-
-@container (min-width: 42rem) {
-  .summary-panel__body {
-    display: grid;
-    grid-template-columns: 16rem minmax(0, 1fr);
-  }
-}
-```
-
-Flex/Grid 子项包含长文本、图表、代码或表格时，记得设置 `min-width: 0`。
-
-### Stack → Row
-
-移动端纵向堆叠，桌面端横向排列：
-
-```html
-<div class="flex flex-col md:flex-row gap-4">
-  <div class="flex-1">主内容</div>
-  <div class="md:w-64 md:flex-shrink-0">侧边栏</div>
-</div>
-```
-
-### 响应式表格
-
-```html
-<!-- 小屏横向滚动 -->
-<div class="overflow-x-auto">
-  <table class="min-w-full">
-    ...
-  </table>
-</div>
-
-<!-- 或：移动端卡片式布局 -->
-<div class="hidden md:block">
-  <table>
-    ...
-  </table>
-</div>
-<div class="md:hidden">
-  <!-- 每行变为卡片 -->
-</div>
-```
-
-移动端数据密集视图需先定义列优先级：主标识、状态和主操作优先保留；低优先级字段进入详情、展开行或抽屉。
-
-### 响应式图片
-
-```html
-<!-- srcset 按设备像素比加载 -->
-<img
-  src="/img/hero-800.jpg"
-  srcset="
-    /img/hero-400.jpg   400w,
-    /img/hero-800.jpg   800w,
-    /img/hero-1200.jpg 1200w
-  "
-  sizes="(max-width: 768px) 100vw, 800px"
-  alt="描述"
-  loading="lazy"
-/>
-
-<!-- picture 元素按断点切换 -->
-<picture>
-  <source
-    media="(min-width: 1024px)"
-    srcset="/img/hero-desktop.webp"
-    type="image/webp"
-  />
-  <source
-    media="(min-width: 768px)"
-    srcset="/img/hero-tablet.webp"
-    type="image/webp"
-  />
-  <img src="/img/hero-mobile.webp" alt="描述" loading="lazy" />
-</picture>
-```
-
-## 移动端交互注意
-
-- **悬停不可靠**: 移动端无 hover 状态，不要将关键功能隐藏在 hover 中（如 tooltip 改为点击触发）
-- **键盘弹出**: 移动端虚拟键盘会缩小可视区域，固定定位元素需注意位置调整
-- **滚动性能**: 使用 `-webkit-overflow-scrolling: touch`（iOS）或 `overscroll-behavior` 优化滚动体验
-- **安全区域**: 适配 iPhone 刘海/底部横条，使用 `env(safe-area-inset-*)`：
-
-```css
-.app-content {
-  padding-top: env(safe-area-inset-top);
-  padding-bottom: env(safe-area-inset-bottom);
-  padding-left: env(safe-area-inset-left);
-  padding-right: env(safe-area-inset-right);
-}
-```
-
-## 测试策略
-
-- 使用 Chrome DevTools Device Mode 测试主流设备
-- 优先在真实设备上测试（iOS Safari / Android Chrome）
-- 测试方向切换（横屏 / 竖屏）
-- 测试不同网络条件（3G / 4G / 弱网）
-- 不要假设桌面端是"默认"，移动端优先验证
-
-## 检查清单
-
-- [ ] 375px 宽度下布局正常，无水平溢出
-- [ ] 所有交互元素 ≥ 44×44px（触摸目标）
-- [ ] 输入框 font-size ≥ 16px（避免 iOS 缩放）
-- [ ] 无 hover 依赖的关键功能
-- [ ] 图片使用 srcset / picture 按设备加载
-- [ ] iPhone 安全区域适配（safe-area-inset）
-- [ ] 内容在断点间平滑过渡，无突变
-- [ ] 断点中间值、横竖屏切换和虚拟键盘弹出不遮挡主操作
-- [ ] 数据密集区域有列优先级或局部滚动策略
+- [ ] 320-375px No horizontal overflow at page level.
+- [ ] The reading order is reasonable after breakpoint switching, and the main operation is not hidden.
+- [ ] Touch target, input font size, safe area, virtual keyboard and horizontal and vertical screen behaviors have been verified.
+- [ ] loading, empty, error, disabled, hover/focus, long translation text and large numbers will not break the fixed format control.
+- [ ] Column priority, partial scrolling, or mobile summary strategies for data-intensive areas.
+- [ ] The size of first-screen media is stable, and non-first-screen media will not slow down the main path of the mobile terminal.

package/templates/shared/rules/fec-source-driven-development.md

@@ -1,31 +1,31 @@
-# 来源驱动开发规则
+# Source-driven development rules
 
-当实现依赖框架、库、浏览器、运行时、构建工具或平台行为时，先确认事实来源，再写代码或评审结论。
+When an implementation relies on a framework, library, browser, runtime, build tool, or platform behavior, confirm the source of truth before writing code or reviewing conclusions.
 
-## 事实来源优先级
+## Fact source priority
 
-1. 项目内 README、配置、测试、模板和已有实现。
-2. 官方文档、源码、类型定义、release notes、migration guide。
-3. Web 标准、浏览器兼容数据和平台文档。
-4. Issue、讨论、博客和第三方文章仅作为线索。
+1. README, configuration, testing, templates and existing implementations within the project.
+2. Official documents, source code, type definitions, release notes, migration guide.
+3. Web standards, browser compatibility data, and platform documentation.
+4. Issues, discussions, blogs and third-party articles are only used as clues.
 
-## 使用场景
+## Usage scenarios
 
-- 框架新版本、路由、渲染模式、缓存、构建配置、浏览器 API。
-- 公共接口、组件 API、设计系统 token、CLI 命令和插件元数据。
-- 依赖升级、迁移、废弃 API 替换、跨运行时兼容。
-- 与安全、性能、可访问性相关的版本敏感判断。
+- New versions of frameworks, routing, rendering modes, caching, build configurations, browser APIs.
+- Public interfaces, component APIs, design system tokens, CLI commands, and plugin metadata.
+- Dependency upgrade, migration, obsolete API replacement, cross-runtime compatibility.
+- Version-sensitive judgments related to security, performance, and accessibility.
 
-## 输出要求
+## Output requirements
 
-- 写清来源、版本或项目事实、决策结论、影响范围和验证方式。
-- 若项目现状与官方推荐冲突，说明冲突原因和渐进迁移策略。
-- 不复制长篇外部文档；只保留必要结论、链接或项目内文件路径。
-- 无法验证时标注不确定性和需要用户/团队确认的事项。
+- Write down the source, version or project facts, decision conclusion, scope of influence and verification method.
+- If the current status of the project conflicts with official recommendations, explain the cause of the conflict and the gradual migration strategy.
+- Do not copy long external documents; only keep necessary conclusions, links or file paths within the project.
+- Mark uncertainties and matters requiring confirmation from the user/team when they cannot be verified.
 
-## 反模式
+## Anti-pattern
 
-- 凭记忆使用版本敏感 API。
-- 用过时教程替代官方文档。
-- 为追新推翻稳定项目约定。
-- 在组件里散落外部库行为假设，而不是集中到适配层。
+- Use version-sensitive APIs from memory.
+- Replace official documentation with outdated tutorials.
+- Overturn the stable project agreement in order to pursue new projects.
+- Scatter external library behavior assumptions throughout components instead of centralizing them in the adaptation layer.

package/templates/shared/rules/fec-state-management.md

@@ -1,163 +1,60 @@
-# 状态管理规范
+# Status management specifications
 
-## 状态分类
+This document stipulates that the front-end status belongs to the bottom line. State manifests, Store shape examples, URL states, persistence adapters, and SSR isolation details are left to `fec-state-management`; request caching details are left to the data fetch workflow; and form fields and validation are left to the form workflow.
 
-| 类型         | 示例                             | 存放位置            |
-| ------------ | -------------------------------- | ------------------- |
-| 组件 UI 状态 | modal 开关、tab 索引、hover 状态 | 组件内 state        |
-| 表单状态     | 输入值、校验错误                 | 表单库或组件 state  |
-| 服务端数据   | 用户列表、订单详情               | 数据请求库缓存      |
-| 全局业务状态 | 当前用户、权限、主题             | 全局 Store          |
-| URL 状态     | 当前页码、筛选条件、排序         | 路由参数 / 搜索参数 |
+## Status classification
 
-## 核心原则
+| Type | Example | Default Attribution |
+| ---- | ---- | -------- |
+| Local UI state | modal switch, tab, expand row, hover editing state | In-component state / ref |
+| Form status | Input value, dirty field, validation error, submitting | Form library or form component |
+| Server status | List, details, paging results, remote errors | Request cache library |
+| URL status | Search terms, filter, sort, page number, selected tab | Routing parameters / search params |
+| Global client status | Login users, topics, permission snapshots, shopping cart drafts | Global store |
+| Browser persistent state | Preferences, non-sensitive drafts, offline queues | Storage layer + state adapter |
 
-- **就近管理**: 状态放在需要它的最近公共祖先
-- **单一数据源**: 同一份数据只在一个地方维护
-- **派生优于同步**: 可计算的值用 computed / useMemo，而不是手动同步多个 state
-- **最小状态**: 不存储可以从已有状态推导的值
+## Core Principles
 
-## React 状态管理
+- **Own first, choose library later**: Don’t choose Redux, Zustand, Pinia or Context first; determine the unique owner of each state first.
+- **Nearest Management**: The state is placed in the nearest common ancestor that needs it.
+- **Single Data Source**: The same data is maintained in only one place.
+- **Derivation is better than synchronization**: Values that can be derived from props, server state, URL or existing state, do not save a new copy.
+- **Minimum global state**: The global store only saves client state that is truly cross-page, cross-feature, or requires unified action.
 
-### 本地状态
+## React state boundaries
 
-```tsx
-// 简单值 - useState
-const [count, setCount] = useState(0);
+- Use `useState` / `useReducer` for single components or small subtrees.
+- Low-frequency global configuration, theme or dependency injection can use Context; large objects that change frequently should not be placed in Context.
+- For moderately complex business states, Zustand, Jotai or existing warehouse solutions can be used; for large and strict action flows, Redux Toolkit can be used.
+- Server-side data uses the request cache library and is not copied to the global store.
 
-// 复杂逻辑 - useReducer
-const [state, dispatch] = useReducer(formReducer, initialState);
-```
+## Vue state boundary
 
-### 全局状态（Zustand 示例）
+- Use `ref` / `reactive` / `computed` for local state.
+- Use `provide/inject` for local cross-level context.
+- Global business status uses Pinia or the existing store of the project.
+- Server-side data is first managed using the request library or composable and is not written to Pinia intact.
 
-<!-- 请根据项目实际选型调整：Redux Toolkit / Zustand / Jotai -->
+## URL and persistent state
 
-```tsx
-const useAuthStore = create<AuthState>((set) => ({
-  user: null,
-  login: async (credentials) => {
-    const user = await authApi.login(credentials);
-    set({ user });
-  },
-  logout: () => set({ user: null }),
-}));
-```
+- When searching, filtering, sorting, paging, selecting tabs, etc., the view state that needs to be shared or refreshed should be given priority to the URL.
+- Browser persistence only saves stable preferences or non-sensitive drafts, and clearly identifies field whitelists, version numbers, migration paths, expiration policies, and sensitive field exclusions.
+- In SSR scenarios, do not create a single instance store with user data at the top level of the module; each request requires an independent instance.
 
-### 服务端状态
+## Anti-pattern
 
-<!-- 请根据项目实际选型调整：React Query / SWR -->
+- Put all state into global store.
+- Store UI temporary state or each field of the form in the store.
+- Manually synchronize multiple copies of the same data instead of deriving from source state.
+- Store the server response intact in the global store without requesting the cache library.
+- Use Context / provide to carry large objects that change frequently, resulting in large-scale re-rendering.
+- Persistent tokens, permission details, personal sensitive data or unversioned large objects.
 
-```tsx
-const { data, isLoading, error } = useQuery({
-  queryKey: ["users", params],
-  queryFn: () => fetchUsers(params),
-  staleTime: 5 * 60 * 1000,
-});
-```
+## Checklist
 
-## Vue 状态管理
-
-### 本地状态
-
-```typescript
-const count = ref(0);
-const form = reactive({ name: "", email: "" });
-```
-
-### 全局状态（Pinia）
-
-```typescript
-export const useAuthStore = defineStore("auth", () => {
-  const user = ref<User | null>(null);
-
-  async function login(credentials: LoginParams) {
-    user.value = await authApi.login(credentials);
-  }
-
-  function logout() {
-    user.value = null;
-  }
-
-  const isLoggedIn = computed(() => user.value !== null);
-
-  return { user: readonly(user), isLoggedIn, login, logout };
-});
-```
-
-### 服务端状态
-
-<!-- 请根据项目实际选型调整：VueQuery / 自定义 composable -->
-
-```typescript
-const { data, isLoading, error } = useQuery({
-  queryKey: ["users", params],
-  queryFn: () => fetchUsers(toValue(params)),
-});
-```
-
-## 选型决策矩阵
-
-### React 全局状态管理选型
-
-| 维度           | Context API                            | Zustand                                | Redux Toolkit                   | Jotai               |
-| -------------- | -------------------------------------- | -------------------------------------- | ------------------------------- | ------------------- |
-| **适用场景**   | 全局常量（主题、语言、用户信息）       | 复杂业务状态（购物车、Dashboard 筛选） | 大型应用，需要严格的状态流控制  | 细粒度原子状态      |
-| **重渲染性能** | ❌ 任何 value 变化导致所有消费者重渲染 | ✅ 通过 selector 精确订阅              | ✅ connect/useSelector 精确订阅 | ✅ 原子级订阅       |
-| **样板代码**   | 少（Provider + createContext）         | 极少（一个 create 调用）               | 多（slice / action / selector） | 极少（atom）        |
-| **DevTools**   | ❌ 无                                  | ✅ Redux DevTools（中间件）            | ✅ Redux DevTools               | ✅ 专用 DevTools    |
-| **TypeScript** | ⚠️ 需手动类型标注                      | ✅ 自动推导                            | ✅ 自动推导                     | ✅ 自动推导         |
-| **中间件**     | ❌                                     | ✅（persist / devtools / immer）       | ✅（thunk / listener）          | ✅                  |
-| **Provider**   | ✅ 必须包裹                            | ❌ 不需要（外部 store）                | ✅ Provider                     | ❌（可选 Provider） |
-
-**推荐决策流程**：
-
-```
-状态是否跨组件共享？
-├── 否 → useState / useReducer（本地状态）
-└── 是
-    ├── 值是否几乎不变？（主题、语言、配置）
-    │   └── 是 → Context API
-    │
-    ├── 是否需要严格状态流 + 时间旅行调试？
-    │   └── 是 → Redux Toolkit
-    │
-    ├── 状态是否高度关联、需要集中管理？
-    │   └── 是 → Zustand
-    │
-    └── 状态是否独立、需要细粒度订阅？
-        └── 是 → Jotai
-```
-
-### Vue 全局状态管理选型
-
-| 维度           | provide/inject                     | Pinia            |
-| -------------- | ---------------------------------- | ---------------- |
-| **适用场景**   | 局部跨层级传递（主题、表单上下文） | 全局业务状态     |
-| **响应式**     | ✅（传入 reactive/ref）            | ✅               |
-| **DevTools**   | ❌                                 | ✅ Vue DevTools  |
-| **TypeScript** | ⚠️ 需 InjectionKey                 | ✅ 自动推导      |
-| **SSR 安全**   | ⚠️ 需注意作用域                    | ✅ 内置 SSR 支持 |
-
-**Vue 选型结论**：Pinia 是 Vue 3 官方推荐，新项目直接使用。provide/inject 仅用于局部上下文传递。
-
----
-
-## 反模式
-
-- 将所有状态都放进全局 store（应优先本地状态）
-- 在 store 中存放 UI 临时状态（modal 开关、表单输入等）
-- 手动同步多份相同数据而不是用计算属性
-- 在组件中直接修改 store 的内部数据（应通过 action / mutation）
-- 将服务端响应原封不动存入全局 store 而不用请求缓存库
-- 过度使用 Context / provide 替代 props 传递
-- 用 Context 管理频繁更新的状态（导致全量消费者重渲染，应改用 Zustand/Pinia）
-
-## 检查清单
-
-- [ ] 每个状态都有明确的归属（本地 / 全局 / URL / 服务端缓存）
-- [ ] 可派生的值没有被存为独立 state
-- [ ] 全局 store 仅包含真正需要跨组件共享的数据
-- [ ] 服务端数据通过请求库管理，而非手动存入 store
-- [ ] URL 状态（搜索、分页、筛选）与路由参数同步
-- [ ] Context 仅用于低频变更的全局值（主题、语言、用户信息）
+- [ ] Each state has a clear ownership: local / form / server cache / URL / global store / browser persistence.
+- [ ] Derivable values are not stored as independent state.
+- [ ] The global store only contains data that is truly shared across boundaries.
+- [ ] Server-side data is managed through the request library, and refreshes, rollbacks, permission changes, and error states can still be recovered.
+- [ ] URL state is synchronized with route parameters, and refresh and share behavior is as expected.
+- [ ] Persistence status has whitelist, version, migration and sensitive field exclusions.