OpenTeams Frontend Development

Conventions and patterns for the OpenTeams frontend stack. Follow these when building or changing any React frontend in this org. To scaffold a brand-new project, use the new-project skill instead — this skill governs ongoing development.

The Stack

First Moves In Any Project

Before writing code, confirm what the project actually uses — conventions below are the org default, but a given repo may differ. Check, in order:

1. package.json — scripts, deps, package manager, React/Router/Tailwind versions.
2. biome.json — formatter + lint settings. If absent, the repo may still be on ESLint (older projects); match what's there, don't force a migration unasked.
3. components.json — shadcn style, baseColor, aliases, icon library.
4. vite.config.ts — @tailwindcss/vite plugin ⇒ Tailwind v4; tailwind.config.ts + postcss ⇒ Tailwind v3.
5. src/index.css / globals.css — color tokens and theme.
6. The existing folder layout — mirror it. Match the surrounding code's idioms over these defaults when they conflict.

Non-Negotiables

• Semantic color tokens only. bg-background text-foreground, never bg-white text-gray-900. This is what makes dark mode work.
• Never hand-edit src/components/ui/. Those are shadcn-generated. Add via npx shadcn@latest add <component>. To customize, wrap or extend — don't edit in place.
• Server state lives in TanStack Query, not Jotai. Never copy API data into an atom.
• No any. Use real types or unknown + narrowing.
• Co-locate tests next to the code (Foo.tsx ⇄ Foo.test.tsx).
• Run the quality gate before declaring done: npm run build && npm run test -- --run && npm run check (Biome check = format + lint + import-organize).

Folder Structure

Components and pages each get a PascalCase directory with a barrel index.ts. Import from the folder, never the inner file.

src/
├── main.tsx
├── App.tsx
├── index.css            # Tailwind v4 entry + @theme tokens
├── lib/
│   ├── utils.ts         # cn()
│   └── api.ts           # fetch wrapper
├── store/               # all Jotai atoms
│   └── appAtoms.ts
├── hooks/               # useThing.ts — TanStack Query wrappers + custom hooks
├── components/
│   ├── ui/              # shadcn (generated — don't edit)
│   └── UserCard/
│       ├── UserCard.tsx
│       ├── UserCard.test.tsx
│       └── index.ts
├── pages/
│   └── Home/
│       ├── Home.tsx
│       ├── Home.test.tsx
│       └── index.ts
└── providers/
    └── ThemeProvider/

import UserCard from "@/components/UserCard";   // ✅ from the folder
import UserCard from "@/components/UserCard/UserCard";  // ❌ inner file

Naming

Reference Files

Read the relevant reference before doing that kind of work — they contain the canonical code patterns:

• references/styling.md — Tailwind v4 setup, semantic tokens, cn(), CVA component variants, dark mode, adding shadcn components.
• references/state-and-data.md — TanStack Query hook patterns, Jotai atoms, the server-vs-client-state decision table, the api.ts wrapper.
• references/components-and-testing.md — component file template, the barrel pattern, Vitest + Testing Library patterns (Router/Query wrappers), what to test.
• references/quality.md — Biome config + commands, the quality-gate workflow, TypeScript strictness, common Biome rule fixes.

What NOT To Do