{"id":"235aa86f-7522-4d10-87eb-bae0f65ece5a","entityType":"agent","slug":"clawhub-bovinphang-fec-react-project-standard","name":"React Project Standard","canonicalUrl":"https://www.xpersona.co/agent/clawhub-bovinphang-fec-react-project-standard","canonicalPath":"/agent/clawhub-bovinphang-fec-react-project-standard","generatedAt":"2026-10-12T14:19:02.389Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T22:30:12.372Z","emptyReason":null},"description":"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibil Skill: React Project Standard Owner: bovinphang Summary: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibil Tags: latest:2.9.0 Version history: v2.9.0 | 2026-09-26T14:43:","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 984 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s175m64gr8tsfc06cj22czzfys83mp52:fec-react-project-standard","sourceUrl":"https://clawhub.ai/bovinphang/fec-react-project-standard","homepage":"https://clawhub.ai/bovinphang/skills/fec-react-project-standard","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/bovinphang/fec-react-project-standard","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/bovinphang/skills/fec-react-project-standard","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T22:30:12.372Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T22:30:12.372Z","emptyReason":null},"stars":null,"forks":null,"downloads":984,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"2.9.0","tractionLabel":"984 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T22:30:12.067Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T22:30:12.372Z","lastCrawledAt":"2026-10-11T22:30:12.067Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T22:30:12.067Z","lastVerifiedAt":null,"highlights":[{"version":"2.9.0","createdAt":"2026-09-26T14:43:19.038Z","changelog":"- Added LICENSE file to clarify usage terms and licensing. - Removed skill-card.md. - SKILL.md content updated from Chinese to English for broader accessibility. - No functional or technical changes to logic or process; documentation and licensing updates only.","fileCount":11,"zipByteSize":19697},{"version":"2.7.0","createdAt":"2026-06-11T02:14:04.267Z","changelog":"- 分解和重组了参考文档，移除 react-project-details.md，新增四个参考文档：react-project-structure.md、react-runtime-patterns.md、react-quality-patterns.md、react-performance-patterns.md。 - 详细参考部分按主题引导加载各自 reference 文件，原有指向已删除的 react-project-details.md 链接被替换。 - 增加项目性能轻量筛查、输出要求和约束，包括性能风险识别流程和性能相关变更的说明要求。 - 更新 TypeScript 类型约定、跨模块类型收敛与标准输出要求，细化 expected output 和 constraints。 - 移除 skill-card.md 及无效链路，文档结构与内容更加聚合和条理清晰。","fileCount":10,"zipByteSize":19425},{"version":"2.4.0","createdAt":"2026-06-01T09:54:11.302Z","changelog":"**v1.0.1 Summary:** Initial release of a modular React project standard, reorganizing documentation and adding comprehensive references for structure and conventions. - Renamed the skill and broadened its audience/purpose to guide overall React + TypeScript structure and conventions. - Added core documentation files: LICENSE, README.md, metadata.json, and a detailed project structure reference. - Removed outdated summary file (skill-card.md). - Updated guidelines to emphasize modular boundaries, code organization, practical constraints, and process for implementing or reviewing React project structure. - Directed detailed structural and component references to a separate file for easier lookup.","fileCount":7,"zipByteSize":16593}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175m64gr8tsfc06cj22czzfys83mp52:fec-react-project-standard","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T14:19:02.387Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-bovinphang-fec-react-project-standard/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T22:30:12.372Z","emptyReason":null},"readme":"Skill: React Project Standard\n\nOwner: bovinphang\n\nSummary: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibil\n\nTags: latest:2.9.0\n\nVersion history:\n\nv2.9.0 | 2026-09-26T14:43:19.038Z | user\n\n- Added LICENSE file to clarify usage terms and licensing.\n- Removed skill-card.md.\n- SKILL.md content updated from Chinese to English for broader accessibility.\n- No functional or technical changes to logic or process; documentation and licensing updates only.\n\nv2.7.0 | 2026-06-11T02:14:04.267Z | user\n\n- 分解和重组了参考文档，移除 react-project-details.md，新增四个参考文档：react-project-structure.md、react-runtime-patterns.md、react-quality-patterns.md、react-performance-patterns.md。\n- 详细参考部分按主题引导加载各自 reference 文件，原有指向已删除的 react-project-details.md 链接被替换。\n- 增加项目性能轻量筛查、输出要求和约束，包括性能风险识别流程和性能相关变更的说明要求。\n- 更新 TypeScript 类型约定、跨模块类型收敛与标准输出要求，细化 expected output 和 constraints。\n- 移除 skill-card.md 及无效链路，文档结构与内容更加聚合和条理清晰。\n\nv2.4.0 | 2026-06-01T09:54:11.302Z | user\n\n**v1.0.1 Summary:** \nInitial release of a modular React project standard, reorganizing documentation and adding comprehensive references for structure and conventions.\n\n- Renamed the skill and broadened its audience/purpose to guide overall React + TypeScript structure and conventions.\n- Added core documentation files: LICENSE, README.md, metadata.json, and a detailed project structure reference.\n- Removed outdated summary file (skill-card.md).\n- Updated guidelines to emphasize modular boundaries, code organization, practical constraints, and process for implementing or reviewing React project structure.\n- Directed detailed structural and component references to a separate file for easier lookup.\n\nArchive index:\n\nArchive v2.9.0: 11 files, 19697 bytes\n\nFiles: LICENSE (1089b), metadata.json (2415b), package.json (1234b), README.md (1870b), references/react-performance-patterns.md (1978b), references/react-project-structure.md (7974b), references/react-quality-patterns.md (6161b), references/react-runtime-patterns.md (10263b), skill-card.md (2026b), SKILL.md (6813b), _meta.json (145b)\n\nFile v2.9.0:SKILL.md\n\n---\nname: fec-react-project-standard\ndescription: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React project specification, React component architecture.\n---\n\n# React project specifications\n\nSuitable for medium and large module construction, page reconstruction and engineering structure design in React + TypeScript warehouse.\n\n## Purpose\n\nProvide engineering structure, module boundaries and default implementation conventions for React + TypeScript projects to ensure clear architecture and maintainable code.\n\n## Procedure\n\nThis skill mainly solves the problem of \"how to design and implement\" React engineering tasks, without repeating the basic coding bottom line. When handling React engineering tasks, perform them in the following order:\n\n1. Identify the warehouse and have an agreement\n - Directory organization\n - Style system\n - Status management solution\n - Request packaging method\n - Testing framework\n - UI component library/design system\n\n2. Determine which layer the target belongs to\n - Routing page\n -Page private components\n - feature business module\n - Global common components\n - hooks / services / stores / utils\n\n3. Design the boundaries before writing the code\n - What logic belongs to page layout\n - Which logic belongs to feature\n - Which logic should be transferred to general capabilities?\n - Which state should be managed locally and which should be handed over to store/query/URL\n - When the status ownership is complex, use the status management process to make a status list first\n - When the boundaries of DTO, public props, generic components or `tsconfig` are complex, first use the TypeScript project specification process to converge cross-framework type contracts\n\n4. Complete key quality items when outputting\n - loading / error / empty / data status\n - Error handling and retrying\n - Type constraints\n - Key test entrance\n - Diversion of necessary special skills\n - Check whether the dependency already exists in `package.json`. If it is missing, give the installation command first and then use it.\n - Whether heavy UI capabilities (animation, charts, 3D, editors, maps) are isolated as leaf components and loaded on demand\n - Whether images, videos, fonts and other resources are localized and cacheable, and avoid placeholder URLs from entering delivery\n - Whether page-level Error Boundary, module-level fallback, API error mapping and user-recoverable actions are consistent\n - Whether Tailwind token/variant or responsive layout requirements should be diverted to the corresponding special skill\n- Perform lightweight screening for obvious architectural performance risks, such as heavy dependency boundaries, too wide Context, high-frequency derived values and lazy loading fallback; enter the performance optimization workflow when indicator evidence is needed\n\n## Detailed reference\n\nLoad more detailed reference files as needed:\n\n- Project Directory, Component Hierarchy, Component Boundary and Component Directory Recommendations: Load [references/react-project-structure.md](references/react-project-structure.md).\n- Component pattern, Hooks, routing, state ownership, API layer, error handling and Suspense/lazy loading: Load [references/react-runtime-patterns.md](references/react-runtime-patterns.md).\n- Style, annotations, TypeScript, tests, anti-patterns and output checklist: Loading [references/react-quality-patterns.md](references/react-quality-patterns.md).\n- Lightweight performance conventions at the React project specification level: Load [references/react-performance-patterns.md](references/react-performance-patterns.md).\n\n## Constraints\n\n- Comply with the existing global rules and React rules of the warehouse by default\n- If the warehouse already has a clear directory structure, style system, status management or request encapsulation, the warehouse convention will be used first.\n- The size of the component file should be approximately **300 lines**; if it exceeds **500 lines** or is too complex, it must be split into sub-components, Hooks, utils, and types.\n- It is forbidden to add new class components (Error Boundary uses libraries such as `react-error-boundary`)\n- Disable bypassing module exports and importing from feature deep paths\n- Do not use `useEffect + setState` to simulate derived values that can be calculated directly\n- Avoid prop drilling too deep without considering composition or partial encapsulation\n- Do not synchronously introduce GSAP, Three.js, Lottie, rich text editor or map SDK into common page components; use dynamic import, route-level subcontracting or leaf component isolation when necessary.\n- No bare `fetch`, API URL, token refresh or upload processes scattered around React components; cross-border requests should be converged to the API integration layer.\n- Do not use Error Boundary to handle normal API failures; request errors should first fall into the loading/error/empty/data state and recoverable operations.\n- Do not write React performance recommendations as global memo without evidence; first locate request waterfall, bundle boundaries, repeated rendering or effect misuse.\n\n## Expected Output\n\n- Component boundaries are clear, pages/features/components are clearly layered\n- The Props type is complete and clear; the narrowing of complex public types or external data has been diverted to the TypeScript project specification process\n- Reusable logic has been extracted into hooks, and the loading/error/empty/data status is complete\n- The API layer has type constraints and unified error handling, and status management conforms to the proximity principle\n- URL status, server status, form status and global client status have clear boundaries\n- Key behaviors are covered by tests, and key modules have been wrapped with `react-error-boundary`\n- The long list has been evaluated for virtualization, and pop-up/composite components have keyboard and focus support\n- Respect the current situation of the warehouse first, and then recommend the structure\n- Give necessary suggestions for file division\n- Explain why this is layered if necessary\n- For new modules, give priority to outputting the smallest floor-mountable structure rather than over-designing it all at once\n- For reconstruction tasks, give priority to ensuring portability and risk controllability\n- For performance-related React changes, describe the triggered risk categories, evidence sources, and verification commands\n\nFile v2.9.0:README.md\n\n# React project specifications\n\nOrganize React and TypeScript components, hooks, routes, state boundaries, and project structure.\n\n## Skill\n\n- ID: `fec-react-project-standard`\n- Category: `project-standard`\n- Version: `2.9.0`\n- Source: `skills/fec-react-project-standard/SKILL.md`\n\n## Description\n\nUse when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React project specification, React component architecture.\n\n## Usage\n\nInstall or import this package with any skill runtime that understands the standard `SKILL.md` layout. The canonical source remains the Frontend Craft repository.\n\n## Packaged Files\n\n- [references/react-performance-patterns.md](references/react-performance-patterns.md)\n- [references/react-project-structure.md](references/react-project-structure.md)\n- [references/react-quality-patterns.md](references/react-quality-patterns.md)\n- [references/react-runtime-patterns.md](references/react-runtime-patterns.md)\n\n## Optional Related Packages\n\n- `@bovinphang/fec-typescript-project-standard`\n- `@bovinphang/fec-state-management`\n- `@bovinphang/fec-tailwind-design-system`\n- `@bovinphang/fec-responsive-layout`\n- `@bovinphang/fec-form-handling`\n- `@bovinphang/fec-data-fetching`\n- `@bovinphang/fec-component-testing`\n- `@bovinphang/fec-e2e-testing`\n- `@bovinphang/fec-accessibility-check`\n- `@bovinphang/fec-security-review`\n- `@bovinphang/fec-list-virtualization`\n- `@bovinphang/fec-svg-animation`\n- `@bovinphang/fec-canvas-threejs`\n- `@bovinphang/fec-api-integration`\n- `@bovinphang/fec-motion-interaction`\n\n## License\n\nMIT\n\nFile v2.9.0:_meta.json\n\n{\n \"ownerId\": \"kn7b0nh7hvj1pffeqc8y0dqwwh83m726\",\n \"slug\": \"fec-react-project-standard\",\n \"version\": \"2.9.0\",\n \"publishedAt\": 1790433799038\n}\n\nFile v2.9.0:references/react-performance-patterns.md\n\n# React performance patterns\n\nThis file keeps lightweight React project-standard performance guidance. Use the frontend performance workflow when the task needs metrics, traces, profiles, bundle analysis, network evidence, or a formal performance report.\n\n### Performance (in conjunction with the \"Performance Optimization\" section)\n\n- **useMemo**: Expensive derivation, large list sorting/filtering; pay attention to immutable data, such as `useMemo(() => [...list].sort(...), [list])`, and avoid directly `sort` the mutable original array.\n- **useCallback**: passed to **`React.memo`** sub-component or used as a callback for other Hook dependencies, used when there is a stable reference requirement.\n- **React.memo**: An acceptable component with pure display and shallow props; do not apply memo globally.\n- **Virtual List**: For very long lists, use **TanStack Virtual**, **react-window**, etc., and only render nodes in the viewport (see \"Suspense and Lazy Loading\" for routing-level and component-level lazy loading).\n\n## Performance optimization\n\nConsider performance optimization in the following scenarios:\n\n- Large list/large table\n- High frequency re-rendering components\n- Complex trees passed with a large number of props\n- Heavy-duty third-party components\n- High frequency changing context\n\n### Recommended means\n\n- Use `React.memo` appropriately\n- Use `useMemo` / `useCallback` only when necessary\n- List uses stable `key`\n- Use virtual scrolling for large lists\n- Code splitting at routing level\n- Avoid putting high-frequency changing values into the top-level context\n- Avoid meaninglessly creating a large number of new objects/new functions/new arrays in render\n- Heavy charting, editor, map, 3D and media processing capabilities into leaf components or route-level lazy loading boundaries\n- Lazy loading components must be equipped with loading, error, empty or downgraded UI to avoid only optimizing the package body but destroying the user state\n\n---\n\nFile v2.9.0:references/react-project-structure.md\n\n# React project structure and component boundaries\n\n## Project structure (recommended reference)\n\nThe following is the industry's best practice structure for medium and large React projects, tailored according to the actual situation of the project:\n\n```text\nsrc/\n├── app/ # Application entry and global configuration\n│ ├── App.tsx # Root component (Provider combination)\n│ ├── routes.tsx # Routing configuration\n│ └── providers.tsx # Global Provider assembly\n│\n├── pages/ # Page components (one-to-one correspondence with routing)\n│ ├── Dashboard/\n│ │ ├── DashboardPage.tsx\n│ │ ├── components/ # Page private components\n│ │ └── hooks/ # Page private hooks\n│ ├── UserList/\n│ └── Settings/\n│\n├── layouts/ # Layout component\n│ ├── MainLayout.tsx # Main layout (sidebar + top bar + content area)\n│ ├── AuthLayout.tsx # Login/registration page layout\n│ └── BlankLayout.tsx # Blank layout (error page, etc.)\n│\n├── features/ # Function modules (divided by business areas)\n│ ├── auth/\n│ │ ├── components/ # Module components\n│ │ ├── hooks/ # module hooks\n│ │ ├── api.ts # Module API call\n│ │ ├── types.ts # Module type definition\n│ │ ├── constants.ts # Module constants\n│ │ └── index.ts # Module publicly exported\n│ └── order/\n│\n├── components/ # Globally shared UI components\n│ ├── Button/\n│ │ ├── Button.tsx\n│ │ ├── Button.styles.css\n│ │ └── __tests__/\n│ ├── Modal/\n│ ├── Form/\n│ └── ErrorBoundary/ # Thin wrapper (function component) for react-error-boundary etc.\n│\n├── hooks/ # Global shared hooks\n│ ├── useAuth.ts\n│ ├── useDebounce.ts\n│ └── useMediaQuery.ts\n│\n├── services/ # API base layer\n│ ├── request.ts # Axios/fetch instance and interceptor\n│ └── endpoints/ # API endpoint definition (such as split by field)\n│\n├── stores/ # Global status management\n│ ├── authStore.ts\n│ └── uiStore.ts\n│\n├── locales/ # International language pack\n│ ├── zh-CN.json # Simplified Chinese\n│ ├── en-US.json # English\n│ └── index.ts # i18n instance initialization (i18next / react-intl)\n│\n├── assets/ # Static resources\n│ ├── images/ # Pictures (PNG, JPG, WebP)\n│ ├── icons/ # SVG icon\n│ └── fonts/ # Custom fonts\n│\n├── config/ # Application configuration\n│ ├── env.ts # Typed encapsulation of environment variables\n│ └── features.ts # Feature Flags Management\n│\n├── types/ # Global shared types\n│ ├── api.ts # API response/request common type\n│ ├── models.ts #Business entity type\n│ └── global.d.ts # Global type extension (picture module declaration, etc.)\n│\n├── utils/ # Pure utility function\n│ ├── format.ts # Date, number, currency formatting\n│ ├── validators.ts # Form validation rules\n│ └── storage.ts # LocalStorage / SessionStorage package\n│\n├── styles/ # Global styles and themes\n│ ├── global.css # Global basic style (reset/normalize)\n│ ├── variables.css # CSS variables (color, spacing, font size)\n│ ├── breakpoints.ts # Responsive breakpoint constants\n│ └── themes/ # theme definition\n│ ├── light.css # Light theme variable\n│ ├── dark.css # Dark theme variable\n│ └── index.ts # theme switching logic\n│\n└── constants/ # Global constants\n ├── routes.ts #Routing path constants\n └── config.ts #Business constants (paging size, timeout, etc.)\n```\n\n### Key Principles\n\n- `pages/` does route mapping and page arrangement, and does not carry large pieces of reusable business logic.\n- `layouts/` is responsible for the page skeleton and layout container, referenced by the routing configuration\n- `features/` is divided according to business areas, and the module should be as self-contained as possible\n- `components/` only contains common components that are reused across pages and modules\n- `hooks/` only puts global general hooks; business hooks are put back to the corresponding feature or page first\n- `locales/` stores language pack JSON files, use `t('key')` in the component instead of hard-coded copy\n- `assets/` stores static resources, SVG is preferred for icons, and WebP/AVIF is preferred for images.\n- `services/` is responsible for requesting infrastructure and does not stack business details\n- `config/` uniformly encapsulates environment variables and feature switches, prohibiting direct reading of `import.meta.env` in components\n- `styles/` and theme variables are managed uniformly to avoid colors and sizes being scattered in business code\n- Each module controls the public API through `index.ts` to avoid deep path imports\n\n---\n\n## Component and module layering\n\nRecommended layering:\n\n```text\nPage components (Pages) → route mapping, layout combination, page arrangement\n └── Container/orchestration layer → data acquisition, status organization, event orchestration\n └── Business components → Domain logic display\n └── Common components → No business coupling, reusable across modules\n```\n\n### When to put it in `pages/`\n\nSuitable for:\n\n- Routing entry component\n- Page level layout combination\n- Page private lightweight orchestration logic\n\nNot suitable for:\n\n- A lot of domain logic\n- Complex business blocks that can be reused on multiple pages\n- API/hooks/types that are strongly bound to a certain business domain\n\n### When to put it in `features/`\n\nSuitable for:\n\n- Components, hooks, apis, and types of a certain business domain\n- Logic that can be shared by multiple pages but has business semantics\n- Self-contained implementation of a complete business unit\n\n### When to put it in `components/`\n\nSuitable for:\n\n- Common UI such as buttons, pop-up windows, form items, table shells, empty states, error states, etc.\n- Components that have nothing to do with specific business and can be reused across modules\n\n---\n\n## Component design specifications\n\n- Use **Functional Components**, Hooks and TypeScript; **Do not** add new class components (Error Boundary uses libraries such as `react-error-boundary`, see below)\n- **Single file size** and splitting principles can be found in `templates/shared/rules/fec-react.md` \"**Component file size**\" (approximately 300 lines is preferred, if it exceeds 500 lines or is too complex, sub-components, Hooks, utils, and types will be split)\n- Keep components with single responsibilities and composable\n- Extract reusable logic into hooks\n- Prioritize the use of controlled component APIs in appropriate scenarios\n- props are clearly defined and typed\n- Prioritize reuse of existing design system components\n- Maintain accessibility with keyboard interaction\n- Avoid deep JSX nesting and duplicate branches\n- Do not store additional state for deducible values\n\n---\n\n\n## Component directory suggestions\n\nWhen the component complexity is low, only one file can be kept. \nWhen a component contains styles, subcomponents, hooks, and tests, it is recommended to use the following structure:\n\n```text\nComponentName/\n├── ComponentName.tsx\n├── ComponentName.types.ts\n├── ComponentName.styles.css\n├── hooks/\n│ └── useComponentLogic.ts\n├── components/\n│ └── SubComponent.tsx\n└── __tests__/\n └── ComponentName.spec.tsx\n```\n\nDescription:\n\n- Split `ComponentName.types.ts` when the type is complex\n- Split `hooks/` when there is local logic reuse\n- When the subcomponent is only used inside the current component, it is placed in the current directory `components/`\n- Whether the test should be placed nearby should follow the existing protocols of the warehouse\n\n---\n\nFile v2.9.0:references/react-quality-patterns.md\n\n# React quality patterns\n\n## Style access\n\nThis skill does not enforce a specific style scheme and follows the current status of the warehouse by default.\n\nPlease note when adapting:\n\n- Tailwind project continues to use Tailwind\n- CSS Modules projects keep naming consistent with file organization\n- The styled-components project continues to follow its pattern\n- Theme, color, font size, spacing, etc. give priority to reusing warehouse token / CSS variables\n- Avoid hardcoding a large number of visual constants within the component\n- Disable inline styles (except dynamic values)\n- Responsive processing must be consistent with the project breakpoint agreement\n\n---\n\n## Comment specifications\n\n- **Prefer using Chinese**: When explaining \"why this is done\", business constraints, boundary conditions, and non-obvious trade-offs, give priority to writing comments in Chinese to make it easier for the team and business parties to read.\n- **Exception when consistent with the code language**: When connecting third-party protocol field names, HTTP headers, and English terms in specifications, English proper nouns can be retained in the comments, and Chinese and English descriptions can be given when necessary.\n- **Less but more precise**: Can express clear logic through clear naming and types without writing nonsense comments; complex branches, temporary compatibility, and performance trade-offs must be clearly stated.\n- **Public API**: The external contract of modules or hooks can use JSDoc (`@param` / `@returns` / `@example`). The instructions can be in Chinese, unless the warehouse requires English.\n\n---\n\n## TypeScript Specification\n\nCommon TypeScript project rules are taken care of by `fec-typescript-project-standard`, including `tsconfig`, strictness, DTO / view model boundaries, `unknown` narrowing, public API types, declared artifacts, and type tests.\n\nThe React specification only supplements components, Props, events and TSX generic writing; complex type modeling or cross-framework type contracts are first offloaded to `fec-typescript-project-standard`.\n\n### React project supplementary conventions\n\n- Props interface naming: `ComponentNameProps`\n- Event handling function: `handle` prefix (such as `handleClick`)\n- Callback Props: `on` prefix (such as `onChange`, `onSubmit`)\n- Components give priority to writing explicit props and return value types (`JSX.Element` / `React.ReactElement`) to avoid behavioral differences such as relying on the implicit `children` of `React.FC`\n- Generic components use `` constraints to maintain call-site type derivation; callback and event types preferentially use DOM/React’s own types (such as `React.ChangeEvent`)\n\n```tsx\ninterface TableProps> {\n data: T[];\n columns: ColumnDef[];\n onRowClick?: (row: T) => void;\n}\n```\n\n---\n\n## Test specifications\n\n### Content that should be covered first\n\n- Core interaction behaviors (click, input, submit)\n- Conditional rendering (loading/error/empty/data)\n- Return values and side effects of key hooks\n- API call mock and module-level integration testing\n\n### Recommended style\n\n- Test user behavior, not implementation details\n- Prioritize using `screen.getByRole`, `getByLabelText`\n- Avoid writing brittle tests around internal state\n- Only measure key behaviors and do not mechanically pursue coverage figures\n\n### Example\n\n```tsx\ndescribe(\"UserForm\", () => {\n it(\"should submit with valid data\", async () => {\n const onSubmit = vi.fn();\n render();\n\n await userEvent.type(screen.getByLabelText(\"username\"), \"test\");\n await userEvent.click(screen.getByRole(\"button\", { name: \"Submit\" }));\n\n expect(onSubmit).toHaveBeenCalledWith({ username: \"test\" });\n });\n\n it(\"should show error on invalid input\", async () => {\n render();\n await userEvent.click(screen.getByRole(\"button\", { name: \"Submit\" }));\n expect(screen.getByText(\"Username cannot be empty\")).toBeInTheDocument();\n });\n});\n```\n\n---\n\n\n## Common anti-patterns\n\nAvoid:\n\n- prop drilling is too deep without considering combination or partial encapsulation\n- Excessive use of context for local issues\n- Stuff data requests, view rendering, and imperative DOM operations into one file\n- Do things in useEffect that can be done in event handlers\n- Use `useEffect + setState` to simulate derived values that could be calculated directly\n- Push all states to the global store\n- Put business coupling components in `components/`\n- Directly bypass the module export and import from the feature deep path\n- There is no obvious benefit but complex optimization is done in advance\n- **New class component** or handwritten class Error Boundary (should function component + `react-error-boundary`, etc.)\n\n---\n\n## Output checklist\n\nWhen outputting React code or solutions, at least check:\n\n- [ ] Whether to align the existing contracts of the warehouse first\n- [ ] Page / feature / Is the boundary of common components clear?\n- [ ] Whether the directory structure matches the module complexity\n- [ ] Props type is complete and clear\n- [ ] Whether explanatory comments should be given priority in Chinese and to the point\n- [ ] Whether reusable logic has been extracted into hooks\n- [ ] loading / error / empty / data status is complete\n- [ ] Whether the API layer has type constraints and unified error handling\n- [ ] Whether complex DTO, external data narrowing, public types or `tsconfig` issues have been offloaded to `fec-typescript-project-standard`\n- [ ] Whether status management complies with the proximity principle\n- [ ] Whether lazy loading is considered for routing-level or heavy-duty modules\n- [ ] Whether the style scheme is consistent with the warehouse\n- [ ] Whether key behaviors are covered by tests\n- [ ] Key modules have been wrapped with **`react-error-boundary`** (etc.), and no hand-written class component Boundary\n- [ ] Whether the long list evaluates virtualization; whether the pop-up window/composite component has keyboard and focus conventions\n- [ ] Whether unnecessary new dependencies or new paradigms are introduced\n\n---\n\nFile v2.9.0:references/react-runtime-patterns.md\n\n# React runtime patterns\n\n## Common UI and status mode\n\nThe following patterns can be used in comparison with other chapters of this skill (Hooks, state management, performance optimization, error handling); **Select based on business complexity and team familiarity** to avoid patterns for pattern's sake. The ideas refer to common React front-end pattern practices in the industry (such as component combination, composite components, performance and accessibility, etc.).\n\n### Composition is better than inheritance\n\n- Use **small subcomponents** + `children` / explicit props to assemble the interface instead of building a class inheritance hierarchy in React.\n- Example: `Card` + `CardHeader` + `CardBody`, composed by the consumer, rather than one giant `Card` branched with a lot of boolean props.\n\n### Compound Components\n\n- The root component provides internal state (such as current Tab, open/closed) to child components through **Context**.\n- The subcomponent **throws an error or asserts** when `useContext` is empty, making it clear that it \"must be used within the Provider tree\".\n- API surfaces remain readable: ``.\n\n### Render Props/Functionator\n\n- Applicable: Encapsulate **data acquisition and three-state** (loading / error / data), and hand over **rendering decision** to the parent.\n- Choose one of the two with **Custom Hook**: `useXxx()` + ordinary components are more intuitive in most scenarios; only keep Render Props when strong constraints on \"same-layer rendering logic\" are required.\n\n### Context + useReducer\n\n- Suitable for **moderate complexity, multi-subtree sharing** client state, and updates can be reduced to explicit `action`.\n- Avoid stuffing large objects that change frequently into the top-level Context; server-side data still takes priority **React Query / SWR**.\n- Large global business status continues to use the **Zusand / Redux Toolkit / Jotai** selected by the warehouse.\n\n### Form\n\n- Controlled fields + validation error objects are a feasible implementation; medium and large forms are given priority **React Hook Form** (or Formik) + **Zod**, and complex form values, DTO and validation type contracts are offloaded to `fec-typescript-project-standard`.\n- Avoid huge `useState` form objects and repeated validation logic in a single component, detachable field subcomponents or extract `useFormSchema`.\n\n### Error Boundary\n\n- **Don't** handwrite Error Boundary in the form of React **class component** in business code; uniformly use **`react-error-boundary`** (or a similar library recognized by the team) to render failure at the **module boundary** (consistent with \"Error Handling\" and `error-handling.md` in this chapter).\n- Use `FallbackComponent` and `resetErrorBoundary` to provide \"retry\"; **log reporting** is placed in the library's **`onError`** (waiting for callbacks), and production code avoids long-term dependence on `console.log` (see TypeScript rules).\n\n\n### Animation and Transition\n\n- List entry and exit can be done using **Framer Motion**'s `AnimatePresence` + `key`, or CSS `transition`; note that reduced layout jitter and `prefers-reduced-motion` (when consistent with accessibility policies).\n\n### Accessibility and Focus\n\n- Customized drop-downs, tabs, etc.: **`role` / `aria-*`**, **Direction keys / Enter / Escape** Behavior and focus rings are visible.\n- Pop-up window: Move the focus into the dialog box when it is opened, and **restore** when it is closed to trigger the element focus; **`focus-trap-react`** or similar solutions can be used to complement the `fec-accessibility-check` skill.\n\n### Next.js and server-side components\n\n- **App Router, Server Components, server-side data acquisition and caching** see **`fec-nextjs-project-standard`**; the client interaction mode is still subject to this chapter and the Hooks specification.\n\n---\n\n\n## Hooks design pattern\n\n### Suitable for scenarios where custom Hooks are drawn\n\n- Data acquisition and three-state management\n- Form status logic\n- Paging, filtering, sorting and arrangement\n- Event monitoring and side effect cleanup\n- Interaction logic that can be reused in multiple components\n\n### Recommended principles\n\n- Uniformly use `use` prefix naming\n- Return objects instead of arrays to facilitate on-demand destructuring and enhance readability and scalability\n- State and behavior are encapsulated together\n- Hook internal processing `loading/error/data`\n- Expose a clear minimal interface to the outside world without leaking irrelevant internal details\n\n### Example\n\n```tsx\nfunction useUserList(params: QueryParams) {\n const [data, setData] = useState([]);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n\n const fetch = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const res = await getUserList(params);\n setData(res.list);\n } catch (e) {\n setError(e as Error);\n } finally {\n setLoading(false);\n }\n }, [params]);\n\n useEffect(() => {\n fetch();\n }, [fetch]);\n\n return { data, loading, error, refetch: fetch };\n}\n```\n\n### Hook usage principles\n\n- `useEffect` must have correct dependencies and cleanup logic\n- `useMemo` / `useCallback` Don’t overuse it, add it only when stable references are really important\n- Don't call hooks in conditional branches or loops\n- When React Query / SWR has been introduced, data requests go through these libraries first instead of recreating a cache layer yourself.\n\n---\n\n## Routing organization\n\n### Recommended method\n\n- Centralized management of routing configuration\n- Path constantization\n- Lazy loading of page components on demand\n- Permission control is placed in the guard layer instead of scattered within the page components\n- Paging, filtering, sorting, etc. URL driver status is synchronized with the address bar first\n\n### Example\n\n```tsx\nconst routes: RouteObject[] = [\n {\n path: \"/\",\n element: ,\n children: [\n { index: true, element: },\n { path: \"users\", element: },\n { path: \"users/:id\", element: },\n { path: \"settings\", element: },\n ],\n },\n { path: \"/login\", element: },\n { path: \"*\", element: },\n];\n```\n\n```tsx\nconst UserListPage = lazy(() => import(\"@/pages/UserList/UserListPage\"));\n\nfunction ProtectedRoute({ children }: { children: React.ReactNode }) {\n const { isAuthenticated } = useAuth();\n if (!isAuthenticated) return ;\n return <>{children};\n}\n```\n\n---\n\n## Status management selection\n\n| Status type | Recommended solution |\n| ------------------ | ------------------------------------------------- |\n| Temporary UI state within the component | `useState` / `useReducer` |\n| Sharing business status across components | Zustand / Redux Toolkit / Jotai (actual selection by warehouse) |\n| Server-side data caching | React Query / SWR |\n| URL driver status | Route parameters / `useSearchParams` |\n| Form State | React Hook Form / Formik |\n\n### Core Principles\n\n- Proximity management: try to place the state on the nearest common ancestor\n-Single data source: Do not maintain multiple copies of the same data\n- Derived over synchronized: computable values are calculated first at render time\n- The server-side data is given priority to the request library management and is not manually inserted into the global store.\n- Don’t upgrade local state to global state in advance just because it “may be used in the future”\n\n---\n\n## API layer specification\n\n### Design principles\n\n- Request infrastructure is centralized in `services/`\n-Business APIs are split by feature instead of stacking them all in one file\n- Both request parameters and response results should have clear types\n- Authentication, error formatting, and universal interception are handled uniformly at the request layer\n- Do not directly scatter splicing request details on pages and components\n\n### Example\n\n```ts\n// services/request.ts\nconst request = axios.create({\n baseURL: import.meta.env.VITE_API_BASE_URL,\n timeout: 10000,\n});\n\nrequest.interceptors.response.use(\n (res) => res.data,\n (error) => {\n if (error.response?.status === 401) {\n redirectToLogin();\n }\n return Promise.reject(normalizeError(error));\n },\n);\n```\n\n```ts\n// features/user/api.ts\nexport function getUserList(\n params: UserQueryParams,\n): Promise> {\n return request.get(\"/users\", { params });\n}\n\nexport function updateUser(id: string, data: UpdateUserDTO): Promise {\n return request.put(`/users/${id}`, data);\n}\n```\n\n---\n\n## Error handling\n\n### Status that must be overridden\n\n- Loading\n- Error\n- Empty\n- Data\n\n### Recommended practices\n\n- Use Error Boundary to wrap key functional modules to avoid local exceptions causing a full-page white screen\n- Visible feedback must be given to the user when an asynchronous request fails\n- Provide retry capability for important operations\n- Don’t catch mistakes, don’t write empty `catch`\n\n### Example (`react-error-boundary`, functional Fallback)\n\n```tsx\nimport { ErrorBoundary } from \"react-error-boundary\";\n\nfunction ModuleErrorFallback({\n resetErrorBoundary,\n}: {\n resetErrorBoundary: () => void;\n}) {\n return (\n
\n Module loading failed\n \n
\n );\n}\n\nexport function UserDashboardSection() {\n return (\n \n \n \n );\n}\n```\n\n---\n\n## Suspense and lazy loading\n\nApplicable scenarios:\n\n- Routing level page\n- Large components such as charts, rich text editors, maps, heavy tables, etc.\n- Modules with higher initialization costs\n\nExample:\n\n```tsx\nconst HeavyChart = lazy(() => import(\"./components/HeavyChart\"));\n\nfunction Dashboard() {\n return (\n }>\n \n \n );\n}\n```\n\nSuggestions:\n\n- Route level priority `lazy + Suspense`\n- `fallback` gives priority to using Skeleton or a placeholder state closer to the content instead of a pure spinner\n\n---\n\nFile v2.9.0:skill-card.md\n\n## Description:\n\nGuides developers in designing and reviewing React and TypeScript project structure, component boundaries, hooks, routing, state, and API conventions.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[bovinphang](https://clawhub.ai/user/bovinphang)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers use this skill to design or review maintainable React and TypeScript applications, including project layout, feature boundaries, state ownership, error handling, and performance conventions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Broad activation may apply these conventions where a narrower workflow or existing team standard is more suitable.\n\nMitigation: Check the task scope and existing project conventions before applying recommendations.\n\nRisk: The guidance prefers Chinese comments, which may conflict with a team's language policy.\n\nMitigation: Follow the project's established comment language and review generated comments before adoption.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/bovinphang/skills/fec-react-project-standard)\n- [React project structure](references/react-project-structure.md)\n- [React runtime patterns](references/react-runtime-patterns.md)\n- [React quality patterns](references/react-quality-patterns.md)\n- [React performance patterns](references/react-performance-patterns.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Code, Shell commands]\n\n**Output Format:** [Markdown with code examples and optional shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Recommendations adapt to existing project conventions.]\n\n## Skill Version(s):\n\n2.9.0 (source: server-resolved release)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.9.0:metadata.json\n\n{\n \"id\": \"fec-react-project-standard\",\n \"name\": \"React project specifications\",\n \"category\": \"project-standard\",\n \"tags\": [\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"summary\": \"Organize React and TypeScript components, hooks, routes, state boundaries, and project structure.\",\n \"version\": \"2.9.0\",\n \"license\": \"MIT\",\n \"homepage\": \"https://github.com/bovinphang/frontend-craft\",\n \"repository\": \"https://github.com/bovinphang/frontend-craft\",\n \"keywords\": [\n \"project-standard\",\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"platforms\": [\n \"skills-cli\",\n \"skillreg\",\n \"claude-code\",\n \"codex\",\n \"cursor\",\n \"opencode\",\n \"openclaw\",\n \"generic-skill-runtime\"\n ],\n \"description\": \"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React project specification, React component architecture.\",\n \"source\": \"skills/fec-react-project-standard\",\n \"references\": [\n \"references/react-performance-patterns.md\",\n \"references/react-project-structure.md\",\n \"references/react-quality-patterns.md\",\n \"references/react-runtime-patterns.md\"\n ],\n \"relations\": {\n \"relatedSkills\": [\n \"fec-typescript-project-standard\",\n \"fec-state-management\",\n \"fec-tailwind-design-system\",\n \"fec-responsive-layout\",\n \"fec-form-handling\",\n \"fec-data-fetching\",\n \"fec-component-testing\",\n \"fec-e2e-testing\",\n \"fec-accessibility-check\",\n \"fec-security-review\",\n \"fec-list-virtualization\",\n \"fec-svg-animation\",\n \"fec-canvas-threejs\",\n \"fec-api-integration\",\n \"fec-motion-interaction\"\n ],\n \"boundaryWorkflows\": [\n \"Use specialty workflows for complex forms, state ownership, TypeScript contracts, server state, tests, accessibility, security, large lists, animation, or graphics.\",\n \"Keep generic React component architecture and hooks organization in the React project workflow.\"\n ],\n \"capabilityTags\": [\n \"react\",\n \"project-standard\",\n \"fec-architecture\"\n ]\n }\n}\n\nFile v2.9.0:package.json\n\n{\n \"name\": \"@bovinphang/fec-react-project-standard\",\n \"version\": \"2.9.0\",\n \"description\": \"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React project specification, React component architecture.\",\n \"type\": \"module\",\n \"license\": \"MIT\",\n \"author\": {\n \"name\": \"Bovin Phang\",\n \"email\": \"pengbaowen@msn.com\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/bovinphang/frontend-craft\",\n \"directory\": \"skills/fec-react-project-standard\"\n },\n \"homepage\": \"https://github.com/bovinphang/frontend-craft\",\n \"keywords\": [\n \"agent-skill\",\n \"frontend-craft\",\n \"project-standard\",\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"files\": [\n \"SKILL.md\",\n \"references\",\n \"scripts\",\n \"data\",\n \"assets\",\n \"metadata.json\",\n \"README.md\",\n \"LICENSE\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n }\n}\n\nFile v2.9.0:LICENSE\n\nMIT License\r\n\r\nCopyright (c) 2025 Bovin Phang\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy\r\nof this software and associated documentation files (the \"Software\"), to deal\r\nin the Software without restriction, including without limitation the rights\r\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\ncopies of the Software, and to permit persons to whom the Software is\r\nfurnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all\r\ncopies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\nSOFTWARE.\n\nArchive v2.7.0: 10 files, 19425 bytes\n\nFiles: metadata.json (2333b), package.json (1215b), README.md (1788b), references/react-performance-patterns.md (1602b), references/react-project-structure.md (7672b), references/react-quality-patterns.md (5059b), references/react-runtime-patterns.md (8890b), skill-card.md (2536b), SKILL.md (5341b), _meta.json (145b)\n\nFile v2.7.0:SKILL.md\n\n---\nname: fec-react-project-standard\ndescription: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\n---\n\n# React 项目规范\n\n适用于 React + TypeScript 仓库中的中大型模块建设、页面重构和工程结构设计。\n\n## Purpose\n\n为 React + TypeScript 项目提供工程结构、模块边界和默认实现约定，确保架构清晰、代码可维护。\n\n## Procedure\n\n本 skill 主要解决 React 工程任务“如何设计和落地”的问题，不重复声明基础编码底线。处理 React 工程化任务时，按以下顺序执行：\n\n1. 识别仓库已有约定\n - 目录组织方式\n - 样式体系\n - 状态管理方案\n - 请求封装方式\n - 测试框架\n - UI 组件库 / 设计系统\n\n2. 判断目标属于哪一层\n - 路由页面\n - 页面私有组件\n - feature 业务模块\n - 全局通用组件\n - hooks / services / stores / utils\n\n3. 设计边界后再落代码\n - 哪些逻辑属于页面编排\n - 哪些逻辑属于 feature\n - 哪些逻辑应下沉为通用能力\n - 哪些状态应本地管理，哪些应交给 store / query / URL\n - 状态归属复杂时使用状态管理流程先做状态清单\n - DTO、公共 props、泛型组件或 `tsconfig` 边界复杂时，先使用 TypeScript 项目规范流程收敛跨框架类型契约\n\n4. 输出时补齐关键质量项\n - loading / error / empty / data 状态\n - 错误处理与重试\n - 类型约束\n - 关键测试入口\n - 必要的专项 skill 分流\n - 依赖是否已存在于 `package.json`，缺失时先给安装命令再使用\n - 重型 UI 能力（动效、图表、3D、编辑器、地图）是否隔离为 leaf component 并按需加载\n - 图片、视频、字体等资源是否本地化、可缓存，并避免占位 URL 进入交付\n - 页面级 Error Boundary、模块级 fallback、API 错误映射和用户可恢复动作是否一致\n - Tailwind token/variant 或响应式布局需求是否应分流到对应专项 skill\n - 对明显架构性能风险做轻量筛查，如重型依赖边界、过宽 Context、高频派生值和懒加载 fallback；需要指标证据时进入性能优化 workflow\n\n## 详细参考\n\n按需要加载更细的参考文件：\n\n- 项目目录、组件分层、组件边界和组件目录建议：加载 [references/react-project-structure.md](references/react-project-structure.md)。\n- 组件模式、Hooks、路由、状态归属、API 层、错误处理和 Suspense/懒加载：加载 [references/react-runtime-patterns.md](references/react-runtime-patterns.md)。\n- 样式、注释、TypeScript、测试、反模式和输出检查清单：加载 [references/react-quality-patterns.md](references/react-quality-patterns.md)。\n- React 项目规范层面的轻量性能约定：加载 [references/react-performance-patterns.md](references/react-performance-patterns.md)。\n\n## Constraints\n\n- 默认遵守仓库现有全局规则和 React rule\n- 若仓库已有明确目录结构、样式体系、状态管理或请求封装，优先沿用仓库约定\n- 组件文件规模宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分子组件、Hooks、utils、类型\n- 禁止新增类组件（Error Boundary 用 `react-error-boundary` 等库）\n- 禁止绕过模块出口，从 feature 深层路径导入\n- 不要用 `useEffect + setState` 模拟本可直接计算的派生值\n- 避免 prop drilling 过深却不考虑组合或局部封装\n- 不在通用页面组件里同步引入 GSAP、Three.js、Lottie、富文本编辑器或地图 SDK；需要时用动态导入、路由级分包或叶子组件隔离。\n- 不在 React 组件中散落裸 `fetch`、API URL、token refresh 或上传流程；跨边界请求应收敛到 API 集成层。\n- 不用 Error Boundary 处理普通 API 失败；请求错误应优先落到 loading/error/empty/data 状态和可恢复操作。\n- 不把 React 性能建议写成无证据的全局 memo 化；先定位请求瀑布、bundle 边界、重复渲染或 effect 误用。\n\n## Expected Output\n\n- 组件边界清晰，pages/features/components 分层明确\n- Props 类型完整且明确；复杂公共类型或外部数据收窄已分流到 TypeScript 项目规范流程\n- 可复用逻辑已提取为 hooks，loading/error/empty/data 状态齐全\n- API 层具备类型约束和统一错误处理，状态管理符合就近原则\n- URL 状态、服务端状态、表单状态和全局客户端状态边界明确\n- 关键行为有测试覆盖，关键模块已用 `react-error-boundary` 包裹\n- 超长列表已评估虚拟化，弹窗/复合组件具备键盘与焦点支持\n- 先尊重仓库现状，再给推荐结构\n- 给出必要的文件划分建议\n- 必要时说明为什么这样分层\n- 对新增模块，优先输出最小可落地结构，而不是一次性过度设计\n- 对重构任务，优先保证可迁移性和风险可控\n- 对性能相关 React 变更，说明触发的风险类别、证据来源和验证命令\n\nFile v2.7.0:README.md\n\n# React 项目规范\n\nFrontend Craft skill for React 项目规范.\n\n## Skill\n\n- ID: `fec-react-project-standard`\n- Category: `project-standard`\n- Version: `2.7.0`\n- Source: `skills/fec-react-project-standard/SKILL.md`\n\n## Description\n\nUse when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\n\n## Usage\n\nInstall or import this package with any skill runtime that understands the standard `SKILL.md` layout. The canonical source remains the Frontend Craft repository.\n\n## Packaged Files\n\n- [references/react-performance-patterns.md](references/react-performance-patterns.md)\n- [references/react-project-structure.md](references/react-project-structure.md)\n- [references/react-quality-patterns.md](references/react-quality-patterns.md)\n- [references/react-runtime-patterns.md](references/react-runtime-patterns.md)\n\n## Optional Related Packages\n\n- `@bovinphang/fec-typescript-project-standard`\n- `@bovinphang/fec-state-management`\n- `@bovinphang/fec-tailwind-design-system`\n- `@bovinphang/fec-responsive-layout`\n- `@bovinphang/fec-form-handling`\n- `@bovinphang/fec-data-fetching`\n- `@bovinphang/fec-component-testing`\n- `@bovinphang/fec-e2e-testing`\n- `@bovinphang/fec-accessibility-check`\n- `@bovinphang/fec-security-review`\n- `@bovinphang/fec-list-virtualization`\n- `@bovinphang/fec-svg-animation`\n- `@bovinphang/fec-canvas-threejs`\n- `@bovinphang/fec-api-integration`\n- `@bovinphang/fec-motion-interaction`\n\n## License\n\nMIT\n\nFile v2.7.0:_meta.json\n\n{\n \"ownerId\": \"kn7b0nh7hvj1pffeqc8y0dqwwh83m726\",\n \"slug\": \"fec-react-project-standard\",\n \"version\": \"2.7.0\",\n \"publishedAt\": 1781144044267\n}\n\nFile v2.7.0:references/react-performance-patterns.md\n\n# React performance patterns\n\nThis file keeps lightweight React project-standard performance guidance. Use the frontend performance workflow when the task needs metrics, traces, profiles, bundle analysis, network evidence, or a formal performance report.\n\n### 性能（与「性能优化」一节配合）\n\n- **useMemo**：昂贵派生、大列表排序/过滤；注意不可变数据，例如 `useMemo(() => [...list].sort(...), [list])`，避免直接 `sort` 可变原数组。\n- **useCallback**：传给 **`React.memo`** 子组件或作为其他 Hook 依赖的回调，在确有稳定引用需求时使用。\n- **React.memo**：纯展示、props 浅比较可接受的组件；不要全局套 memo。\n- **虚拟列表**：超长列表用 **TanStack Virtual**、**react-window** 等，只渲染视区内节点（路由级与组件级懒加载仍见「Suspense 与懒加载」）。\n\n## 性能优化\n\n在以下场景考虑性能优化：\n\n- 大列表 / 大表格\n- 高频重渲染组件\n- 大量 props 传递的复杂树\n- 重型第三方组件\n- 高频变化 context\n\n### 推荐手段\n\n- 合理使用 `React.memo`\n- 只在必要时使用 `useMemo` / `useCallback`\n- 列表使用稳定 `key`\n- 大列表使用虚拟滚动\n- 路由级做 code splitting\n- 避免将高频变化值放进顶层 context\n- 避免在 render 中无意义创建大量新对象 / 新函数 / 新数组\n- 重型图表、编辑器、地图、3D 和媒体处理能力放到叶子组件或路由级懒加载边界\n- 懒加载组件必须配套 loading、error、empty 或降级 UI，避免只优化包体却破坏用户状态\n\n---\n\nFile v2.7.0:references/react-project-structure.md\n\n# React project structure and component boundaries\n\n## 项目结构（推荐参考）\n\n以下为中大型 React 项目的业界最佳实践结构，按项目实际情况裁剪：\n\n```text\nsrc/\n├── app/ # 应用入口与全局配置\n│ ├── App.tsx # 根组件（Provider 组合）\n│ ├── routes.tsx # 路由配置\n│ └── providers.tsx # 全局 Provider 组装\n│\n├── pages/ # 页面组件（与路由一一对应）\n│ ├── Dashboard/\n│ │ ├── DashboardPage.tsx\n│ │ ├── components/ # 页面私有组件\n│ │ └── hooks/ # 页面私有 hooks\n│ ├── UserList/\n│ └── Settings/\n│\n├── layouts/ # 布局组件\n│ ├── MainLayout.tsx # 主布局（侧边栏 + 顶栏 + 内容区）\n│ ├── AuthLayout.tsx # 登录/注册页布局\n│ └── BlankLayout.tsx # 空白布局（错误页等）\n│\n├── features/ # 功能模块（按业务领域划分）\n│ ├── auth/\n│ │ ├── components/ # 模块组件\n│ │ ├── hooks/ # 模块 hooks\n│ │ ├── api.ts # 模块 API 调用\n│ │ ├── types.ts # 模块类型定义\n│ │ ├── constants.ts # 模块常量\n│ │ └── index.ts # 模块公开导出\n│ └── order/\n│\n├── components/ # 全局共享 UI 组件\n│ ├── Button/\n│ │ ├── Button.tsx\n│ │ ├── Button.styles.css\n│ │ └── __tests__/\n│ ├── Modal/\n│ ├── Form/\n│ └── ErrorBoundary/ # 对 react-error-boundary 等的薄封装（函数组件）\n│\n├── hooks/ # 全局共享 hooks\n│ ├── useAuth.ts\n│ ├── useDebounce.ts\n│ └── useMediaQuery.ts\n│\n├── services/ # API 基础层\n│ ├── request.ts # Axios/fetch 实例与拦截器\n│ └── endpoints/ # API 端点定义（如按领域拆分）\n│\n├── stores/ # 全局状态管理\n│ ├── authStore.ts\n│ └── uiStore.ts\n│\n├── locales/ # 国际化语言包\n│ ├── zh-CN.json # 中文\n│ ├── en-US.json # 英文\n│ └── index.ts # i18n 实例初始化（i18next / react-intl）\n│\n├── assets/ # 静态资源\n│ ├── images/ # 图片（PNG、JPG、WebP）\n│ ├── icons/ # SVG 图标\n│ └── fonts/ # 自定义字体\n│\n├── config/ # 应用配置\n│ ├── env.ts # 环境变量类型化封装\n│ └── features.ts # Feature Flags 管理\n│\n├── types/ # 全局共享类型\n│ ├── api.ts # API 响应/请求通用类型\n│ ├── models.ts # 业务实体类型\n│ └── global.d.ts # 全局类型扩展（图片模块声明等）\n│\n├── utils/ # 纯工具函数\n│ ├── format.ts # 日期、数字、货币格式化\n│ ├── validators.ts # 表单校验规则\n│ └── storage.ts # LocalStorage / SessionStorage 封装\n│\n├── styles/ # 全局样式与主题\n│ ├── global.css # 全局基础样式（reset / normalize）\n│ ├── variables.css # CSS 变量（颜色、间距、字号）\n│ ├── breakpoints.ts # 响应式断点常量\n│ └── themes/ # 主题定义\n│ ├── light.css # 亮色主题变量\n│ ├── dark.css # 暗色主题变量\n│ └── index.ts # 主题切换逻辑\n│\n└── constants/ # 全局常量\n ├── routes.ts # 路由路径常量\n └── config.ts # 业务常量（分页大小、超时时间等）\n```\n\n### 关键原则\n\n- `pages/` 做路由映射和页面编排，不承载大块可复用业务逻辑\n- `layouts/` 负责页面骨架和布局容器，由路由配置引用\n- `features/` 按业务领域划分，模块内尽量自包含\n- `components/` 仅放跨页面、跨模块复用的通用组件\n- `hooks/` 仅放全局通用 hooks；业务 hooks 优先放回对应 feature 或 page\n- `locales/` 存放语言包 JSON 文件，组件中使用 `t('key')` 而非硬编码文案\n- `assets/` 存放静态资源，图标优先使用 SVG，图片优先使用 WebP/AVIF\n- `services/` 负责请求基础设施，不堆叠业务细节\n- `config/` 统一封装环境变量和特性开关，禁止组件中直接读取 `import.meta.env`\n- `styles/` 和主题变量统一管理，避免颜色和尺寸散落在业务代码中\n- 每个模块通过 `index.ts` 管控对外公开 API，避免深层路径导入\n\n---\n\n## 组件与模块分层\n\n推荐分层：\n\n```text\n页面组件 (Pages) → 路由映射、布局组合、页面编排\n └── 容器/编排层 → 数据获取、状态组织、事件编排\n └── 业务组件 → 领域逻辑展示\n └── 通用组件 → 无业务耦合、可跨模块复用\n```\n\n### 什么时候放到 `pages/`\n\n适合放：\n\n- 路由入口组件\n- 页面级布局组合\n- 页面私有的轻量编排逻辑\n\n不适合放：\n\n- 大量领域逻辑\n- 可复用于多个页面的复杂业务块\n- 与某个业务域强绑定的 API / hooks / types\n\n### 什么时候放到 `features/`\n\n适合放：\n\n- 某个业务域的组件、hooks、api、types\n- 可被多个页面共享但带业务语义的逻辑\n- 一个完整业务单元的自包含实现\n\n### 什么时候放到 `components/`\n\n适合放：\n\n- 按钮、弹窗、表单项、表格壳子、空态、错误态等通用 UI\n- 与具体业务无关、可跨模块复用的组件\n\n---\n\n## 组件设计规范\n\n- 使用**函数组件**、Hooks 与 TypeScript；**不要**新增类组件（Error Boundary 用 `react-error-boundary` 等库，见下文）\n- **单文件规模**与拆分原则见 `templates/shared/rules/fec-react.md`「**组件文件规模**」（约 300 行内为佳，逾 500 行或复杂度过高拆子组件、Hooks、utils、类型）\n- 保持组件职责单一、可组合\n- 将可复用逻辑提取到 hooks\n- 在合适场景优先使用受控组件 API\n- props 定义清晰且类型明确\n- 优先复用现有设计系统组件\n- 保持可访问性与键盘交互\n- 避免过深的 JSX 嵌套和重复分支\n- 对可推导的值不要额外存 state\n\n---\n\n\n## 组件目录建议\n\n当组件复杂度较低时，可只保留一个文件。 \n当组件包含样式、子组件、hooks、测试时，推荐使用如下结构：\n\n```text\nComponentName/\n├── ComponentName.tsx\n├── ComponentName.types.ts\n├── ComponentName.styles.css\n├── hooks/\n│ └── useComponentLogic.ts\n├── components/\n│ └── SubComponent.tsx\n└── __tests__/\n └── ComponentName.spec.tsx\n```\n\n说明：\n\n- 类型复杂时再拆 `ComponentName.types.ts`\n- 存在局部逻辑复用时再拆 `hooks/`\n- 子组件仅在当前组件内部使用时，放到当前目录 `components/`\n- 测试是否就近放置，应遵循仓库现有约定\n\n---\n\nFile v2.7.0:references/react-quality-patterns.md\n\n# React quality patterns\n\n## 样式接入\n\n本 skill 不强制具体样式方案，默认遵循仓库现状。\n\n适配时注意：\n\n- Tailwind 项目继续使用 Tailwind\n- CSS Modules 项目保持命名与文件组织一致\n- styled-components 项目继续沿用其模式\n- 主题、颜色、字号、间距等优先复用仓库 token / CSS 变量\n- 避免在组件内硬编码大量视觉常量\n- 禁止内联样式（除动态值外）\n- 响应式处理需与项目断点约定一致\n\n---\n\n## 注释规范\n\n- **优先使用中文**：解释「为什么这样做」、业务约束、边界情况、非显而易见的权衡时，优先用中文撰写注释，便于团队与业务方阅读。\n- **与代码语言一致时的例外**：对接第三方协议字段名、HTTP 头、规范中的英文术语时，注释里可保留英文专有名词，必要时中英文并列说明。\n- **少而精**：能通过清晰命名与类型表达清楚的逻辑不写废话注释；复杂分支、临时兼容、性能取舍必须写清意图。\n- **公开 API**：模块或 hooks 的对外契约可用 JSDoc（`@param` / `@returns` / `@example`），说明用中文即可，除非仓库统一要求英文。\n\n---\n\n## TypeScript 规范\n\n通用 TypeScript 工程规则由 `fec-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。\n\nReact 规范只补充组件、Props、事件和 TSX 泛型写法；复杂类型建模或跨框架类型契约先分流到 `fec-typescript-project-standard`。\n\n### React 项目补充约定\n\n- Props interface 命名: `ComponentNameProps`\n- 事件处理函数: `handle` 前缀（如 `handleClick`）\n- 回调 Props: `on` 前缀（如 `onChange`、`onSubmit`）\n- 组件优先写显式 props 与返回值类型（`JSX.Element` / `React.ReactElement`），避免依赖 `React.FC` 的隐式 `children` 等行为差异\n- 泛型组件使用 `` 约束，保持调用处类型推导；回调与事件类型优先使用 DOM / React 自带类型（如 `React.ChangeEvent`）\n\n```tsx\ninterface TableProps> {\n data: T[];\n columns: ColumnDef[];\n onRowClick?: (row: T) => void;\n}\n```\n\n---\n\n## 测试规范\n\n### 应优先覆盖的内容\n\n- 核心交互行为（点击、输入、提交）\n- 条件渲染（loading / error / empty / data）\n- 关键 hooks 的返回值和副作用\n- API 调用 mock 与模块级集成测试\n\n### 推荐风格\n\n- 测试用户行为，而不是实现细节\n- 优先使用 `screen.getByRole`、`getByLabelText`\n- 避免围绕内部 state 写脆弱测试\n- 只测关键行为，不机械追求覆盖率数字\n\n### 示例\n\n```tsx\ndescribe(\"UserForm\", () => {\n it(\"should submit with valid data\", async () => {\n const onSubmit = vi.fn();\n render();\n\n await userEvent.type(screen.getByLabelText(\"用户名\"), \"test\");\n await userEvent.click(screen.getByRole(\"button\", { name: \"提交\" }));\n\n expect(onSubmit).toHaveBeenCalledWith({ username: \"test\" });\n });\n\n it(\"should show error on invalid input\", async () => {\n render();\n await userEvent.click(screen.getByRole(\"button\", { name: \"提交\" }));\n expect(screen.getByText(\"用户名不能为空\")).toBeInTheDocument();\n });\n});\n```\n\n---\n\n\n## 常见反模式\n\n避免：\n\n- prop drilling 过深却不考虑组合或局部封装\n- 对局部问题过度使用 context\n- 把数据请求、视图渲染、命令式 DOM 操作全塞进一个文件\n- 在 useEffect 中做可以在事件处理函数中完成的事\n- 用 `useEffect + setState` 模拟本可直接计算的派生值\n- 将所有状态都推进全局 store\n- 在 `components/` 中放业务耦合组件\n- 直接绕过模块出口，从 feature 深层路径导入\n- 没有明显收益却提前做复杂优化\n- **新增类组件**或手写类式 Error Boundary（应函数组件 + `react-error-boundary` 等）\n\n---\n\n## 输出检查清单\n\n输出 React 代码或方案时，至少检查：\n\n- [ ] 是否先对齐了仓库现有约定\n- [ ] 页面 / feature / 通用组件边界是否清晰\n- [ ] 目录结构是否与模块复杂度匹配\n- [ ] Props 类型完整且明确\n- [ ] 解释性注释是否优先使用中文且点到要害\n- [ ] 可复用逻辑是否已提取为 hooks\n- [ ] loading / error / empty / data 状态是否齐全\n- [ ] API 层是否具备类型约束和统一错误处理\n- [ ] 复杂 DTO、外部数据收窄、公共类型或 `tsconfig` 问题是否已分流到 `fec-typescript-project-standard`\n- [ ] 状态管理是否符合就近原则\n- [ ] 路由级或重型模块是否考虑懒加载\n- [ ] 样式方案是否与仓库保持一致\n- [ ] 关键行为是否有测试覆盖\n- [ ] 关键模块已用 **`react-error-boundary`**（等）包裹，且未手写类组件式 Boundary\n- [ ] 超长列表是否评估虚拟化；弹窗/复合组件是否具备键盘与焦点约定\n- [ ] 是否引入了不必要的新依赖或新范式\n\n---\n\nFile v2.7.0:references/react-runtime-patterns.md\n\n# React runtime patterns\n\n## 常用 UI 与状态模式\n\n以下模式可与本 skill 其他章节（Hooks、状态管理、性能优化、错误处理）对照使用；**按业务复杂度与团队熟悉度选用**，避免为模式而模式。思路参考业界常见的 React 前端模式实践（如组件组合、复合组件、性能与无障碍等）。\n\n### 组合优于继承\n\n- 用**小颗粒子组件** + `children` / 显式 props 拼装界面，而不是在 React 中搭建类继承层次。\n- 示例：`Card` + `CardHeader` + `CardBody`，由使用方组合，而不是一个巨型 `Card` 用大量布尔 props 分支。\n\n### 复合组件（Compound Components）\n\n- 根组件通过 **Context** 向子组件提供内部状态（如当前 Tab、打开/关闭）。\n- 子组件在 `useContext` 为空时**抛错或断言**，明确「必须在 Provider 树内使用」。\n- API 表面保持可读：``。\n\n### Render Props / 函数子\n\n- 适用：封装**数据获取与三态**（loading / error / data），把**渲染决策**交给父级。\n- 与 **自定义 Hook** 二选一即可：多数场景 `useXxx()` + 普通组件更直观；仅在需要强约束「同层渲染逻辑」时保留 Render Props。\n\n### Context + useReducer\n\n- 适合**中等复杂度、多子树共享**的客户端状态，且更新可归约为明确 `action`。\n- 避免把高频变化的大对象塞进顶层 Context；服务端数据仍优先 **React Query / SWR**。\n- 大型全局业务状态继续用仓库已选的 **Zustand / Redux Toolkit / Jotai**。\n\n### 表单\n\n- 受控字段 + 校验错误对象是一类可行实现；中大型表单优先 **React Hook Form**（或 Formik）+ **Zod**，复杂表单值、DTO 和校验类型契约分流到 `fec-typescript-project-standard`。\n- 避免单组件内巨型 `useState` 表单对象与重复校验逻辑，可拆字段子组件或抽 `useFormSchema`。\n\n### Error Boundary\n\n- **不要**在业务代码中手写 React **类组件**形式的 Error Boundary；统一使用 **`react-error-boundary`**（或团队认可的同类库）在**模块边界**兜底渲染失败（与本章「错误处理」、`error-handling.md` 一致）。\n- 用 `FallbackComponent` 与 `resetErrorBoundary` 提供「重试」；**日志上报**放在库的 **`onError`**（等回调）中，生产代码避免长期依赖 `console.log`（见 TypeScript 规则）。\n\n\n### 动画与过渡\n\n- 列表进出场可用 **Framer Motion** 的 `AnimatePresence` + `key`，或 CSS `transition`；注意减少布局抖动与 `prefers-reduced-motion`（与无障碍策略一致时）。\n\n### 无障碍与焦点\n\n- 自定义下拉、标签页等：**`role` / `aria-*`**、**方向键 / Enter / Escape** 行为与焦点环可见。\n- 弹窗：打开时将焦点移入对话框，关闭时**恢复**触发元素焦点；可用 **`focus-trap-react`** 或类似方案，与 `fec-accessibility-check` skill 互补。\n\n### Next.js 与服务端组件\n\n- **App Router、Server Components、服务端数据获取与缓存**见 **`fec-nextjs-project-standard`**；客户端交互模式仍以本章与 Hooks 规范为准。\n\n---\n\n\n## Hooks 设计模式\n\n### 适合抽为自定义 Hook 的场景\n\n- 数据获取与三态管理\n- 表单状态逻辑\n- 分页、筛选、排序编排\n- 事件监听与副作用清理\n- 可在多个组件复用的交互逻辑\n\n### 推荐原则\n\n- 统一使用 `use` 前缀命名\n- 返回对象而非数组，方便按需解构，增强可读性和扩展性\n- 状态和行为封装在一起\n- Hook 内部处理 `loading / error / data`\n- 对外暴露清晰的最小接口，不泄漏无关内部细节\n\n### 示例\n\n```tsx\nfunction useUserList(params: QueryParams) {\n const [data, setData] = useState([]);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n\n const fetch = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const res = await getUserList(params);\n setData(res.list);\n } catch (e) {\n setError(e as Error);\n } finally {\n setLoading(false);\n }\n }, [params]);\n\n useEffect(() => {\n fetch();\n }, [fetch]);\n\n return { data, loading, error, refetch: fetch };\n}\n```\n\n### Hook 使用原则\n\n- `useEffect` 必须有正确依赖和清理逻辑\n- `useMemo` / `useCallback` 不要滥用，只有在稳定引用确实重要时再加\n- 不在条件分支或循环中调用 hooks\n- 已引入 React Query / SWR 时，数据请求优先走这些库，而不是自己重复造一套缓存层\n\n---\n\n## 路由组织\n\n### 推荐方式\n\n- 路由配置集中管理\n- 路径常量化\n- 页面组件按需懒加载\n- 权限控制放在 guard 层，而不是散落在页面组件内\n- 分页、筛选、排序等 URL 驱动状态优先与地址栏同步\n\n### 示例\n\n```tsx\nconst routes: RouteObject[] = [\n {\n path: \"/\",\n element: ,\n children: [\n { index: true, element: },\n { path: \"users\", element: },\n { path: \"users/:id\", element: },\n { path: \"settings\", element: },\n ],\n },\n { path: \"/login\", element: },\n { path: \"*\", element: },\n];\n```\n\n```tsx\nconst UserListPage = lazy(() => import(\"@/pages/UserList/UserListPage\"));\n\nfunction ProtectedRoute({ children }: { children: React.ReactNode }) {\n const { isAuthenticated } = useAuth();\n if (!isAuthenticated) return ;\n return <>{children};\n}\n```\n\n---\n\n## 状态管理选型\n\n| 状态类型 | 推荐方案 |\n| ------------------ | ------------------------------------------------- |\n| 组件内临时 UI 状态 | `useState` / `useReducer` |\n| 跨组件共享业务状态 | Zustand / Redux Toolkit / Jotai（按仓库实际选择） |\n| 服务端数据缓存 | React Query / SWR |\n| URL 驱动状态 | 路由参数 / `useSearchParams` |\n| 表单状态 | React Hook Form / Formik |\n\n### 核心原则\n\n- 就近管理：状态尽量放在最近的公共祖先\n- 单一数据源：同一份数据不要维护多份\n- 派生优于同步：可计算值优先在渲染期计算\n- 服务端数据优先交给请求库管理，不手动塞进全局 store\n- 不要因为“以后可能会用到”就把局部状态提前升级为全局状态\n\n---\n\n## API 层规范\n\n### 设计原则\n\n- 请求基础设施集中在 `services/`\n- 业务 API 按 feature 拆分，而不是全部堆在一个文件\n- 请求参数和响应结果都应有明确类型\n- 认证、错误格式化、通用拦截放在请求层统一处理\n- 页面和组件不要直接散落拼接请求细节\n\n### 示例\n\n```ts\n// services/request.ts\nconst request = axios.create({\n baseURL: import.meta.env.VITE_API_BASE_URL,\n timeout: 10000,\n});\n\nrequest.interceptors.response.use(\n (res) => res.data,\n (error) => {\n if (error.response?.status === 401) {\n redirectToLogin();\n }\n return Promise.reject(normalizeError(error));\n },\n);\n```\n\n```ts\n// features/user/api.ts\nexport function getUserList(\n params: UserQueryParams,\n): Promise> {\n return request.get(\"/users\", { params });\n}\n\nexport function updateUser(id: string, data: UpdateUserDTO): Promise {\n return request.put(`/users/${id}`, data);\n}\n```\n\n---\n\n## 错误处理\n\n### 必须覆盖的状态\n\n- Loading\n- Error\n- Empty\n- Data\n\n### 推荐做法\n\n- 关键功能模块使用 Error Boundary 包裹，避免局部异常导致全页白屏\n- 异步请求失败时必须给用户可见反馈\n- 重要操作提供重试能力\n- 不要吞错，不写空 `catch`\n\n### 示例（`react-error-boundary`，函数式 Fallback）\n\n```tsx\nimport { ErrorBoundary } from \"react-error-boundary\";\n\nfunction ModuleErrorFallback({\n resetErrorBoundary,\n}: {\n resetErrorBoundary: () => void;\n}) {\n return (\n
\n 模块加载失败\n \n
\n );\n}\n\nexport function UserDashboardSection() {\n return (\n \n \n \n );\n}\n```\n\n---\n\n## Suspense 与懒加载\n\n适用场景：\n\n- 路由级页面\n- 图表、富文本编辑器、地图、重型表格等大体积组件\n- 初始化成本较高的模块\n\n示例：\n\n```tsx\nconst HeavyChart = lazy(() => import(\"./components/HeavyChart\"));\n\nfunction Dashboard() {\n return (\n }>\n \n \n );\n}\n```\n\n建议：\n\n- 路由级优先 `lazy + Suspense`\n- `fallback` 优先使用 Skeleton 或更贴近内容的占位态，而不是纯 spinner\n\n---\n\nFile v2.7.0:skill-card.md\n\n## Description:\n\nProvides React + TypeScript project architecture guidance for project structure, feature and module boundaries, component design, hooks organization, routing composition, state, API, error handling, styling defaults, and repository-wide conventions.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[bovinphang](https://clawhub.ai/user/bovinphang)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineering teams use this skill to design or review React + TypeScript project structure, component boundaries, hooks, routing, state ownership, API integration, error states, styling conventions, and lightweight performance risks.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Chinese-oriented React and TypeScript conventions may conflict with teams that standardize on English or another commenting style.\n\nMitigation: Review the language and commenting preferences before team adoption and adapt examples to local standards.\n\nRisk: Architecture guidance may be applied too broadly without checking an existing repository's conventions.\n\nMitigation: Compare recommendations against the current project structure, state management, styling, API, and testing patterns before changing code.\n\n## Reference(s):\n\n- [React Project Standard on ClawHub](https://clawhub.ai/bovinphang/skills/fec-react-project-standard)\n- [React performance patterns](references/react-performance-patterns.md)\n- [React project structure and component boundaries](references/react-project-structure.md)\n- [React quality patterns](references/react-quality-patterns.md)\n- [React runtime patterns](references/react-runtime-patterns.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Code, Configuration]\n\n**Output Format:** [Markdown with file-structure examples, React and TypeScript code snippets, checklists, and command suggestions when dependencies or validation steps are needed]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include architecture rationale, migration notes, testing entry points, error/loading/empty state expectations, and lightweight performance risk checks.]\n\n## Skill Version(s):\n\n2.7.0 (source: server release evidence and package.json)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.7.0:metadata.json\n\n{\n \"id\": \"fec-react-project-standard\",\n \"name\": \"React 项目规范\",\n \"category\": \"project-standard\",\n \"tags\": [\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"summary\": \"Frontend Craft skill for React 项目规范.\",\n \"version\": \"2.7.0\",\n \"license\": \"MIT\",\n \"homepage\": \"https://github.com/bovinphang/frontend-craft\",\n \"repository\": \"https://github.com/bovinphang/frontend-craft\",\n \"keywords\": [\n \"project-standard\",\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"platforms\": [\n \"skills-cli\",\n \"skillreg\",\n \"claude-code\",\n \"codex\",\n \"cursor\",\n \"opencode\",\n \"openclaw\",\n \"generic-skill-runtime\"\n ],\n \"description\": \"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\",\n \"source\": \"skills/fec-react-project-standard\",\n \"references\": [\n \"references/react-performance-patterns.md\",\n \"references/react-project-structure.md\",\n \"references/react-quality-patterns.md\",\n \"references/react-runtime-patterns.md\"\n ],\n \"relations\": {\n \"relatedSkills\": [\n \"fec-typescript-project-standard\",\n \"fec-state-management\",\n \"fec-tailwind-design-system\",\n \"fec-responsive-layout\",\n \"fec-form-handling\",\n \"fec-data-fetching\",\n \"fec-component-testing\",\n \"fec-e2e-testing\",\n \"fec-accessibility-check\",\n \"fec-security-review\",\n \"fec-list-virtualization\",\n \"fec-svg-animation\",\n \"fec-canvas-threejs\",\n \"fec-api-integration\",\n \"fec-motion-interaction\"\n ],\n \"boundaryWorkflows\": [\n \"Use specialty workflows for complex forms, state ownership, TypeScript contracts, server state, tests, accessibility, security, large lists, animation, or graphics.\",\n \"Keep generic React component architecture and hooks organization in the React project workflow.\"\n ],\n \"capabilityTags\": [\n \"react\",\n \"project-standard\",\n \"fec-architecture\"\n ]\n }\n}\n\nFile v2.7.0:package.json\n\n{\n \"name\": \"@bovinphang/fec-react-project-standard\",\n \"version\": \"2.7.0\",\n \"description\": \"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\",\n \"type\": \"module\",\n \"license\": \"MIT\",\n \"author\": {\n \"name\": \"Bovin Phang\",\n \"email\": \"pengbaowen@msn.com\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/bovinphang/frontend-craft\",\n \"directory\": \"skills/fec-react-project-standard\"\n },\n \"homepage\": \"https://github.com/bovinphang/frontend-craft\",\n \"keywords\": [\n \"agent-skill\",\n \"frontend-craft\",\n \"project-standard\",\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"files\": [\n \"SKILL.md\",\n \"references\",\n \"scripts\",\n \"data\",\n \"assets\",\n \"metadata.json\",\n \"README.md\",\n \"LICENSE\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n }\n}\n\nArchive v2.4.0: 7 files, 16593 bytes\n\nFiles: metadata.json (2190b), package.json (1205b), README.md (1594b), references/react-project-details.md (22690b), skill-card.md (2402b), SKILL.md (4410b), _meta.json (145b)\n\nFile v2.4.0:SKILL.md\n\n---\nname: fec-react-project-standard\ndescription: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\n---\n\n# React 项目规范\n\n适用于 React + TypeScript 仓库中的中大型模块建设、页面重构和工程结构设计。\n\n## Purpose\n\n为 React + TypeScript 项目提供工程结构、模块边界和默认实现约定，确保架构清晰、代码可维护。\n\n## Procedure\n\n本 skill 主要解决 React 工程任务“如何设计和落地”的问题，不重复声明基础编码底线。处理 React 工程化任务时，按以下顺序执行：\n\n1. 识别仓库已有约定\n - 目录组织方式\n - 样式体系\n - 状态管理方案\n - 请求封装方式\n - 测试框架\n - UI 组件库 / 设计系统\n\n2. 判断目标属于哪一层\n - 路由页面\n - 页面私有组件\n - feature 业务模块\n - 全局通用组件\n - hooks / services / stores / utils\n\n3. 设计边界后再落代码\n - 哪些逻辑属于页面编排\n - 哪些逻辑属于 feature\n - 哪些逻辑应下沉为通用能力\n - 哪些状态应本地管理，哪些应交给 store / query / URL\n - 状态归属复杂时使用状态管理流程先做状态清单\n - DTO、公共 props 或泛型组件复杂时使用 TypeScript 类型安全流程先收敛类型契约\n\n4. 输出时补齐关键质量项\n - loading / error / empty / data 状态\n - 错误处理与重试\n - 类型约束\n - 关键测试入口\n - 必要的专项 skill 分流\n - 依赖是否已存在于 `package.json`，缺失时先给安装命令再使用\n - 重型 UI 能力（动效、图表、3D、编辑器、地图）是否隔离为 leaf component 并按需加载\n - 图片、视频、字体等资源是否本地化、可缓存，并避免占位 URL 进入交付\n - 页面级 Error Boundary、模块级 fallback、API 错误映射和用户可恢复动作是否一致\n - Tailwind token/variant 或响应式布局需求是否应分流到对应专项 skill\n\n## Detailed References\n\n需要具体 React 项目结构、组件模式、Hooks、路由、状态归属、API 层形状、错误处理、样式默认值、TypeScript 约定或审查清单时，加载 [references/react-project-details.md](references/react-project-details.md)。\n\n## Constraints\n\n- 默认遵守仓库现有全局规则和 React rule\n- 若仓库已有明确目录结构、样式体系、状态管理或请求封装，优先沿用仓库约定\n- 组件文件规模宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分子组件、Hooks、utils、类型\n- 禁止新增类组件（Error Boundary 用 `react-error-boundary` 等库）\n- 禁止绕过模块出口，从 feature 深层路径导入\n- 不要用 `useEffect + setState` 模拟本可直接计算的派生值\n- 避免 prop drilling 过深却不考虑组合或局部封装\n- 不在通用页面组件里同步引入 GSAP、Three.js、Lottie、富文本编辑器或地图 SDK；需要时用动态导入、路由级分包或叶子组件隔离。\n- 不在 React 组件中散落裸 `fetch`、API URL、token refresh 或上传流程；跨边界请求应收敛到 API 集成层。\n- 不用 Error Boundary 处理普通 API 失败；请求错误应优先落到 loading/error/empty/data 状态和可恢复操作。\n\n## Expected Output\n\n- 组件边界清晰，pages/features/components 分层明确\n- Props 类型完整且明确，无 `any` 滥用\n- 可复用逻辑已提取为 hooks，loading/error/empty/data 状态齐全\n- API 层具备类型约束和统一错误处理，状态管理符合就近原则\n- URL 状态、服务端状态、表单状态和全局客户端状态边界明确\n- 关键行为有测试覆盖，关键模块已用 `react-error-boundary` 包裹\n- 超长列表已评估虚拟化，弹窗/复合组件具备键盘与焦点支持\n- 先尊重仓库现状，再给推荐结构\n- 给出必要的文件划分建议\n- 必要时说明为什么这样分层\n- 对新增模块，优先输出最小可落地结构，而不是一次性过度设计\n- 对重构任务，优先保证可迁移性和风险可控\n\nFile v2.4.0:README.md\n\n# React 项目规范\n\nFrontend Craft skill for React 项目规范.\n\n## Skill\n\n- ID: `fec-react-project-standard`\n- Category: `project-standard`\n- Version: `2.4.0`\n- Source: `skills/fec-react-project-standard/SKILL.md`\n\n## Description\n\nUse when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\n\n## Usage\n\nInstall or import this package with any skill runtime that understands the standard `SKILL.md` layout. The canonical source remains the Frontend Craft repository.\n\n## Packaged Files\n\n- [references/react-project-details.md](references/react-project-details.md)\n\n## Optional Related Packages\n\n- `@frontend-craft/fec-typescript-type-safety`\n- `@frontend-craft/fec-state-management`\n- `@frontend-craft/fec-tailwind-design-system`\n- `@frontend-craft/fec-responsive-layout`\n- `@frontend-craft/fec-form-handling`\n- `@frontend-craft/fec-data-fetching`\n- `@frontend-craft/fec-component-testing`\n- `@frontend-craft/fec-e2e-testing`\n- `@frontend-craft/fec-accessibility-check`\n- `@frontend-craft/fec-security-review`\n- `@frontend-craft/fec-list-virtualization`\n- `@frontend-craft/fec-svg-animation`\n- `@frontend-craft/fec-canvas-threejs`\n- `@frontend-craft/fec-api-integration`\n- `@frontend-craft/fec-motion-interaction`\n\n## License\n\nMIT\n\nFile v2.4.0:_meta.json\n\n{\n \"ownerId\": \"kn7b0nh7hvj1pffeqc8y0dqwwh83m726\",\n \"slug\": \"fec-react-project-standard\",\n \"version\": \"2.4.0\",\n \"publishedAt\": 1780307651302\n}\n\nFile v2.4.0:references/react-project-details.md\n\n# React 项目规范详解\n\n## 项目结构（推荐参考）\n\n以下为中大型 React 项目的业界最佳实践结构，按项目实际情况裁剪：\n\n```text\nsrc/\n├── app/ # 应用入口与全局配置\n│ ├── App.tsx # 根组件（Provider 组合）\n│ ├── routes.tsx # 路由配置\n│ └── providers.tsx # 全局 Provider 组装\n│\n├── pages/ # 页面组件（与路由一一对应）\n│ ├── Dashboard/\n│ │ ├── DashboardPage.tsx\n│ │ ├── components/ # 页面私有组件\n│ │ └── hooks/ # 页面私有 hooks\n│ ├── UserList/\n│ └── Settings/\n│\n├── layouts/ # 布局组件\n│ ├── MainLayout.tsx # 主布局（侧边栏 + 顶栏 + 内容区）\n│ ├── AuthLayout.tsx # 登录/注册页布局\n│ └── BlankLayout.tsx # 空白布局（错误页等）\n│\n├── features/ # 功能模块（按业务领域划分）\n│ ├── auth/\n│ │ ├── components/ # 模块组件\n│ │ ├── hooks/ # 模块 hooks\n│ │ ├── api.ts # 模块 API 调用\n│ │ ├── types.ts # 模块类型定义\n│ │ ├── constants.ts # 模块常量\n│ │ └── index.ts # 模块公开导出\n│ └── order/\n│\n├── components/ # 全局共享 UI 组件\n│ ├── Button/\n│ │ ├── Button.tsx\n│ │ ├── Button.styles.css\n│ │ └── __tests__/\n│ ├── Modal/\n│ ├── Form/\n│ └── ErrorBoundary/ # 对 react-error-boundary 等的薄封装（函数组件）\n│\n├── hooks/ # 全局共享 hooks\n│ ├── useAuth.ts\n│ ├── useDebounce.ts\n│ └── useMediaQuery.ts\n│\n├── services/ # API 基础层\n│ ├── request.ts # Axios/fetch 实例与拦截器\n│ └── endpoints/ # API 端点定义（如按领域拆分）\n│\n├── stores/ # 全局状态管理\n│ ├── authStore.ts\n│ └── uiStore.ts\n│\n├── locales/ # 国际化语言包\n│ ├── zh-CN.json # 中文\n│ ├── en-US.json # 英文\n│ └── index.ts # i18n 实例初始化（i18next / react-intl）\n│\n├── assets/ # 静态资源\n│ ├── images/ # 图片（PNG、JPG、WebP）\n│ ├── icons/ # SVG 图标\n│ └── fonts/ # 自定义字体\n│\n├── config/ # 应用配置\n│ ├── env.ts # 环境变量类型化封装\n│ └── features.ts # Feature Flags 管理\n│\n├── types/ # 全局共享类型\n│ ├── api.ts # API 响应/请求通用类型\n│ ├── models.ts # 业务实体类型\n│ └── global.d.ts # 全局类型扩展（图片模块声明等）\n│\n├── utils/ # 纯工具函数\n│ ├── format.ts # 日期、数字、货币格式化\n│ ├── validators.ts # 表单校验规则\n│ └── storage.ts # LocalStorage / SessionStorage 封装\n│\n├── styles/ # 全局样式与主题\n│ ├── global.css # 全局基础样式（reset / normalize）\n│ ├── variables.css # CSS 变量（颜色、间距、字号）\n│ ├── breakpoints.ts # 响应式断点常量\n│ └── themes/ # 主题定义\n│ ├── light.css # 亮色主题变量\n│ ├── dark.css # 暗色主题变量\n│ └── index.ts # 主题切换逻辑\n│\n└── constants/ # 全局常量\n ├── routes.ts # 路由路径常量\n └── config.ts # 业务常量（分页大小、超时时间等）\n```\n\n### 关键原则\n\n- `pages/` 做路由映射和页面编排，不承载大块可复用业务逻辑\n- `layouts/` 负责页面骨架和布局容器，由路由配置引用\n- `features/` 按业务领域划分，模块内尽量自包含\n- `components/` 仅放跨页面、跨模块复用的通用组件\n- `hooks/` 仅放全局通用 hooks；业务 hooks 优先放回对应 feature 或 page\n- `locales/` 存放语言包 JSON 文件，组件中使用 `t('key')` 而非硬编码文案\n- `assets/` 存放静态资源，图标优先使用 SVG，图片优先使用 WebP/AVIF\n- `services/` 负责请求基础设施，不堆叠业务细节\n- `config/` 统一封装环境变量和特性开关，禁止组件中直接读取 `import.meta.env`\n- `styles/` 和主题变量统一管理，避免颜色和尺寸散落在业务代码中\n- 每个模块通过 `index.ts` 管控对外公开 API，避免深层路径导入\n\n---\n\n## 组件与模块分层\n\n推荐分层：\n\n```text\n页面组件 (Pages) → 路由映射、布局组合、页面编排\n └── 容器/编排层 → 数据获取、状态组织、事件编排\n └── 业务组件 → 领域逻辑展示\n └── 通用组件 → 无业务耦合、可跨模块复用\n```\n\n### 什么时候放到 `pages/`\n\n适合放：\n\n- 路由入口组件\n- 页面级布局组合\n- 页面私有的轻量编排逻辑\n\n不适合放：\n\n- 大量领域逻辑\n- 可复用于多个页面的复杂业务块\n- 与某个业务域强绑定的 API / hooks / types\n\n### 什么时候放到 `features/`\n\n适合放：\n\n- 某个业务域的组件、hooks、api、types\n- 可被多个页面共享但带业务语义的逻辑\n- 一个完整业务单元的自包含实现\n\n### 什么时候放到 `components/`\n\n适合放：\n\n- 按钮、弹窗、表单项、表格壳子、空态、错误态等通用 UI\n- 与具体业务无关、可跨模块复用的组件\n\n---\n\n## 组件设计规范\n\n- 使用**函数组件**、Hooks 与 TypeScript；**不要**新增类组件（Error Boundary 用 `react-error-boundary` 等库，见下文）\n- **单文件规模**与拆分原则见 `templates/shared/rules/fec-react.md`「**组件文件规模**」（约 300 行内为佳，逾 500 行或复杂度过高拆子组件、Hooks、utils、类型）\n- 保持组件职责单一、可组合\n- 将可复用逻辑提取到 hooks\n- 在合适场景优先使用受控组件 API\n- props 定义清晰且类型明确\n- 优先复用现有设计系统组件\n- 保持可访问性与键盘交互\n- 避免过深的 JSX 嵌套和重复分支\n- 对可推导的值不要额外存 state\n\n---\n\n## 常用 UI 与状态模式\n\n以下模式可与本 skill 其他章节（Hooks、状态管理、性能优化、错误处理）对照使用；**按业务复杂度与团队熟悉度选用**，避免为模式而模式。思路参考业界常见的 React 前端模式实践（如组件组合、复合组件、性能与无障碍等）。\n\n### 组合优于继承\n\n- 用**小颗粒子组件** + `children` / 显式 props 拼装界面，而不是在 React 中搭建类继承层次。\n- 示例：`Card` + `CardHeader` + `CardBody`，由使用方组合，而不是一个巨型 `Card` 用大量布尔 props 分支。\n\n### 复合组件（Compound Components）\n\n- 根组件通过 **Context** 向子组件提供内部状态（如当前 Tab、打开/关闭）。\n- 子组件在 `useContext` 为空时**抛错或断言**，明确「必须在 Provider 树内使用」。\n- API 表面保持可读：``。\n\n### Render Props / 函数子\n\n- 适用：封装**数据获取与三态**（loading / error / data），把**渲染决策**交给父级。\n- 与 **自定义 Hook** 二选一即可：多数场景 `useXxx()` + 普通组件更直观；仅在需要强约束「同层渲染逻辑」时保留 Render Props。\n\n### Context + useReducer\n\n- 适合**中等复杂度、多子树共享**的客户端状态，且更新可归约为明确 `action`。\n- 避免把高频变化的大对象塞进顶层 Context；服务端数据仍优先 **React Query / SWR**。\n- 大型全局业务状态继续用仓库已选的 **Zustand / Redux Toolkit / Jotai**。\n\n### 表单\n\n- 受控字段 + 校验错误对象是一类可行实现；中大型表单优先 **React Hook Form**（或 Formik）+ **Zod**（类型与校验与 `templates/shared/rules/fec-typescript.md` 一致）。\n- 避免单组件内巨型 `useState` 表单对象与重复校验逻辑，可拆字段子组件或抽 `useFormSchema`。\n\n### Error Boundary\n\n- **不要**在业务代码中手写 React **类组件**形式的 Error Boundary；统一使用 **`react-error-boundary`**（或团队认可的同类库）在**模块边界**兜底渲染失败（与本章「错误处理」、`error-handling.md` 一致）。\n- 用 `FallbackComponent` 与 `resetErrorBoundary` 提供「重试」；**日志上报**放在库的 **`onError`**（等回调）中，生产代码避免长期依赖 `console.log`（见 TypeScript 规则）。\n\n### 性能（与「性能优化」一节配合）\n\n- **useMemo**：昂贵派生、大列表排序/过滤；注意不可变数据，例如 `useMemo(() => [...list].sort(...), [list])`，避免直接 `sort` 可变原数组。\n- **useCallback**：传给 **`React.memo`** 子组件或作为其他 Hook 依赖的回调，在确有稳定引用需求时使用。\n- **React.memo**：纯展示、props 浅比较可接受的组件；不要全局套 memo。\n- **虚拟列表**：超长列表用 **TanStack Virtual**、**react-window** 等，只渲染视区内节点（路由级与组件级懒加载仍见「Suspense 与懒加载」）。\n\n### 动画与过渡\n\n- 列表进出场可用 **Framer Motion** 的 `AnimatePresence` + `key`，或 CSS `transition`；注意减少布局抖动与 `prefers-reduced-motion`（与无障碍策略一致时）。\n\n### 无障碍与焦点\n\n- 自定义下拉、标签页等：**`role` / `aria-*`**、**方向键 / Enter / Escape** 行为与焦点环可见。\n- 弹窗：打开时将焦点移入对话框，关闭时**恢复**触发元素焦点；可用 **`focus-trap-react`** 或类似方案，与 `fec-accessibility-check` skill 互补。\n\n### Next.js 与服务端组件\n\n- **App Router、Server Components、服务端数据获取与缓存**见 **`fec-nextjs-project-standard`**；客户端交互模式仍以本章与 Hooks 规范为准。\n\n---\n\n## 组件目录建议\n\n当组件复杂度较低时，可只保留一个文件。 \n当组件包含样式、子组件、hooks、测试时，推荐使用如下结构：\n\n```text\nComponentName/\n├── ComponentName.tsx\n├── ComponentName.types.ts\n├── ComponentName.styles.css\n├── hooks/\n│ └── useComponentLogic.ts\n├── components/\n│ └── SubComponent.tsx\n└── __tests__/\n └── ComponentName.spec.tsx\n```\n\n说明：\n\n- 类型复杂时再拆 `ComponentName.types.ts`\n- 存在局部逻辑复用时再拆 `hooks/`\n- 子组件仅在当前组件内部使用时，放到当前目录 `components/`\n- 测试是否就近放置，应遵循仓库现有约定\n\n---\n\n## Hooks 设计模式\n\n### 适合抽为自定义 Hook 的场景\n\n- 数据获取与三态管理\n- 表单状态逻辑\n- 分页、筛选、排序编排\n- 事件监听与副作用清理\n- 可在多个组件复用的交互逻辑\n\n### 推荐原则\n\n- 统一使用 `use` 前缀命名\n- 返回对象而非数组，方便按需解构，增强可读性和扩展性\n- 状态和行为封装在一起\n- Hook 内部处理 `loading / error / data`\n- 对外暴露清晰的最小接口，不泄漏无关内部细节\n\n### 示例\n\n```tsx\nfunction useUserList(params: QueryParams) {\n const [data, setData] = useState([]);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n\n const fetch = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const res = await getUserList(params);\n setData(res.list);\n } catch (e) {\n setError(e as Error);\n } finally {\n setLoading(false);\n }\n }, [params]);\n\n useEffect(() => {\n fetch();\n }, [fetch]);\n\n return { data, loading, error, refetch: fetch };\n}\n```\n\n### Hook 使用原则\n\n- `useEffect` 必须有正确依赖和清理逻辑\n- `useMemo` / `useCallback` 不要滥用，只有在稳定引用确实重要时再加\n- 不在条件分支或循环中调用 hooks\n- 已引入 React Query / SWR 时，数据请求优先走这些库，而不是自己重复造一套缓存层\n\n---\n\n## 路由组织\n\n### 推荐方式\n\n- 路由配置集中管理\n- 路径常量化\n- 页面组件按需懒加载\n- 权限控制放在 guard 层，而不是散落在页面组件内\n- 分页、筛选、排序等 URL 驱动状态优先与地址栏同步\n\n### 示例\n\n```tsx\nconst routes: RouteObject[] = [\n {\n path: \"/\",\n element: ,\n children: [\n { index: true, element: },\n { path: \"users\", element: },\n { path: \"users/:id\", element: },\n { path: \"settings\", element: },\n ],\n },\n { path: \"/login\", element: },\n { path: \"*\", element: },\n];\n```\n\n```tsx\nconst UserListPage = lazy(() => import(\"@/pages/UserList/UserListPage\"));\n\nfunction ProtectedRoute({ children }: { children: React.ReactNode }) {\n const { isAuthenticated } = useAuth();\n if (!isAuthenticated) return ;\n return <>{children};\n}\n```\n\n---\n\n## 状态管理选型\n\n| 状态类型 | 推荐方案 |\n| ------------------ | ------------------------------------------------- |\n| 组件内临时 UI 状态 | `useState` / `useReducer` |\n| 跨组件共享业务状态 | Zustand / Redux Toolkit / Jotai（按仓库实际选择） |\n| 服务端数据缓存 | React Query / SWR |\n| URL 驱动状态 | 路由参数 / `useSearchParams` |\n| 表单状态 | React Hook Form / Formik |\n\n### 核心原则\n\n- 就近管理：状态尽量放在最近的公共祖先\n- 单一数据源：同一份数据不要维护多份\n- 派生优于同步：可计算值优先在渲染期计算\n- 服务端数据优先交给请求库管理，不手动塞进全局 store\n- 不要因为“以后可能会用到”就把局部状态提前升级为全局状态\n\n---\n\n## API 层规范\n\n### 设计原则\n\n- 请求基础设施集中在 `services/`\n- 业务 API 按 feature 拆分，而不是全部堆在一个文件\n- 请求参数和响应结果都应有明确类型\n- 认证、错误格式化、通用拦截放在请求层统一处理\n- 页面和组件不要直接散落拼接请求细节\n\n### 示例\n\n```ts\n// services/request.ts\nconst request = axios.create({\n baseURL: import.meta.env.VITE_API_BASE_URL,\n timeout: 10000,\n});\n\nrequest.interceptors.response.use(\n (res) => res.data,\n (error) => {\n if (error.response?.status === 401) {\n redirectToLogin();\n }\n return Promise.reject(normalizeError(error));\n },\n);\n```\n\n```ts\n// features/user/api.ts\nexport function getUserList(\n params: UserQueryParams,\n): Promise> {\n return request.get(\"/users\", { params });\n}\n\nexport function updateUser(id: string, data: UpdateUserDTO): Promise {\n return request.put(`/users/${id}`, data);\n}\n```\n\n---\n\n## 错误处理\n\n### 必须覆盖的状态\n\n- Loading\n- Error\n- Empty\n- Data\n\n### 推荐做法\n\n- 关键功能模块使用 Error Boundary 包裹，避免局部异常导致全页白屏\n- 异步请求失败时必须给用户可见反馈\n- 重要操作提供重试能力\n- 不要吞错，不写空 `catch`\n\n### 示例（`react-error-boundary`，函数式 Fallback）\n\n```tsx\nimport { ErrorBoundary } from \"react-error-boundary\";\n\nfunction ModuleErrorFallback({\n resetErrorBoundary,\n}: {\n resetErrorBoundary: () => void;\n}) {\n return (\n
\n 模块加载失败\n \n
\n );\n}\n\nexport function UserDashboardSection() {\n return (\n \n \n \n );\n}\n```\n\n---\n\n## Suspense 与懒加载\n\n适用场景：\n\n- 路由级页面\n- 图表、富文本编辑器、地图、重型表格等大体积组件\n- 初始化成本较高的模块\n\n示例：\n\n```tsx\nconst HeavyChart = lazy(() => import(\"./components/HeavyChart\"));\n\nfunction Dashboard() {\n return (\n }>\n \n \n );\n}\n```\n\n建议：\n\n- 路由级优先 `lazy + Suspense`\n- `fallback` 优先使用 Skeleton 或更贴近内容的占位态，而不是纯 spinner\n\n---\n\n## 样式接入\n\n本 skill 不强制具体样式方案，默认遵循仓库现状。\n\n适配时注意：\n\n- Tailwind 项目继续使用 Tailwind\n- CSS Modules 项目保持命名与文件组织一致\n- styled-components 项目继续沿用其模式\n- 主题、颜色、字号、间距等优先复用仓库 token / CSS 变量\n- 避免在组件内硬编码大量视觉常量\n- 禁止内联样式（除动态值外）\n- 响应式处理需与项目断点约定一致\n\n---\n\n## 注释规范\n\n- **优先使用中文**：解释「为什么这样做」、业务约束、边界情况、非显而易见的权衡时，优先用中文撰写注释，便于团队与业务方阅读。\n- **与代码语言一致时的例外**：对接第三方协议字段名、HTTP 头、规范中的英文术语时，注释里可保留英文专有名词，必要时中英文并列说明。\n- **少而精**：能通过清晰命名与类型表达清楚的逻辑不写废话注释；复杂分支、临时兼容、性能取舍必须写清意图。\n- **公开 API**：模块或 hooks 的对外契约可用 JSDoc（`@param` / `@returns` / `@example`），说明用中文即可，除非仓库统一要求英文。\n\n---\n\n## TypeScript 规范\n\n通用 TypeScript / JavaScript 约定（类型与接口、`any`/`unknown`、React Props、不可变更新、错误处理、Zod、模式与安全等）见插件模板 **`templates/shared/rules/fec-typescript.md`**（初始化到项目后为 `.claude/rules/fec-typescript.md`）。\n\n- **函数签名**：参数上的复杂联合、内联对象、冗长回调应优先抽成具名类型（见同文件「函数参数：复杂类型宜具名」）。\n\n### React 项目补充约定\n\n- Props interface 命名: `ComponentNameProps`\n- 事件处理函数: `handle` 前缀（如 `handleClick`）\n- 回调 Props: `on` 前缀（如 `onChange`、`onSubmit`）\n- 组件优先写显式 props 与返回值类型（`JSX.Element` / `React.ReactElement`），避免依赖 `React.FC` 的隐式 `children` 等行为差异\n- 泛型组件使用 `` 约束，保持调用处类型推导；回调与事件类型优先使用 DOM / React 自带类型（如 `React.ChangeEvent`）\n\n```tsx\ninterface TableProps> {\n data: T[];\n columns: ColumnDef[];\n onRowClick?: (row: T) => void;\n}\n```\n\n---\n\n## 测试规范\n\n### 应优先覆盖的内容\n\n- 核心交互行为（点击、输入、提交）\n- 条件渲染（loading / error / empty / data）\n- 关键 hooks 的返回值和副作用\n- API 调用 mock 与模块级集成测试\n\n### 推荐风格\n\n- 测试用户行为，而不是实现细节\n- 优先使用 `screen.getByRole`、`getByLabelText`\n- 避免围绕内部 state 写脆弱测试\n- 只测关键行为，不机械追求覆盖率数字\n\n### 示例\n\n```tsx\ndescribe(\"UserForm\", () => {\n it(\"should submit with valid data\", async () => {\n const onSubmit = vi.fn();\n render();\n\n await userEvent.type(screen.getByLabelText(\"用户名\"), \"test\");\n await userEvent.click(screen.getByRole(\"button\", { name: \"提交\" }));\n\n expect(onSubmit).toHaveBeenCalledWith({ username: \"test\" });\n });\n\n it(\"should show error on invalid input\", async () => {\n render();\n await userEvent.click(screen.getByRole(\"button\", { name: \"提交\" }));\n expect(screen.getByText(\"用户名不能为空\")).toBeInTheDocument();\n });\n});\n```\n\n---\n\n## 性能优化\n\n在以下场景考虑性能优化：\n\n- 大列表 / 大表格\n- 高频重渲染组件\n- 大量 props 传递的复杂树\n- 重型第三方组件\n- 高频变化 context\n\n### 推荐手段\n\n- 合理使用 `React.memo`\n- 只在必要时使用 `useMemo` / `useCallback`\n- 列表使用稳定 `key`\n- 大列表使用虚拟滚动\n- 路由级做 code splitting\n- 避免将高频变化值放进顶层 context\n- 避免在 render 中无意义创建大量新对象 / 新函数 / 新数组\n\n---\n\n## 常见反模式\n\n避免：\n\n- prop drilling 过深却不考虑组合或局部封装\n- 对局部问题过度使用 context\n- 把数据请求、视图渲染、命令式 DOM 操作全塞进一个文件\n- 在 useEffect 中做可以在事件处理函数中完成的事\n- 用 `useEffect + setState` 模拟本可直接计算的派生值\n- 将所有状态都推进全局 store\n- 在 `components/` 中放业务耦合组件\n- 直接绕过模块出口，从 feature 深层路径导入\n- 没有明显收益却提前做复杂优化\n- **新增类组件**或手写类式 Error Boundary（应函数组件 + `react-error-boundary` 等）\n\n---\n\n## 输出检查清单\n\n输出 React 代码或方案时，至少检查：\n\n- [ ] 是否先对齐了仓库现有约定\n- [ ] 页面 / feature / 通用组件边界是否清晰\n- [ ] 目录结构是否与模块复杂度匹配\n- [ ] Props 类型完整且明确\n- [ ] 解释性注释是否优先使用中文且点到要害\n- [ ] 可复用逻辑是否已提取为 hooks\n- [ ] loading / error / empty / data 状态是否齐全\n- [ ] API 层是否具备类型约束和统一错误处理\n- [ ] 是否避免滥用 `any`，外部/接口数据是否在边界收窄或校验\n- [ ] 状态管理是否符合就近原则\n- [ ] 路由级或重型模块是否考虑懒加载\n- [ ] 样式方案是否与仓库保持一致\n- [ ] 关键行为是否有测试覆盖\n- [ ] 关键模块已用 **`react-error-boundary`**（等）包裹，且未手写类组件式 Boundary\n- [ ] 超长列表是否评估虚拟化；弹窗/复合组件是否具备键盘与焦点约定\n- [ ] 是否引入了不必要的新依赖或新范式\n\n---\n\nFile v2.4.0:skill-card.md\n\n## Description:
\nUse when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[bovinphang](https://clawhub.ai/user/bovinphang)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and engineering agents use this skill to plan, implement, or review React and TypeScript project structure, module boundaries, component architecture, hooks organization, routing, state ownership, API integration shape, error handling, styling defaults, and repository-wide conventions.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Generated architecture guidance can be applied too broadly or conflict with existing repository conventions.
\nMitigation: Review proposed structure and file moves against the current repository conventions before applying changes.
\nRisk: The security evidence notes that related maintainer workflows may expose full-access nested review behavior.
\nMitigation: Use the documented no-yolo option or normal sandbox prompts when invoking any review helper that can run nested agent commands.
\n\n\n## Reference(s):
\n- [React Project Details](references/react-project-details.md)
\n- [ClawHub Skill Page](https://clawhub.ai/bovinphang/fec-react-project-standard)
\n\n\n## Skill Output:
\n**Output Type(s):** [guidance, markdown, code, shell commands, configuration]
\n**Output Format:** [Markdown guidance with code, shell command, and configuration examples when needed]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Guidance should preserve existing repository conventions, prefer focused specialty workflows for deeper areas, and include concrete file-structure recommendations when relevant.]
\n\n## Skill Version(s):
\n2.4.0 (source: server release evidence, package.json, metadata.json, README.md)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v2.4.0:metadata.json\n\n{\n \"id\": \"fec-react-project-standard\",\n \"name\": \"React 项目规范\",\n \"category\": \"project-standard\",\n \"tags\": [\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"summary\": \"Frontend Craft skill for React 项目规范.\",\n \"version\": \"2.4.0\",\n \"license\": \"MIT\",\n \"homepage\": \"https://github.com/bovinphang/frontend-craft\",\n \"repository\": \"https://github.com/bovinphang/frontend-craft\",\n \"keywords\": [\n \"project-standard\",\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"platforms\": [\n \"skills-cli\",\n \"skillreg\",\n \"claude-code\",\n \"codex\",\n \"cursor\",\n \"opencode\",\n \"openclaw\",\n \"generic-skill-runtime\"\n ],\n \"description\": \"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\",\n \"source\": \"skills/fec-react-project-standard\",\n \"references\": [\n \"references/react-project-details.md\"\n ],\n \"relations\": {\n \"relatedSkills\": [\n \"fec-typescript-type-safety\",\n \"fec-state-management\",\n \"fec-tailwind-design-system\",\n \"fec-responsive-layout\",\n \"fec-form-handling\",\n \"fec-data-fetching\",\n \"fec-component-testing\",\n \"fec-e2e-testing\",\n \"fec-accessibility-check\",\n \"fec-security-review\",\n \"fec-list-virtualization\",\n \"fec-svg-animation\",\n \"fec-canvas-threejs\",\n \"fec-api-integration\",\n \"fec-motion-interaction\"\n ],\n \"boundaryWorkflows\": [\n \"Use specialty workflows for complex forms, state ownership, TypeScript contracts, server state, tests, accessibility, security, large lists, animation, or graphics.\",\n \"Keep generic React component architecture and hooks organization in the React project workflow.\"\n ],\n \"capabilityTags\": [\n \"react\",\n \"project-standard\",\n \"fec-architecture\"\n ]\n }\n}\n\nFile v2.4.0:package.json\n\n{\n \"name\": \"@frontend-craft/fec-react-project-standard\",\n \"version\": \"2.4.0\",\n \"description\": \"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.\",\n \"type\": \"module\",\n \"license\": \"MIT\",\n \"author\": {\n \"name\": \"Bovin Phang\",\n \"email\": \"pengbaowen@msn.com\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/bovinphang/frontend-craft\",\n \"directory\": \"skills/fec-react-project-standard\"\n },\n \"homepage\": \"https://github.com/bovinphang/frontend-craft\",\n \"keywords\": [\n \"agent-skill\",\n \"frontend-craft\",\n \"project-standard\",\n \"react\",\n \"typescript\",\n \"hooks\",\n \"components\",\n \"architecture\"\n ],\n \"files\": [\n \"SKILL.md\",\n \"references\",\n \"scripts\",\n \"data\",\n \"metadata.json\",\n \"README.md\",\n \"LICENSE\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n }\n}","readmeExcerpt":"Skill: React Project Standard Owner: bovinphang Summary: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibil Tags: latest:2.9.0 Version history: v2.9.0 | 2026-09-26T14:43:","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"src/\n├── app/ # Application entry and global configuration\n│ ├── App.tsx # Root component (Provider combination)\n│ ├── routes.tsx # Routing configuration\n│ └── providers.tsx # Global Provider assembly\n│\n├── pages/ # Page components (one-to-one correspondence with routing)\n│ ├── Dashboard/\n│ │ ├── DashboardPage.tsx\n│ │ ├── components/ # Page private components\n│ │ └── hooks/ # Page private hooks\n│ ├── UserList/\n│ └── Settings/\n│\n├── layouts/ # Layout component\n│ ├── MainLayout.tsx # Main layout (sidebar + top bar + content area)\n│ ├── AuthLayout.tsx # Login/registration page layout\n│ └── BlankLayout.tsx # Blank layout (error page, etc.)\n│\n├── features/ # Function modules (divided by business areas)\n│ ├── auth/\n│ │ ├── components/ # Module components\n│ │ ├── hooks/ # module hooks\n│ │ ├── api.ts # Module API call\n│ │ ├── types.ts # Module type definition\n│ │ ├── constants.ts # Module constants\n│ │ └── index.ts # Module publicly exported\n│ └── order/\n│\n├── components/ # Globally shared UI components\n│ ├── Button/\n│ │ ├── Button.tsx\n│ │ ├── Button.styles.css\n│ │ └── __tests__/\n│ ├── Modal/\n│ ├── Form/\n│ └── ErrorBoundary/ # Thin wrapper (function component) for react-error-boundary etc.\n│\n├── hooks/ # Global shared hooks\n│ ├── useAuth.ts\n│ ├── useDebounce.ts\n│ └── useMediaQuery.ts\n│\n├── services/ # API base layer\n│ ├── request.ts # Axios/fetch instance and interceptor\n│ └── endpoints/ # API endpoint definition (such as split by field)\n│\n├── stores/ # Global status management\n│ ├── authStore.ts\n│ └── uiStore.ts\n│\n├── locales/ # International language pack\n│ ├── zh-CN.json # Simplified Chinese\n│ ├── en-US.json # English\n│ └── index.ts # i18n instance initialization (i18next / react-intl)\n│\n├── assets/ # Static resources\n│ ├── images/ # Pictures (PNG, JPG, WebP)\n│ ├── icons/ # SVG icon\n│ └── fonts/ # Custom fonts\n│\n├── config/ # Application configuration\n│ ├── env.ts # Typed encapsulation of environment variables\n│ └── features.ts #"},{"language":"text","snippet":"Page components (Pages) → route mapping, layout combination, page arrangement\n └── Container/orchestration layer → data acquisition, status organization, event orchestration\n └── Business components → Domain logic display\n └── Common components → No business coupling, reusable across modules"},{"language":"text","snippet":"ComponentName/\n├── ComponentName.tsx\n├── ComponentName.types.ts\n├── ComponentName.styles.css\n├── hooks/\n│ └── useComponentLogic.ts\n├── components/\n│ └── SubComponent.tsx\n└── __tests__/\n └── ComponentName.spec.tsx"},{"language":"tsx","snippet":"interface TableProps> {\n data: T[];\n columns: ColumnDef[];\n onRowClick?: (row: T) => void;\n}"},{"language":"tsx","snippet":"describe(\"UserForm\", () => {\n it(\"should submit with valid data\", async () => {\n const onSubmit = vi.fn();\n render();\n\n await userEvent.type(screen.getByLabelText(\"username\"), \"test\");\n await userEvent.click(screen.getByRole(\"button\", { name: \"Submit\" }));\n\n expect(onSubmit).toHaveBeenCalledWith({ username: \"test\" });\n });\n\n it(\"should show error on invalid input\", async () => {\n render();\n await userEvent.click(screen.getByRole(\"button\", { name: \"Submit\" }));\n expect(screen.getByText(\"Username cannot be empty\")).toBeInTheDocument();\n });\n});"},{"language":"tsx","snippet":"function useUserList(params: QueryParams) {\n const [data, setData] = useState([]);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n\n const fetch = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const res = await getUserList(params);\n setData(res.list);\n } catch (e) {\n setError(e as Error);\n } finally {\n setLoading(false);\n }\n }, [params]);\n\n useEffect(() => {\n fetch();\n }, [fetch]);\n\n return { data, loading, error, refetch: fetch };\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: fec-react-project-standard\ndescription: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React project specification, React component architecture.\n---\n\n# React project specifications\n\nSuitable for medium and large module construction, page reconstruction and engineering structure design in React + TypeScript warehouse.\n\n## Purpose\n\nProvide engineering structure, module boundaries and default implementation conventions for React + TypeScript projects to ensure clear architecture and maintainable code.\n\n## Procedure\n\nThis skill mainly solves the problem of \"how to design and implement\" React engineering tasks, without repeating the basic coding bottom line. When handling React engineering tasks, perform them in the following order:\n\n1. Identify the warehouse and have an agreement\n - Directory organization\n - Style system\n - Status management solution\n - Request packaging method\n - Testing framework\n - UI component library/design system\n\n2. Determine which layer the target belongs to\n - Routing page\n -Page private components\n - feature business module\n - Global common components\n - hooks / services / stores / utils\n\n3. Design the boundaries before writing the code\n - What logic belongs to page layout\n - Which logic belongs to feature\n - Which logic should be transferred to general capabilities?\n - Which state should be managed locally and which should be handed over to store/query/URL\n - When the status ownership is complex, use the status management process to make a status list first\n - When the boundaries of DTO, public props, generic components or `tsconfig` are complex, first use the TypeScript project specification process to converge cross-framework type contracts\n\n4. Complete key quality items when outputting\n - loading / error / empty / data status\n - Error handling and retrying\n - Type constraints\n - Key test entrance\n - Diversion of necessary special skills\n - Check whether the dependency already exists in `package.json`. If it is missing, give the installation command first and then use it.\n - Whether heavy UI capabilities (animation, charts, 3D, editors, maps) are isolated as leaf components and loaded on demand\n - Whether images, videos, fonts and other resources are localized and cacheable, and avoid placeholder URLs from entering delivery\n - Whether page-level Error Boundary, module-level fallback, API error mapping and user-recoverable actions are consistent\n - Whether Tailwind token/variant or responsive layout requirements should be diverted to the corresponding special skill\n- Perform lightweight screening for obvious architectural performa"},{"path":"README.md","content":"# React project specifications\n\nOrganize React and TypeScript components, hooks, routes, state boundaries, and project structure.\n\n## Skill\n\n- ID: `fec-react-project-standard`\n- Category: `project-standard`\n- Version: `2.9.0`\n- Source: `skills/fec-react-project-standard/SKILL.md`\n\n## Description\n\nUse when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React project specification, React component architecture.\n\n## Usage\n\nInstall or import this package with any skill runtime that understands the standard `SKILL.md` layout. The canonical source remains the Frontend Craft repository.\n\n## Packaged Files\n\n- [references/react-performance-patterns.md](references/react-performance-patterns.md)\n- [references/react-project-structure.md](references/react-project-structure.md)\n- [references/react-quality-patterns.md](references/react-quality-patterns.md)\n- [references/react-runtime-patterns.md](references/react-runtime-patterns.md)\n\n## Optional Related Packages\n\n- `@bovinphang/fec-typescript-project-standard`\n- `@bovinphang/fec-state-management`\n- `@bovinphang/fec-tailwind-design-system`\n- `@bovinphang/fec-responsive-layout`\n- `@bovinphang/fec-form-handling`\n- `@bovinphang/fec-data-fetching`\n- `@bovinphang/fec-component-testing`\n- `@bovinphang/fec-e2e-testing`\n- `@bovinphang/fec-accessibility-check`\n- `@bovinphang/fec-security-review`\n- `@bovinphang/fec-list-virtualization`\n- `@bovinphang/fec-svg-animation`\n- `@bovinphang/fec-canvas-threejs`\n- `@bovinphang/fec-api-integration`\n- `@bovinphang/fec-motion-interaction`\n\n## License\n\nMIT"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b0nh7hvj1pffeqc8y0dqwwh83m726\",\n \"slug\": \"fec-react-project-standard\",\n \"version\": \"2.9.0\",\n \"publishedAt\": 1790433799038\n}"},{"path":"references/react-performance-patterns.md","content":"# React performance patterns\n\nThis file keeps lightweight React project-standard performance guidance. Use the frontend performance workflow when the task needs metrics, traces, profiles, bundle analysis, network evidence, or a formal performance report.\n\n### Performance (in conjunction with the \"Performance Optimization\" section)\n\n- **useMemo**: Expensive derivation, large list sorting/filtering; pay attention to immutable data, such as `useMemo(() => [...list].sort(...), [list])`, and avoid directly `sort` the mutable original array.\n- **useCallback**: passed to **`React.memo`** sub-component or used as a callback for other Hook dependencies, used when there is a stable reference requirement.\n- **React.memo**: An acceptable component with pure display and shallow props; do not apply memo globally.\n- **Virtual List**: For very long lists, use **TanStack Virtual**, **react-window**, etc., and only render nodes in the viewport (see \"Suspense and Lazy Loading\" for routing-level and component-level lazy loading).\n\n## Performance optimization\n\nConsider performance optimization in the following scenarios:\n\n- Large list/large table\n- High frequency re-rendering components\n- Complex trees passed with a large number of props\n- Heavy-duty third-party components\n- High frequency changing context\n\n### Recommended means\n\n- Use `React.memo` appropriately\n- Use `useMemo` / `useCallback` only when necessary\n- List uses stable `key`\n- Use virtual scrolling for large lists\n- Code splitting at routing level\n- Avoid putting high-frequency changing values into the top-level context\n- Avoid meaninglessly creating a large number of new objects/new functions/new arrays in render\n- Heavy charting, editor, map, 3D and media processing capabilities into leaf components or route-level lazy loading boundaries\n- Lazy loading components must be equipped with loading, error, empty or downgraded UI to avoid only optimizing the package body but destroying the user state\n\n---"},{"path":"references/react-project-structure.md","content":"# React project structure and component boundaries\n\n## Project structure (recommended reference)\n\nThe following is the industry's best practice structure for medium and large React projects, tailored according to the actual situation of the project:\n\n```text\nsrc/\n├── app/ # Application entry and global configuration\n│ ├── App.tsx # Root component (Provider combination)\n│ ├── routes.tsx # Routing configuration\n│ └── providers.tsx # Global Provider assembly\n│\n├── pages/ # Page components (one-to-one correspondence with routing)\n│ ├── Dashboard/\n│ │ ├── DashboardPage.tsx\n│ │ ├── components/ # Page private components\n│ │ └── hooks/ # Page private hooks\n│ ├── UserList/\n│ └── Settings/\n│\n├── layouts/ # Layout component\n│ ├── MainLayout.tsx # Main layout (sidebar + top bar + content area)\n│ ├── AuthLayout.tsx # Login/registration page layout\n│ └── BlankLayout.tsx # Blank layout (error page, etc.)\n│\n├── features/ # Function modules (divided by business areas)\n│ ├── auth/\n│ │ ├── components/ # Module components\n│ │ ├── hooks/ # module hooks\n│ │ ├── api.ts # Module API call\n│ │ ├── types.ts # Module type definition\n│ │ ├── constants.ts # Module constants\n│ │ └── index.ts # Module publicly exported\n│ └── order/\n│\n├── components/ # Globally shared UI components\n│ ├── Button/\n│ │ ├── Button.tsx\n│ │ ├── Button.styles.css\n│ │ └── __tests__/\n│ ├── Modal/\n│ ├── Form/\n│ └── ErrorBoundary/ # Thin wrapper (function component) for react-error-boundary etc.\n│\n├── hooks/ # Global shared hooks\n│ ├── useAuth.ts\n│ ├── useDebounce.ts\n│ └── useMediaQuery.ts\n│\n├── services/ # API base layer\n│ ├── request.ts # Axios/fetch instance and interceptor\n│ └── endpoints/ # API endpoint definition (such as split by field)\n│\n├── stores/ # Global status management\n│ ├── authStore.ts\n│ └── uiStore.ts\n│\n├── locales/ # International language pack\n│ ├── zh-CN.json # Simplified Chinese\n│ ├── en-US.json # English\n│ └── index.ts # i18n instance initialization (i18next / react-intl)\n│\n├── assets/ # Static resources\n│ ├── images/ # Pictures (PNG, JPG, WebP)\n│ ├── icons/ # SVG icon\n│ └── fonts/ # Custom fonts\n│\n├── config/ # Application configuration\n│ ├── env.ts # Typed encapsulation of environment variables\n│ └── features.ts # Feature Flags Management\n│\n├── types/ # Global shared types\n│ ├── api.ts # API response/request common type\n│ ├── models.ts #Business entity type\n│ └── global.d.ts # Global type extension (picture module declaration, etc.)\n│\n├── utils/ # Pure utility function\n│ ├── format.ts # Date, number, currency formatting\n│ ├── validators.ts # Form validation rules\n│ └── storage.ts # LocalStorage / SessionStorage package\n│\n├── styles/ # Global styles and themes\n│ ├── global.css # Global basic style (reset/normalize)\n│ ├── variables.css # CSS variables (color, spacing, font size)\n│ ├── breakpoints.ts # Responsive breakpoint constants\n│ └── themes/ # theme definition\n│ ├── light.css # Light theme variable\n│ ├── dark.css # Dark theme variable\n│ "}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibil Skill: React Project Standard Owner: bovinphang Summary: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibil Tags: latest:2.9.0 Version history: v2.9.0 | 2026-09-26T14:43:","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1756,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T22:30:12.372Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T22:30:12.372Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T14:19:02.389Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}