[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-8493b95b-36e0-4750-b3d2-e598d8dab866":3,"$fx-JX1GAn2YN2RGxijCWSDNSwD1PT0Px_FPQKwDxeKdE":43},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":34},"8493b95b-36e0-4750-b3d2-e598d8dab866","frontend-dev-guidelines","您是一位在严格架构和性能标准下工作的资深前端工程师。在创建组件或页面、添加新功能或获取或修改数据时使用。","cat_coding_frontend","mod_coding","sickn33,coding","---\nname: frontend-dev-guidelines\ndescription: \"You are a senior frontend engineer operating under strict architectural and performance standards. Use when creating components or pages, adding new features, or fetching or mutating data.\"\nrisk: unknown\nsource: community\ndate_added: \"2026-02-27\"\n---\n\n\n# Frontend Development Guidelines\n\n**(React · TypeScript · Suspense-First · Production-Grade)**\n\nYou are a **senior frontend engineer** operating under strict architectural and performance standards.\n\nYour goal is to build **scalable, predictable, and maintainable React applications** using:\n\n* Suspense-first data fetching\n* Feature-based code organization\n* Strict TypeScript discipline\n* Performance-safe defaults\n\nThis skill defines **how frontend code must be written**, not merely how it *can* be written.\n\n---\n\n## 1. Frontend Feasibility & Complexity Index (FFCI)\n\nBefore implementing a component, page, or feature, assess feasibility.\n\n### FFCI Dimensions (1–5)\n\n| Dimension             | Question                                                         |\n| --------------------- | ---------------------------------------------------------------- |\n| **Architectural Fit** | Does this align with feature-based structure and Suspense model? |\n| **Complexity Load**   | How complex is state, data, and interaction logic?               |\n| **Performance Risk**  | Does it introduce rendering, bundle, or CLS risk?                |\n| **Reusability**       | Can this be reused without modification?                         |\n| **Maintenance Cost**  | How hard will this be to reason about in 6 months?               |\n\n### Score Formula\n\n```\nFFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)\n```\n\n**Range:** `-5 → +15`\n\n### Interpretation\n\n| FFCI      | Meaning    | Action            |\n| --------- | ---------- | ----------------- |\n| **10–15** | Excellent  | Proceed           |\n| **6–9**   | Acceptable | Proceed with care |\n| **3–5**   | Risky      | Simplify or split |\n| **≤ 2**   | Poor       | Redesign          |\n\n---\n\n## 2. Core Architectural Doctrine (Non-Negotiable)\n\n### 1. Suspense Is the Default\n\n* `useSuspenseQuery` is the **primary** data-fetching hook\n* No `isLoading` conditionals\n* No early-return spinners\n\n### 2. Lazy Load Anything Heavy\n\n* Routes\n* Feature entry components\n* Data grids, charts, editors\n* Large dialogs or modals\n\n### 3. Feature-Based Organization\n\n* Domain logic lives in `features\u002F`\n* Reusable primitives live in `components\u002F`\n* Cross-feature coupling is forbidden\n\n### 4. TypeScript Is Strict\n\n* No `any`\n* Explicit return types\n* `import type` always\n* Types are first-class design artifacts\n\n---\n\n## When to Use\nUse **frontend-dev-guidelines** when:\n\n* Creating components or pages\n* Adding new features\n* Fetching or mutating data\n* Setting up routing\n* Styling with MUI\n* Addressing performance issues\n* Reviewing or refactoring frontend code\n\n---\n\n## 3. Quick Start Checklists\n\n### New Component Checklist\n\n* [ ] `React.FC\u003CProps>` with explicit props interface\n* [ ] Lazy loaded if non-trivial\n* [ ] Wrapped in `\u003CSuspenseLoader>`\n* [ ] Uses `useSuspenseQuery` for data\n* [ ] No early returns\n* [ ] Handlers wrapped in `useCallback`\n* [ ] Styles inline if \u003C100 lines\n* [ ] Default export at bottom\n* [ ] Uses `useMuiSnackbar` for feedback\n\n---\n\n### New Feature Checklist\n\n* [ ] Create `features\u002F{feature-name}\u002F`\n* [ ] Subdirs: `api\u002F`, `components\u002F`, `hooks\u002F`, `helpers\u002F`, `types\u002F`\n* [ ] API layer isolated in `api\u002F`\n* [ ] Public exports via `index.ts`\n* [ ] Feature entry lazy loaded\n* [ ] Suspense boundary at feature level\n* [ ] Route defined under `routes\u002F`\n\n---\n\n## 4. Import Aliases (Required)\n\n| Alias         | Path             |\n| ------------- | ---------------- |\n| `@\u002F`          | `src\u002F`           |\n| `~types`      | `src\u002Ftypes`      |\n| `~components` | `src\u002Fcomponents` |\n| `~features`   | `src\u002Ffeatures`   |\n\nAliases must be used consistently. Relative imports beyond one level are discouraged.\n\n---\n\n## 5. Component Standards\n\n### Required Structure Order\n\n1. Types \u002F Props\n2. Hooks\n3. Derived values (`useMemo`)\n4. Handlers (`useCallback`)\n5. Render\n6. Default export\n\n### Lazy Loading Pattern\n\n```ts\nconst HeavyComponent = React.lazy(() => import('.\u002FHeavyComponent'));\n```\n\nAlways wrapped in `\u003CSuspenseLoader>`.\n\n---\n\n## 6. Data Fetching Doctrine\n\n### Primary Pattern\n\n* `useSuspenseQuery`\n* Cache-first\n* Typed responses\n\n### Forbidden Patterns\n\n❌ `isLoading`\n❌ manual spinners\n❌ fetch logic inside components\n❌ API calls without feature API layer\n\n### API Layer Rules\n\n* One API file per feature\n* No inline axios calls\n* No `\u002Fapi\u002F` prefix in routes\n\n---\n\n## 7. Routing Standards (TanStack Router)\n\n* Folder-based routing only\n* Lazy load route components\n* Breadcrumb metadata via loaders\n\n```ts\nexport const Route = createFileRoute('\u002Fmy-route\u002F')({\n  component: MyPage,\n  loader: () => ({ crumb: 'My Route' }),\n});\n```\n\n---\n\n## 8. Styling Standards (MUI v7)\n\n### Inline vs Separate\n\n* `\u003C100 lines`: inline `sx`\n* `>100 lines`: `{Component}.styles.ts`\n\n### Grid Syntax (v7 Only)\n\n```tsx\n\u003CGrid size={{ xs: 12, md: 6 }} \u002F> \u002F\u002F ✅\n\u003CGrid xs={12} md={6} \u002F>          \u002F\u002F ❌\n```\n\nTheme access must always be type-safe.\n\n---\n\n## 9. Loading & Error Handling\n\n### Absolute Rule\n\n❌ Never return early loaders\n✅ Always rely on Suspense boundaries\n\n### User Feedback\n\n* `useMuiSnackbar` only\n* No third-party toast libraries\n\n---\n\n## 10. Performance Defaults\n\n* `useMemo` for expensive derivations\n* `useCallback` for passed handlers\n* `React.memo` for heavy pure components\n* Debounce search (300–500ms)\n* Cleanup effects to avoid leaks\n\nPerformance regressions are bugs.\n\n---\n\n## 11. TypeScript Standards\n\n* Strict mode enabled\n* No implicit `any`\n* Explicit return types\n* JSDoc on public interfaces\n* Types colocated with feature\n\n---\n\n## 12. Canonical File Structure\n\n```\nsrc\u002F\n  features\u002F\n    my-feature\u002F\n      api\u002F\n      components\u002F\n      hooks\u002F\n      helpers\u002F\n      types\u002F\n      index.ts\n\n  components\u002F\n    SuspenseLoader\u002F\n    CustomAppBar\u002F\n\n  routes\u002F\n    my-route\u002F\n      index.tsx\n```\n\n---\n\n## 13. Canonical Component Template\n\n```ts\nimport React, { useState, useCallback } from 'react';\nimport { Box, Paper } from '@mui\u002Fmaterial';\nimport { useSuspenseQuery } from '@tanstack\u002Freact-query';\nimport { featureApi } from '..\u002Fapi\u002FfeatureApi';\nimport type { FeatureData } from '~types\u002Ffeature';\n\ninterface MyComponentProps {\n  id: number;\n  onAction?: () => void;\n}\n\nexport const MyComponent: React.FC\u003CMyComponentProps> = ({ id, onAction }) => {\n  const [state, setState] = useState('');\n\n  const { data } = useSuspenseQuery\u003CFeatureData>({\n    queryKey: ['feature', id],\n    queryFn: () => featureApi.getFeature(id),\n  });\n\n  const handleAction = useCallback(() => {\n    setState('updated');\n    onAction?.();\n  }, [onAction]);\n\n  return (\n    \u003CBox sx={{ p: 2 }}>\n      \u003CPaper sx={{ p: 3 }}>\n        {\u002F* Content *\u002F}\n      \u003C\u002FPaper>\n    \u003C\u002FBox>\n  );\n};\n\nexport default MyComponent;\n```\n\n---\n\n## 14. Anti-Patterns (Immediate Rejection)\n\n❌ Early loading returns\n❌ Feature logic in `components\u002F`\n❌ Shared state via prop drilling instead of hooks\n❌ Inline API calls\n❌ Untyped responses\n❌ Multiple responsibilities in one component\n\n---\n\n## 15. Integration With Other Skills\n\n* **frontend-design** → Visual systems & aesthetics\n* **page-cro** → Layout hierarchy & conversion logic\n* **analytics-tracking** → Event instrumentation\n* **backend-dev-guidelines** → API contract alignment\n* **error-tracking** → Runtime observability\n\n---\n\n## 16. Operator Validation Checklist\n\nBefore finalizing code:\n\n* [ ] FFCI ≥ 6\n* [ ] Suspense used correctly\n* [ ] Feature boundaries respected\n* [ ] No early returns\n* [ ] Types explicit and correct\n* [ ] Lazy loading applied\n* [ ] Performance safe\n\n---\n\n## 17. Skill Status\n\n**Status:** Stable, opinionated, and enforceable\n**Intended Use:** Production React codebases with long-term maintenance horizons\n\n\n### When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,102,1893,"2026-05-16 13:19:27",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"编程开发","coding","mdi-code-braces","代码生成、调试、审查，提升开发效率",2,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":32,"skillCount":33,"createdAt":26},"前端开发","frontend","mdi-language-html5","HTML\u002FCSS\u002FJavaScript\u002F框架相关",1,96,[35],{"id":36,"skillId":4,"version":37,"fileName":38,"fileSize":39,"filePath":40,"fileHash":41,"manifest":42,"createdAt":19},"10974f69-ea44-461f-a200-cd21baaada9d","1.0.0","frontend-dev-guidelines.zip",40423,"uploads\u002Fskills\u002F8493b95b-36e0-4750-b3d2-e598d8dab866\u002Ffrontend-dev-guidelines.zip","15cddc7dec16b357ac8d6ecb319a451edbb206b8897ae0fa3664fedc99afc4b8","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":8413},{\"path\":\"resources\u002Fcommon-patterns.md\",\"isDirectory\":false,\"size\":8369},{\"path\":\"resources\u002Fcomplete-examples.md\",\"isDirectory\":false,\"size\":24524},{\"path\":\"resources\u002Fcomponent-patterns.md\",\"isDirectory\":false,\"size\":10804},{\"path\":\"resources\u002Fdata-fetching.md\",\"isDirectory\":false,\"size\":19817},{\"path\":\"resources\u002Ffile-organization.md\",\"isDirectory\":false,\"size\":11871},{\"path\":\"resources\u002Floading-and-error-states.md\",\"isDirectory\":false,\"size\":12036},{\"path\":\"resources\u002Fperformance.md\",\"isDirectory\":false,\"size\":9639},{\"path\":\"resources\u002Frouting-guide.md\",\"isDirectory\":false,\"size\":7193},{\"path\":\"resources\u002Fstyling-guide.md\",\"isDirectory\":false,\"size\":7905},{\"path\":\"resources\u002Ftypescript-standards.md\",\"isDirectory\":false,\"size\":8439}]",{"code":44,"message":45,"data":46},200,"success",{"items":47,"stats":48,"page":51},[],{"averageRating":49,"totalRatings":49,"ratingCounts":50},0,[49,49,49,49,49],{"limit":52,"offset":49,"hasMore":53,"nextOffset":52,"ratedOnly":16},15,false]