Frontend Conventions
Developmentfrontend-conventionsFrontend Conventions is an Agent Skill for development published in the iflytek/skillhub repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Coding conventions, architecture patterns, and testing rules for the SkillHub React frontend. Ensures agents follow Feature-Sliced Design and use the generated OpenAPI types.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/iflytek/skillhub/blob/HEAD/.agents/skills/frontend-conventions/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/frontend-conventions, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Frontend Conventions Skill
Trigger
Use this skill when:
- Adding or modifying React/TypeScript frontend code
- Creating new pages, features, entities, or shared components
- Changing API client calls or data fetching patterns
Rules
Feature-Sliced Design
Place code at the lowest appropriate layer:
| Layer | Path | Purpose |
|---|---|---|
| Pages | web/src/pages/ | Route-level page components |
| Features | web/src/features/ | Business features (search, upload, review, etc.) |
| Entities | web/src/entities/ | Domain entity display logic (skill, user, namespace) |
| Shared | web/src/shared/ | Reusable UI components, hooks, utilities |
Current features:
admin— Admin panel (user management, labels, search)auth— Login, OAuth flows, device authgovernance— Skill governance actions (hide, yank, archive)namespace— Namespace management (members, settings)notification— User notifications and inboxpromotion— Skill promotion between scopespublish— Skill upload/publish UIreport— Skill reportingreview— Review workflow UIsearch— Skill search and filteringsecurity-audit— Security audit viewerskill— Skill detail, listing, cardssocial— Stars, ratings, subscriptionstoken— API token management
Data Fetching
- Always use TanStack Query (
@tanstack/react-query) for server state. - Never use
useEffectfor data fetching. - Use
openapi-fetchclient with generated types fromweb/src/api/generated/schema.d.ts. - Never use
anytypes.
State Management
- TanStack Query for server state (API data, caching, invalidation, optimistic updates)
- Zustand for local/UI state (theme, sidebar, modals, form state)
Component Composition
- Radix UI primitives:
@radix-ui/react-dropdown-menu,@radix-ui/react-select - class-variance-authority (cva) for component variants
- clsx + tailwind-merge for class merging
cn()utility:web/src/shared/lib/utils.ts- shadcn/ui is NOT used as a library
API Type Generation
When backend OpenAPI contracts change:
make generate-api
This runs openapi-typescript http://localhost:8080/v3/api-docs -o src/api/generated/schema.d.ts.
Commit the updated web/src/api/generated/schema.d.ts with the PR.
To verify the generated file is not stale:
./scripts/check-openapi-generated.sh
Styling
- Tailwind CSS for all styling
cn()utility for conditional class merging- Follow existing component patterns in
web/src/shared/components/
Internationalization
- i18next + react-i18next for translations
- All user-facing text must be translatable
- Translation keys in
web/src/i18n/
Build & Development
make dev-web # Start Vite dev server (HMR enabled)
make build-frontend # Production build
make typecheck-web # TypeScript type check (tsc --noEmit)
make lint-web # ESLint check
make test-frontend # Vitest unit tests
make test-e2e-frontend # Playwright E2E tests
make test-e2e-smoke-frontend # Playwright smoke tests
Vite HMR is enabled by default — save a file and the browser updates instantly.
Frontend Dependencies
Key dependencies (from web/package.json):
react19,react-dom19@tanstack/react-query5@tanstack/react-router1@radix-ui/react-dropdown-menu,@radix-ui/react-selectclass-variance-authority,clsx,tailwind-mergeopenapi-fetch0.13i18next,react-i18nextzustand5react-markdown,rehype-highlight,rehype-sanitizelucide-react(icons)sonner(toasts)
Build tools: Vite 6, TypeScript 5.7, Vitest 3.2, Playwright 1.58