--- description: "KubeStellar Console — Multi-cluster Kubernetes dashboard development rules" globs: **/*.tsx, **/*.ts, **/*.go, web/src/**/*.ts, web/src/**/*.tsx, pkg/**/*.go, cmd/**/*.go alwaysApply: false ---

KubeStellar Console Development Rules

Project Structure

• Frontend: React + TypeScript in `/web/`
• Backend: Go (Fiber v2) in root directory
• Build: `cd web && npm run build && npm run lint` before every commit
• Cards: Dashboard card components in `web/src/components/cards/`
• Hooks: Data fetching hooks in `web/src/hooks/`

Card Development

• All data fetching MUST go through `useCache`/`useCached*` hooks
• Always destructure and pass `isDemoData` and `isRefreshing` to `useCardLoadingState()`
• Never use demo data during loading: `isDemoFallback && !isLoading`
• Hook ordering: `useCardLoadingState` AFTER hooks providing `isDemoData`

Array Safety

• NEVER call `.join()`, `.map()`, `.filter()`, `.forEach()`, `for...of` on values that might be undefined
• Always guard: `(data || []).map(...)` or `(data || []).join(', ')`

No Magic Numbers

• Numeric literals should be named constants, except trivial literals (`0`, `1`, `-1`) in clear local contexts
• Use constants from `lib/constants/` (time.ts, network.ts, ui.ts)

Styling

• Tailwind CSS with `cn()` utility for merging classNames
• Never use raw hex colors — use semantic Tailwind classes (`text-foreground`, `bg-primary`, `bg-card`)
• Status colors: `text-green-400`/`bg-green-500/10` (success), `text-yellow-400`/`bg-yellow-500/10` (warning), `text-red-400`/`bg-red-500/10` (error), `text-cyan-400`/`bg-cyan-500/10` (info) — these map to the design system's semantic status tokens and are the only permitted palette classes

Internationalization

• All user-facing strings use `t()` from `react-i18next`
• Keys in `web/src/locales/en/` JSON files
• Never use raw strings for UI text

Go Backend

• Fiber v2 handlers: `func(c *fiber.Ctx) error`
• Use `fiber.NewError(statusCode, message)` for errors
• Always `make([]T, 0)` not `var x []T` (nil → null in JSON)
• Use `log/slog` for structured logging
• Multi-cluster queries use goroutines + sync.WaitGroup

Cluster Deduplication

• Always use `DeduplicatedClusters()` when iterating clusters
• Multiple kubeconfig contexts can point to same physical cluster