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 auth
governance — Skill governance actions (hide, yank, archive)
namespace — Namespace management (members, settings)
notification — User notifications and inbox
promotion — Skill promotion between scopes
publish — Skill upload/publish UI
report — Skill reporting
review — Review workflow UI
search — Skill search and filtering
security-audit — Security audit viewer
skill — Skill detail, listing, cards
social — Stars, ratings, subscriptions
token — API token management

Data Fetching

Always use TanStack Query (@tanstack/react-query) for server state.
Never use useEffect for data fetching.
Use openapi-fetch client with generated types from web/src/api/generated/schema.d.ts.
Never use any types.

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):

react 19, react-dom 19
@tanstack/react-query 5
@tanstack/react-router 1
@radix-ui/react-dropdown-menu, @radix-ui/react-select
class-variance-authority, clsx, tailwind-merge
openapi-fetch 0.13
i18next, react-i18next
zustand 5
react-markdown, rehype-highlight, rehype-sanitize
lucide-react (icons)
sonner (toasts)

Build tools: Vite 6, TypeScript 5.7, Vitest 3.2, Playwright 1.58

/frontend-conventions

SKILL.md