{"id":"5df7ddbb-4970-4044-a17a-f743ca4309a4","shortId":"Fu7sCT","kind":"skill","title":"frontend-dev-guidelines","tagline":"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.","description":"# 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/`\n* Reusable primitives live in `components/`\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<Props>` with explicit props interface\n* [ ] Lazy loaded if non-trivial\n* [ ] Wrapped in `<SuspenseLoader>`\n* [ ] Uses `useSuspenseQuery` for data\n* [ ] No early returns\n* [ ] Handlers wrapped in `useCallback`\n* [ ] Styles inline if <100 lines\n* [ ] Default export at bottom\n* [ ] Uses `useMuiSnackbar` for feedback\n\n---\n\n### New Feature Checklist\n\n* [ ] Create `features/{feature-name}/`\n* [ ] Subdirs: `api/`, `components/`, `hooks/`, `helpers/`, `types/`\n* [ ] API layer isolated in `api/`\n* [ ] Public exports via `index.ts`\n* [ ] Feature entry lazy loaded\n* [ ] Suspense boundary at feature level\n* [ ] Route defined under `routes/`\n\n---\n\n## 4. Import Aliases (Required)\n\n| Alias         | Path             |\n| ------------- | ---------------- |\n| `@/`          | `src/`           |\n| `~types`      | `src/types`      |\n| `~components` | `src/components` |\n| `~features`   | `src/features`   |\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 / 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('./HeavyComponent'));\n```\n\nAlways wrapped in `<SuspenseLoader>`.\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 `/api/` 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('/my-route/')({\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* `<100 lines`: inline `sx`\n* `>100 lines`: `{Component}.styles.ts`\n\n### Grid Syntax (v7 Only)\n\n```tsx\n<Grid size={{ xs: 12, md: 6 }} /> // ✅\n<Grid xs={12} md={6} />          // ❌\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/\n  features/\n    my-feature/\n      api/\n      components/\n      hooks/\n      helpers/\n      types/\n      index.ts\n\n  components/\n    SuspenseLoader/\n    CustomAppBar/\n\n  routes/\n    my-route/\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/material';\nimport { useSuspenseQuery } from '@tanstack/react-query';\nimport { featureApi } from '../api/featureApi';\nimport type { FeatureData } from '~types/feature';\n\ninterface MyComponentProps {\n  id: number;\n  onAction?: () => void;\n}\n\nexport const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {\n  const [state, setState] = useState('');\n\n  const { data } = useSuspenseQuery<FeatureData>({\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    <Box sx={{ p: 2 }}>\n      <Paper sx={{ p: 3 }}>\n        {/* Content */}\n      </Paper>\n    </Box>\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/`\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.","tags":["frontend","dev","guidelines","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding"],"capabilities":["skill","source-sickn33","skill-frontend-dev-guidelines","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/frontend-dev-guidelines","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 37911 github stars · SKILL.md body (8,052 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:51:05.442Z","embedding":null,"createdAt":"2026-04-18T20:34:55.137Z","updatedAt":"2026-05-18T18:51:05.442Z","lastSeenAt":"2026-05-18T18:51:05.442Z","tsv":"'+15':187 '-5':186 '/api':510 '/api/featureapi':704 '/heavycomponent':466 '/my-route':537 '1':101,118,218,441 '10':192,609 '100':364,552,556 '11':638 '12':568,573,658 '13':681 '14':755 '15':193,786 '16':821 '17':848 '2':208,211,239,444,746 '3':202,256,330,446,750 '300':627 '4':277,410,450 '5':119,203,435,453 '500ms':628 '6':173,196,455,470,570,575,829 '7':514 '8':544 '9':197,584 'absolut':588 'accept':198 'access':577 'action':191,879 'ad':24,309 'address':322 'aesthet':796 'alia':414 'alias':412,423 'align':126,815 'alway':288,467,579,594 'analyt':805 'analytics-track':804 'anti':757 'anti-pattern':756 'anyth':242 'api':383,388,392,491,495,497,501,667,777,813 'appli':845 'applic':66,873 'architectur':14,52,122,178,213 'artifact':295 'ask':917 'assess':114 'avoid':632 'axio':507 'backend':810 'backend-dev-guidelin':809 'base':75,130,259,521 'beyond':430 'bottom':369 'boundari':402,598,834,925 'box':693,743 'breadcrumb':528 'bug':637 'build':60 'bundl':151 'cach':478 'cache-first':477 'call':492,508,778 'canon':659,682 'care':201 'chart':250 'checklist':333,336,376,824 'clarif':919 'class':293 'cleanup':629 'clear':892 'cls':153 'code':76,90,329,827 'codebas':860 'coloc':655 'complex':104,135,138,182 'compon':21,110,247,270,306,335,384,419,436,490,527,538,558,624,668,673,683,767,785 'condit':233 'consist':427 'const':462,534,717,722,726,735 'content':751 'contract':814 'convers':802 'core':212 'correct':832,842 'cost':163,184 'coupl':274 'creat':20,305,377 'createfilerout':536 'criteria':928 'cro':799 'cross':272 'cross-featur':271 'crumb':541 'customappbar':675 'data':31,71,141,228,248,315,353,471,727 'data-fetch':227 'debounc':625 'default':84,222,366,456,611,753 'defin':87,407 'deriv':447,615 'describ':880,896 'design':294,793 'dev':3,302,811 'develop':33 'dialog':253 'dimens':117,120 'disciplin':80 'discourag':434 'doctrin':214,473 'domain':261 'drill':772 'earli':236,355,592,761,837 'early-return':235 'editor':251 'effect':630 'enabl':643 'enforc':855 'engin':10,48 'entri':246,398 'environ':908 'environment-specif':907 'error':586,817 'error-track':816 'event':807 'excel':194 'execut':875 'expens':614 'expert':913 'explicit':283,339,647,840 'export':367,394,457,533,716,752 'feasibl':103,115 'featur':26,74,113,129,245,258,265,273,311,375,378,380,397,404,421,494,504,657,663,666,730,764,833 'feature-bas':73,128,257 'feature-nam':379 'featureapi':702 'featureapi.getfeature':733 'featuredata':707 'feedback':373,600 'fetch':28,72,229,312,472,487 'ffci':106,116,177,189,828 'file':502,660 'final':826 'first':39,70,292,479 'first-class':291 'fit':123,179 'folder':520 'folder-bas':519 'forbidden':276,482 'formula':176 'frontend':2,9,32,47,89,102,301,328,792 'frontend-design':791 'frontend-dev-guidelin':1,300 'goal':57 'grade':42 'grid':249,560,565,571 'guidelin':4,34,303,812 'handl':587 'handleact':736 'handler':357,451,619 'hard':165 'heavi':243,622 'heavycompon':463 'helper':386,670 'hierarchi':801 'hook':230,385,445,669,775 'horizon':866 'id':712,720,731,734 'immedi':759 'implement':108 'implicit':645 'import':286,411,429,465,686,692,697,701,705 'index':105 'index.ts':396,672 'index.tsx':680 'inlin':362,506,549,554,776 'input':922 'insid':489 'instead':773 'instrument':808 'integr':787 'intend':856 'interact':143 'interfac':341,653,710 'interpret':188 'introduc':149 'isload':232,484 'isol':390 'issu':324 'jsdoc':650 'larg':252 'layer':389,496,498 'layout':800 'lazi':240,342,399,458,524,843 'leak':633 'level':405,432 'librari':608 'limit':884 'line':365,553,557 'live':263,268 'load':136,241,343,400,459,525,585,762,844 'loader':531,540,593 'logic':144,262,488,765,803 'long':863 'long-term':862 'maintain':64 'mainten':162,183,865 'manual':485 'match':893 'md':569,574 'mean':190 'mere':95 'metadata':529 'miss':930 'modal':255 'mode':642 'model':134 'modif':161 'month':174 'mui':321,547 'mui/material':696 'multipl':781 'must':91,424,578 'mutat':30,314 'my-featur':664 'my-rout':677 'mycompon':718,754 'mycomponentprop':711 'mypag':539 'name':381 'negoti':217 'never':590 'new':25,310,334,374 'non':216,346 'non-negoti':215 'non-trivi':345 'number':713 'observ':820 'onact':714,721,740,741 'one':431,500,784 'oper':11,49,822 'opinion':853 'order':440 'organ':77,260 'output':902 'overview':883 'p':745,749 'page':23,111,308,798 'page-cro':797 'paper':694,747 'parti':606 'pass':618 'path':415 'pattern':460,475,483,758 'per':503 'perform':16,54,82,145,181,323,610,634,846 'performance-saf':81 'permiss':923 'poor':209 'predict':62 'prefix':511 'primari':226,474 'primit':267 'proceed':195,199 'product':41,858 'production-grad':40 'prop':340,443,771 'public':393,652 'pure':623 'queryfn':732 'querykey':729 'question':121 'quick':331 'rang':185 'react':35,65,687,691,859 'react.fc':337,719 'react.lazy':464 'react.memo':620 'reason':170 'redesign':210 'refactor':327 'regress':635 'reject':760 'relat':428 'reli':595 'render':150,454 'requir':413,438,921 'respect':835 'respons':481,780,782 'return':237,284,356,591,648,742,763,838 'reus':159 'reusabl':155,180,266 'review':325,914 'risk':146,154 'riski':204 'rout':244,318,406,409,513,515,522,526,535,543,676,679 'router':518 'rule':499,589 'runtim':819 'safe':83,583,847 'safeti':924 'scalabl':61 'scope':895 'score':175 'search':626 'senior':8,46 'separ':551 'set':316 'setstat':724,738 'share':768 'simplifi':205 'size':566 'skill':86,790,849,871,887 'skill-frontend-dev-guidelines' 'source-sickn33' 'specif':909 'spinner':238,486 'split':207 'src':416,662 'src/components':420 'src/features':422 'src/types':418 'stabl':852 'standard':17,55,437,516,546,640 'start':332 'state':140,723,769 'status':850,851 'stop':915 'strict':13,51,78,280,641 'structur':131,439,661 'style':319,361,545 'styles.ts':559 'subdir':382 'substitut':905 'success':927 'suspens':38,69,133,219,401,597,830 'suspense-first':37,68 'suspenseload':674 'sx':555,744,748 'syntax':561 'system':795 'tanstack':517 'tanstack/react-query':700 'task':891 'templat':684 'term':864 'test':911 'theme':576 'third':605 'third-parti':604 'toast':607 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'track':806,818 'treat':900 'trivial':347 'ts':461,532,685 'tsx':564 'type':285,287,289,387,417,442,480,582,649,654,671,706,839 'type-saf':581 'types/feature':709 'typescript':36,79,278,639 'untyp':779 'updat':739 'use':18,67,298,299,350,370,426,831,857,869,885 'usecallback':360,452,616,689,737 'usememo':449,612 'usemuisnackbar':371,601 'user':599 'usest':688,725 'usesuspensequeri':223,351,476,698,728 'v7':548,562 'valid':823,910 'valu':448 'via':395,530,770 'visual':794 'void':715 'vs':550 'without':160,493 'workflow':877 'wrap':348,358,468 'written':93,100 'xs':567,572","prices":[{"id":"fd9266e5-d37c-459a-b702-15bf3e57c3db","listingId":"5df7ddbb-4970-4044-a17a-f743ca4309a4","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:34:55.137Z"}],"sources":[{"listingId":"5df7ddbb-4970-4044-a17a-f743ca4309a4","source":"github","sourceId":"sickn33/antigravity-awesome-skills/frontend-dev-guidelines","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/frontend-dev-guidelines","isPrimary":false,"firstSeenAt":"2026-04-18T21:37:39.482Z","lastSeenAt":"2026-05-18T18:51:05.442Z"},{"listingId":"5df7ddbb-4970-4044-a17a-f743ca4309a4","source":"skills_sh","sourceId":"sickn33/antigravity-awesome-skills/frontend-dev-guidelines","sourceUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/frontend-dev-guidelines","isPrimary":true,"firstSeenAt":"2026-04-18T20:34:55.137Z","lastSeenAt":"2026-05-07T22:40:40.325Z"}],"details":{"listingId":"5df7ddbb-4970-4044-a17a-f743ca4309a4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"frontend-dev-guidelines","github":{"repo":"sickn33/antigravity-awesome-skills","stars":37911,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-05-18T08:24:49Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"653b50dfd507ab52e2fbff6a6995749affc6d055","skill_md_path":"skills/frontend-dev-guidelines/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/frontend-dev-guidelines"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"frontend-dev-guidelines","description":"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."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/frontend-dev-guidelines"},"updatedAt":"2026-05-18T18:51:05.442Z"}}