@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/skills/fec-refactoring-move-features/references/moving-refactorings.md

@@ -0,0 +1,453 @@
+# Moving Feature Refactorings
+
+These cards transform the supplied standard catalog into concise operational guidance for frontend agents. Standard IDs/names are preserved; examples and framework adaptations are original.
+
+## RF-MOVE-FUNCTION — Move Function
+
+### Intent
+Move behavior to the module that owns most of the data it uses or the responsibility it represents.
+
+### Typical Signals
+- A function depends more on another module’s data than its current home.
+
+### Avoid When
+- Do not move orchestration merely because it calls several collaborators; coordination may be its responsibility.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify data ownership and change responsibility.
+2. Create/copy the function at the destination with a narrow interface.
+3. Delegate from the old location while migrating callers.
+4. Remove the old location only when dependencies and public contracts permit.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-DIVERGENT-CHANGE`
+- `SMELL-SHOTGUN-SURGERY`
+- `SMELL-FEATURE-ENVY`
+- `SMELL-TEMPORARY-FIELD`
+- `SMELL-MESSAGE-CHAINS`
+- `SMELL-INSIDER-TRADING`
+- `SMELL-ALTERNATIVE-CLASSES-DIFFERENT-INTERFACES`
+- `SMELL-DATA-CLASS`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: a component-local mailbox quota calculation mostly reads account policy data. After: move it to the account policy module and keep UI code declarative.
+
+## RF-MOVE-FIELD — Move Field
+
+### Intent
+Move data to the object/module that conceptually owns it and changes with it.
+
+### Typical Signals
+- A field is read/updated mainly by another owner or repeatedly travels with another data cluster.
+
+### Avoid When
+- Avoid moving a public serialized field without a compatibility plan.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify the real owner and all reads/writes.
+2. Add storage/access at the destination.
+3. Redirect reads and writes incrementally.
+4. Remove old storage after state synchronization is no longer required.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-SHOTGUN-SURGERY`
+- `SMELL-INSIDER-TRADING`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: a view controller owns `quotaLimit` though policy service controls it. After: policy owns the field and UI reads through the policy boundary.
+
+## RF-MOVE-STATEMENTS-INTO-FUNCTION — Move Statements into Function
+
+### Intent
+Move statements that always accompany a function call into that function so the shared operation is complete.
+
+### Typical Signals
+- The same setup/teardown statement appears around many calls and belongs to the called operation.
+
+### Avoid When
+- Do not move caller-specific policy into a generic function.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Find repeated adjacent statements around the call.
+2. Move one shared statement into the callee.
+3. Verify callers and ordering.
+4. Repeat only for behavior truly common to all callers.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: every caller formats a draft ID immediately before `saveDraft`. After: `saveDraft` owns canonical ID formatting if it is always required.
+
+## RF-MOVE-STATEMENTS-TO-CALLERS — Move Statements to Callers
+
+### Intent
+Move behavior out of a function when only some callers need it or its policy varies by context.
+
+### Typical Signals
+- A formerly common step is now caller-specific.
+
+### Avoid When
+- Avoid duplicating logic when the behavior is still a stable invariant of every caller.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify the statement whose policy varies.
+2. Expose or split the callee so callers can perform the varying step.
+3. Move the statement to one caller at a time.
+4. Verify ordering and shared invariants.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: `loadMessages` always shows a toast, but background refresh must not. After: callers decide whether to notify after loading.
+
+## RF-REPLACE-INLINE-CODE-WITH-FUNCTION-CALL — Replace Inline Code with Function Call
+
+### Intent
+Use an existing function instead of duplicating equivalent inline logic.
+
+### Typical Signals
+- Inline logic already has a trustworthy named implementation elsewhere.
+
+### Avoid When
+- Do not replace merely similar logic when semantics or edge cases differ.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Prove equivalence between inline code and the existing function.
+2. Replace one occurrence with the call.
+3. Verify result, error, and evaluation semantics.
+4. Remove any now-unused local helpers.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: an inline loop checks whether a folder is special. After: call the existing `isSpecialFolder(id)` helper when semantics match exactly.
+
+## RF-SLIDE-STATEMENTS — Slide Statements
+
+### Intent
+Reorder statements so related code is adjacent and a later extraction or simplification becomes possible.
+
+### Typical Signals
+- Statements that belong together are separated by unrelated work.
+
+### Avoid When
+- Do not reorder across side effects, awaits, exceptions, subscriptions, or reads/writes whose order is observable.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Map dependencies and side effects between statements.
+2. Move the smallest statement across only independent operations.
+3. Verify after each move.
+4. Stop when the intended cluster is adjacent.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-DUPLICATED-CODE`
+- `SMELL-MUTABLE-DATA`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: two normalization statements are separated by an unrelated analytics call. After: move only if analytics timing and data dependencies are unchanged.
+
+## RF-SPLIT-LOOP — Split Loop
+
+### Intent
+Separate a loop that performs multiple independent tasks into focused passes.
+
+### Typical Signals
+- One loop computes unrelated results with separate accumulators.
+
+### Avoid When
+- Avoid when the extra pass is materially expensive or iteration order/side effects couple the tasks.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify independent loop responsibilities.
+2. Duplicate the iteration and keep one responsibility in each pass.
+3. Verify outputs/order/performance.
+4. Then extract or pipeline individual loops if useful.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-LONG-FUNCTION`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: one loop both counts unread messages and builds attachment names. After: split into two focused passes when collection size and order permit.
+
+## RF-REPLACE-LOOP-WITH-PIPELINE — Replace Loop with Pipeline
+
+### Intent
+Express a collection transformation as a sequence of named filter/map/reduce-style operations.
+
+### Typical Signals
+- An imperative loop mostly filters, maps, or accumulates data and bookkeeping hides intent.
+
+### Avoid When
+- Keep loops for early exits, complex mutation, tight performance constraints, or async sequencing when clearer.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify the element-level transformation stages.
+2. Replace one stage with an equivalent collection operation.
+3. Preserve ordering and callback semantics.
+4. Verify empty inputs, errors, and performance-sensitive paths.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-LOOPS`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: push matching attachment names into an array inside a loop. After: `attachments.filter(isVisible).map(a => a.name)` when behavior matches.
+
+## RF-REMOVE-DEAD-CODE — Remove Dead Code
+
+### Intent
+Remove code proven to have no reachable runtime or supported-tooling use.
+
+### Typical Signals
+- A function, export, branch, asset, style, route, or dependency has no legitimate references.
+
+### Avoid When
+- Do not infer deadness from grep alone when dynamic imports, routes, Storybook, i18n, Tailwind classes, runtime templates, or external consumers may reference it.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Prove unused status across static and dynamic reference channels.
+2. Classify risk before deletion.
+3. Use the dedicated cleanup workflow for actual removal.
+4. Run relevant build/tests after deletion.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-SPECULATIVE-GENERALITY`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: an obsolete component appears unused. After: route actual proof and deletion through `fec-refactor-clean`, including dynamic-reference checks.

package/skills/fec-refactoring-validation/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: fec-refactoring-validation
+description: Use when proving that a frontend refactoring preserved existing behavior, selecting an appropriate safety net, validating each structural step, or assigning a PASS, PARTIAL, or NOT PROVEN preservation verdict.
+---
+
+# Skill: Refactoring Validation
+
+## Purpose
+
+Define the observable contract and the smallest credible evidence needed to prove that structural edits preserved existing frontend behavior.
+
+## Procedure
+
+1. Record the relevant behavior contract before substantial edits.
+2. Classify safety-net coverage as A, B, or C.
+3. Run and record the pre-change baseline.
+4. Match verification to the current refactoring risk and affected boundary.
+5. After every structural step, run the narrowest sufficient check immediately.
+6. If a newly introduced failure appears, revert that step before broader repair.
+7. At the end, run the broad gates justified by the affected surface.
+8. Assign PASS, PARTIAL, or NOT PROVEN from evidence, not optimism.
+
+Pure structural work uses **GREEN → REFACTOR → GREEN**.
+
+## Safety-Net Levels
+
+| Level | Evidence | Execution guidance |
+| --- | --- | --- |
+| A — Strong | Existing tests cover relevant behavior | Use tests as the primary safety net |
+| B — Partial | Important behavior is only partly covered | Add focused characterization of current behavior before risky steps |
+| C — None | No useful automated behavior coverage | Do not auto-install a framework; keep CAUTION/DANGER plan-only unless a minimal safety net is authorized |
+
+## Frontend Contract Checklist
+
+Check relevant items, not every item mechanically:
+
+- function inputs, outputs, exceptions, and error mapping;
+- DOM structure that consumers depend on, visible states, focus, keyboard flow, and accessibility semantics;
+- props, emits, slots, hook/composable return values, and event ordering;
+- requests, payloads, cancellation, retries, cache keys, and loading/error transitions;
+- store state, persistence, object identity, memoization, refs/reactivity, and lifecycle timing;
+- routes, URLs, guards, package exports, serialized fields, and backend-facing DTOs.
+
+## References
+
+- Load [behavior-preservation.md](references/behavior-preservation.md) for contract construction and proof levels.
+- Load [refactoring-test-checklist.md](references/refactoring-test-checklist.md) for targeted verification by frontend risk.
+
+## Constraints
+
+- Passing unrelated tests does not prove preservation.
+- A green test written only after the change is weaker evidence than a pre-change baseline or characterization test.
+- Do not rewrite expected values simply because the refactor changed behavior.
+- Do not hide missing proof behind a PASS label.
+- Do not install a new test framework without explicit authorization.
+
+## Expected Output
+
+A behavior-preservation record containing baseline status, safety-net level, per-step checks, final validation, unresolved coverage gaps, and a PASS/PARTIAL/NOT PROVEN verdict.

package/skills/fec-refactoring-validation/references/behavior-preservation.md

@@ -0,0 +1,53 @@
+# Behavior Preservation
+
+## Build the Contract
+
+Before changing structure, identify which observations must remain stable. Use the smallest contract that fully covers the affected boundary.
+
+### Functional contract
+
+- accepted inputs and normalization;
+- return values and output ordering;
+- errors, exceptions, and fallback behavior;
+- side effects and significant ordering.
+
+### UI contract
+
+- rendered states and user-visible text/data;
+- enabled/disabled behavior;
+- focus and keyboard transitions;
+- event/callback ordering;
+- accessibility relationships that users or tests rely on.
+
+### State and async contract
+
+- store transitions and persistence;
+- request count, URL, method, payload, cancellation, retry, and error mapping;
+- loading/error/empty state timing;
+- React identity/memoization and hook dependency semantics;
+- Vue `ref`, `reactive`, `computed`, `watch`, and lifecycle identity/timing.
+
+### Public contract
+
+- exported symbols and call signatures;
+- routes and URL parameters;
+- serialized fields and API DTOs;
+- extension, plugin, template, or runtime registration points.
+
+## Characterization Tests
+
+When behavior is important but weakly covered, write a narrow test that captures current behavior before a risky structural edit. It may pass immediately because it records the existing contract. Do not broaden it into a new requirement.
+
+## Verdicts
+
+### PASS
+
+Use only when the relevant contract is well identified, the before/after baseline is comparable, and all required checks pass.
+
+### PARTIAL
+
+Use when checks pass but meaningful paths remain untested or only static/manual evidence covers an important boundary.
+
+### NOT PROVEN
+
+Use when dependencies cannot be installed, required tools cannot run, the baseline is ambiguous, or the safety net cannot credibly distinguish preservation from accidental behavior change.

package/skills/fec-refactoring-validation/references/refactoring-test-checklist.md

@@ -0,0 +1,42 @@
+# Refactoring Test Checklist
+
+## Local Function or Module
+
+- targeted unit tests for inputs, outputs, and errors;
+- typecheck of affected package/module;
+- callers compile with unchanged contracts;
+- no public export change unless planned.
+
+## React
+
+- hook order and dependency arrays remain valid;
+- stale closure behavior is not introduced;
+- controlled/uncontrolled ownership remains stable;
+- memoization or referential equality assumptions are preserved;
+- effect cleanup, request cancellation, and event order remain stable;
+- Server/Client boundaries and hydration behavior are unchanged when relevant.
+
+## Vue
+
+- `ref`/`reactive` identity and unwrapping semantics remain stable;
+- computed values stay derived rather than duplicated mutable state;
+- watchers keep intended source, flush timing, and cleanup;
+- props, emits, slots, and expose contracts remain stable;
+- Pinia store ownership and persistence remain stable.
+
+## API and Data
+
+- request shape, headers, auth refresh, cancellation, retry, and errors remain stable;
+- field renames do not cross DTO, storage, query-string, or backend contracts unintentionally;
+- sorting/filtering transformations preserve order, duplicates, and edge cases;
+- reference-to-value or value-to-reference changes preserve required identity semantics.
+
+## Routing and Runtime Registration
+
+- route names/paths/guards remain stable;
+- dynamic imports and lazy registrations remain discoverable;
+- Storybook, i18n, CSS/Tailwind dynamic classes, runtime templates, and generated metadata are not broken by search-only reasoning.
+
+## Final Ladder
+
+Run available checks from narrowest to broadest: targeted tests -> affected integration tests -> lint/typecheck -> full tests -> build -> E2E/SSR/visual/a11y/performance specialty gates when the refactoring touches those risks.

package/skills/fec-responsive-layout/SKILL.md

@@ -1,34 +1,34 @@
 ---
 name: fec-responsive-layout
-description: Use when designing, implementing, or reviewing responsive frontend layouts, mobile-first breakpoints, container queries, fluid grids, data-dense tables, touch targets, safe areas, orientation changes, viewport overflow, or cross-device UI behavior; Chinese triggers include 响应式布局, 移动端适配, 断点, 容器查询, 横竖屏, 触摸目标.
+description: Use when designing, implementing, or reviewing responsive frontend layouts, mobile-first breakpoints, container queries, fluid grids, data-dense tables, touch targets, safe areas, orientation changes, viewport overflow, or cross-device UI behavior; Chinese triggers include responsive layouts, mobile-side adaptation, breakpoints, container queries, horizontal and vertical screens, touch targets.
 ---
 
-# 响应式布局
+# Responsive layout
 
-适用于需要让页面、工具界面、表格、仪表盘或组件在多设备上稳定工作的前端任务。需要布局模式和检查清单时加载 [references/responsive-layout-patterns.md](references/responsive-layout-patterns.md)。
+Suitable for front-end tasks that require pages, tool interfaces, tables, dashboards or components to work stably on multiple devices. Load [references/responsive-layout-patterns.md](references/responsive-layout-patterns.md) when layout patterns and checklists are required.
 
 ## Purpose
 
-用内容优先、移动优先和容器感知的方式设计响应式布局，避免只靠固定断点修补溢出。
+Design responsive layouts in a content-first, mobile-first, and container-aware manner to avoid relying solely on fixed breakpoints to fix overflow.
 
 ## Procedure
 
-1. 明确信息优先级：小屏先保留核心任务、关键操作和反馈；次要信息折叠、延后或移入详情层。
-2. 选择布局策略：简单页面用 mobile-first 断点；嵌套组件、卡片网格和侧栏优先考虑 container query。
-3. 设计流式尺寸：用 `minmax()`、`clamp()`、`aspect-ratio`、`max-width`、`min-width: 0` 和稳定网格轨道控制伸缩。
-4. 处理数据密集界面：表格、列表、看板和编辑器需要明确横向滚动、列优先级、冻结列或移动端摘要视图。
-5. 保证触摸与键盘：触摸目标、焦点路径、hover 替代、虚拟键盘、安全区域和横竖屏切换都要复核。
-6. 关联性能与资源：移动端减少首屏大图、重型图表、同步动画和不必要列渲染。
-7. 验证断点之间：检查 375px、768px、1024px、1440px，以及断点中间值是否溢出、遮挡或跳变。
+1. Clarify the priority of information: On small screens, core tasks, key operations and feedback are retained first; secondary information is folded, postponed or moved to the detail layer.
+2. Choose a layout strategy: use mobile-first breakpoints for simple pages; give priority to container query for nested components, card grids and sidebars.
+3. Design flow size: use `minmax()`, `clamp()`, `aspect-ratio`, `max-width`, `min-width: 0` and stable grid track to control scaling.
+4. Handle data-intensive interfaces: tables, lists, boards, and editors need to explicitly support horizontal scrolling, column prioritization, frozen columns, or mobile summary views.
+5. Ensure touch and keyboard: touch targets, focus paths, hover substitutions, virtual keyboards, safe areas, and horizontal and vertical screen switching should all be reviewed.
+6. Correlate performance and resources: The mobile terminal reduces first-screen large images, heavy charts, synchronized animations and unnecessary column rendering.
+7. Verify between breakpoints: check 375px, 768px, 1024px, 1440px, and whether the intermediate value of the breakpoint overflows, blocks, or jumps.
 
 ## Constraints
 
-- 不把桌面版缩小当作移动端设计。
-- 不让关键功能只依赖 hover 或宽屏侧栏。
-- 不用固定高度掩盖内容变化；需要固定格式时用稳定约束和可滚动区域。
-- 不用 viewport 字体缩放替代真实排版层级。
-- 不让移动端横向溢出成为默认解决方案；只有数据表、画布或编辑器等明确场景可以局部横滚。
+- Don’t treat the desktop version downsized as a mobile design.
+- Don’t make key features rely solely on hover or widescreen sidebars.
+- Do not use fixed height to cover content changes; use stable constraints and scrollable areas when fixed format is required.
+- Do not use viewport font scaling instead of real typography hierarchy.
+- Do not make mobile horizontal overflow the default solution; only explicit scenes such as data tables, canvases or editors can partially scroll.
 
 ## Expected Output
 
-输出响应式信息优先级、断点或容器策略、关键组件布局模式、触摸/键盘要求、数据密集区域处理方案和验证结果。完成后页面在常见视口和输入方式下不溢出、不遮挡、可操作。
+Outputs responsive information prioritization, breakpoint or container strategies, key component layout patterns, touch/keyboard requirements, data-intensive area handling options, and validation results. After completion, the page will not overflow, not be blocked, and is operable under common viewports and input methods.