设计与 UI
frontend-conventions
Coding conventions, architecture patterns, and testing rules for the SkillHub React frontend. Ensures agents follow Feature-Sliced Design and use the generated OpenAPI types.
iflytek · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add iflytek/skillhub --skill frontend-conventions技能说明
name: frontend-conventions description: Coding conventions, architecture patterns, and testing rules for the SkillHub React frontend. Ensures agents follow Feature-Sliced Design and use the generated OpenAPI types. license: Apache-2.0
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