docs: add frontend developer documentation (#6486)

Co-authored-by: kyle-ssg <kyle@solidstategroup.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Kim Gustyr <khvn26@gmail.com>
Co-authored-by: Kim Gustyr <kim.gustyr@flagsmith.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Matthew Elwell <matthew.elwell@flagsmith.com>
Co-authored-by: Talisson <talisson.odcosta@gmail.com>

Author: 7 people

frontend/.claude/commands/api.md

@@ -0,0 +1,12 @@
+---
+description: Generate a new RTK Query API service
+---
+
+<!-- TODO: Update /api-types-sync once OpenAPI schema is ready -->
+
+Generate a new API service. Follow these steps:
+
+1. Go through the process mentioned in `.claude/context/api-integration.md`
+2. If I haven't specified, attempt to find where I'd want to create this component in the frontend
+
+Context file: `.claude/context/api-integration.md`

frontend/.claude/commands/backend.md

@@ -0,0 +1,14 @@
+---
+description: Search the backend codebase for endpoint details
+---
+
+Search the `../api` codebase for the requested endpoint.
+
+Look for:
+1. Route definitions (URL path)
+2. HTTP method (GET, POST, PUT, DELETE)
+3. Request validation schema (request body/params types)
+4. Response structure (what data is returned)
+5. Authentication/authorization requirements
+
+If the endpoint isn't found, check swagger docs: https://staging.flagsmith.com/api/v1/docs/

frontend/.claude/commands/check-staged.md

@@ -0,0 +1,8 @@
+---
+description: Run type checking and linting on staged files
+---
+
+Run TypeScript checking and linting on all currently staged files, similar to pre-commit hooks. Steps:
+1. Run `npm run check:staged` to typecheck and lint only staged files
+2. Report any type errors or linting issues found
+3. If errors exist, offer to fix them

frontend/.claude/commands/check.md

@@ -0,0 +1,9 @@
+---
+description: Run type checking and linting
+---
+
+Run the following checks on the codebase:
+
+1. `npx lint-staged --allow-empty` - Fix linting issues on staged files only (same as git hook)
+
+Report any errors found and offer to fix them.

frontend/.claude/commands/context.md

@@ -0,0 +1,12 @@
+---
+description: Load detailed context files for specific topics
+---
+
+Available context files in `.claude/context/`:
+
+1. **api-integration.md** - API integration workflow, Redux setup, cross-platform patterns
+2. **architecture.md** - Environment config, tech stack, additional rules
+3. **feature-flags/** - Flagsmith feature flags (usage + MCP workflows)
+4. **patterns/** - Code patterns (API, mobile)
+
+Which context would you like to explore?

frontend/.claude/commands/feature-flag.md

@@ -0,0 +1,5 @@
+---
+description: Create a feature flag
+---
+
+1. Create a feature flag using the context defined in `.claude/context/feature-flags/`

frontend/.claude/commands/find-usages.md

@@ -0,0 +1,62 @@
+---
+description: Find all usages of a component, function, or type
+---
+
+Find all usages of `$ARGUMENTS` across the frontend codebase.
+
+## Steps
+
+1. **Identify what we're searching for**
+   - Component name (e.g., `Switch`, `Button`)
+   - Function name (e.g., `isFreeEmailDomain`, `formatDate`)
+   - Type/interface name (e.g., `FeatureState`, `ProjectFlag`)
+
+2. **Find the definition**
+   - Search for where it's defined/exported
+   - Note the file path and export type (default vs named)
+
+3. **Search for imports**
+   ```bash
+   # For named exports
+   grep -r "import.*{ $SYMBOL" --include="*.ts" --include="*.tsx"
+
+   # For default exports
+   grep -r "import $SYMBOL" --include="*.ts" --include="*.tsx"
+   ```
+
+4. **Search for direct usages**
+   - JSX usage: `<ComponentName`
+   - Function calls: `functionName(`
+   - Type annotations: `: TypeName` or `as TypeName`
+
+5. **Categorise usages**
+   - Group by file/directory
+   - Note the context (component, hook, utility, test)
+
+## Output format
+
+```
+## Definition
+[File path where it's defined]
+
+## Usages (X files)
+
+### components/
+- ComponentA.tsx:42 - Used in render
+- ComponentB.tsx:15 - Passed as prop
+
+### pages/
+- FeaturePage.tsx:88 - Used in modal
+
+### hooks/
+- useFeature.ts:12 - Called in effect
+
+## Impact Assessment
+[Brief note on how widespread the usage is and what to consider when modifying]
+```
+
+## Use cases
+
+- Before refactoring: understand what will be affected
+- Before deleting: ensure nothing depends on it
+- Before renaming: find all places that need updates

frontend/.claude/commands/pr-review.md

@@ -0,0 +1,56 @@
+---
+description: Review a GitHub pull request
+---
+
+Review the pull request at `$ARGUMENTS`.
+
+## Steps
+
+1. **Fetch PR details**
+   ```bash
+   gh pr view <PR_NUMBER_OR_URL> --json title,body,files,additions,deletions,state,headRefName
+   ```
+
+2. **Get the diff**
+   ```bash
+   gh pr diff <PR_NUMBER_OR_URL>
+   ```
+
+3. **Analyse the changes**
+   - Summarise what the PR does
+   - Check if the approach makes sense
+   - Identify potential issues:
+     - Missing edge cases
+     - Inconsistencies with existing patterns
+     - Code style issues (indentation, naming)
+     - Missing tests for new functionality
+   - Check if related files need updates
+
+4. **Review against project patterns**
+   - Does it follow patterns in `.claude/context/`?
+   - Are imports using path aliases (`common/`, `components/`)?
+   - Is state management using RTK Query where appropriate?
+
+5. **Provide feedback**
+   - Summary of what the PR does
+   - What's good about the approach
+   - Potential concerns or suggestions
+   - Questions for the author (if any)
+
+## Output format
+
+```
+## PR Summary
+[Brief description of what the PR does]
+
+## Changes
+[List of files changed and what each change does]
+
+## Assessment
+✅ What looks good
+⚠️ Potential concerns
+💡 Suggestions
+
+## Questions
+[Any clarifying questions for the author]
+```

frontend/.claude/commands/ui-patterns.md

@@ -0,0 +1,47 @@
+# UI Patterns & Best Practices
+
+## Confirmation Dialogs
+
+**NEVER use `window.confirm`** - Always use the `openConfirm` function from `components/base/Modal`.
+
+### Correct Usage
+
+```typescript
+import { openConfirm } from 'components/base/Modal'
+
+// Signature: openConfirm(title, body, onYes, onNo?, challenge?)
+openConfirm(
+  'Delete Partner',
+  'Are you sure you want to delete this partner?',
+  async (closeModal) => {
+    const res = await deleteAction()
+    if (!res.error) {
+      toast(null, 'Partner deleted successfully')
+      closeModal() // Always call closeModal to dismiss the dialog
+    }
+  },
+)
+```
+
+### Parameters
+- `title: string` - Dialog title
+- `body: ReactNode` - Dialog content (can be JSX)
+- `onYes: (closeModal: () => void) => void` - Callback when user confirms
+- `onNo?: () => void` - Optional callback when user cancels
+- `challenge?: string` - Optional challenge text user must type to confirm
+
+### Key Points
+- The `onYes` callback receives a `closeModal` function
+- Always call `closeModal()` when the action completes successfully
+- Can be async - use `async (closeModal) => { ... }`
+
+## Backend Integration
+
+### Always Run API Types Sync Before API Work
+
+When using `/api` to generate new API services, the command automatically runs `/api-types-sync` first to:
+1. Pull latest backend changes (`git pull` in `../api`)
+2. Sync frontend types with backend serializers
+3. Ensure types are up-to-date before generating new services
+
+This prevents type mismatches and ensures consistency.

frontend/.claude/commands/unit-test.md

@@ -0,0 +1,61 @@
+---
+description: Analyse a frontend file and generate unit tests (Jest)
+---
+
+Generate unit tests for the frontend file at `$ARGUMENTS`.
+
+**Note:** This command is for frontend code only. For backend (Python) tests, see `../api/README.md`.
+
+## Steps
+
+1. **Check for existing tests**
+   - Look for `__tests__/{filename}.test.ts` in the same directory
+   - If tests exist, analyse them for coverage gaps
+
+2. **Read and analyse the source file**
+   - Identify all exported functions, classes, and constants
+   - Note dependencies and imports
+   - Determine testability:
+     - Pure functions (no side effects) → highly testable
+     - React components → may need mocking
+     - Functions with external dependencies → note what needs mocking
+
+3. **Generate test file**
+   - Follow the pattern in `common/utils/__tests__/format.test.ts`
+   - Location: `{sourceDir}/__tests__/{filename}.test.ts`
+   - Use path aliases for imports (`common/...`, `components/...`)
+
+4. **Test structure requirements**
+   - Use `describe` block for each exported function
+   - Use `it.each` for table-driven tests when function has multiple input/output cases
+   - Include edge cases: `null`, `undefined`, empty strings, empty arrays
+   - Include boundary cases where applicable
+
+5. **After generating, run the tests**
+   ```bash
+   npm run test:unit -- --testPathPatterns={filename}
+   ```
+
+## Test file pattern
+
+```typescript
+import { functionName } from 'common/path/to/file'
+
+describe('functionName', () => {
+  it.each`
+    input        | expected
+    ${value1}    | ${result1}
+    ${value2}    | ${result2}
+    ${null}      | ${expectedForNull}
+    ${undefined} | ${expectedForUndefined}
+  `('functionName($input) returns $expected', ({ input, expected }) => {
+    expect(functionName(input)).toBe(expected)
+  })
+})
+```
+
+## Reference
+
+See existing tests at:
+- `common/utils/__tests__/format.test.ts`
+- `common/utils/__tests__/featureFilterParams.test.ts`