code-ui

# Code UI You are a UI coding agent. You write production-quality React/TypeScript code following Kumo conventions. ## Ownership Boundaries `/code-ui` owns: - implementation planning from the provided handoff - code edits and integration wiring - implementation-specific checks - targeted test design - initial diagnosis of failures introduced by the change `/code-ui` does not own: - deciding whether a ticket should proceed - approval checkpoints - PR creation decisions - overall workflow stop or continue policy - diff review standards ## Invocation ``` /code-ui <task-description> /code-ui add a new page for model comparison /code-ui add store for notification preferences /code-ui add test for useConnectorData hook ``` ## Step 0: Load Context **Always load:** - `docs/development/ui.md` — compressed coding conventions and recipes - `.agents/skills/code-ui/references/catalog-components.md` — available UI catalog components - `.agents/skills/code-ui/references/design-tokens.md` — color tokens, typography, Figma mapping - `.agents/skills/code-ui/references/integration-checklist.md` — integration and implementation checks **Load conditionally:** - If creating/modifying tests: `docs/development/ui-review-testing.md` - If creating/modifying tests: `.agents/skills/code-ui/references/testing-playbook.md` - If creating/modifying components or hooks: `docs/development/ui-review-react.md` - If touching Kumo-specific patterns (stores, API, navigation): `docs/development/ui-review-kumo.md` ## Step 1: Understand the Task Required outputs: - implementation plan - code changes aligned to the task - relevant integration updates - targeted validation results - explicit notes for any blocked or skipped verification 1. Parse the task description to determine what type of artifact is needed: - **page** — new route with lazy loading, loader, error boundary - **component** — new UI component with error boundary - **hook** — custom hook (data fetching, state logic, utility) - **store** — Zustand store with devtools + immer - **test** — test file for existing component/hook/store - **feature** — combination of the above 2. Identify which existing files need to be modified (routes, barrel exports, mock dispatch, test setup) 3. Check for existing patterns — search for similar components/hooks in the codebase to match local conventions ## Step 2: Check Prerequisites Before writing code: 1. **Check generated types**: Search `gen/v1/` first for relevant API types and hooks. If the endpoint isn't in `gen/v1/`, fall back to `gen/v0/` which has broader coverage. Use the generated hook — don't write manual axios calls. 2. **Check catalog**: Search catalog-components.md for UI primitives you need. Don't reimplement what exists. 3. **Check existing utils**: Search `utils/`, `hooks/`, `stores/` for helpers that already exist. Don't duplicate. 4. **Check query keys**: If adding data fetching, check `utils/reactQueryKeys.ts` for existing keys. Add new keys if needed. 5. **Check design tokens**: Load `references/design-tokens.md`. Never use generic Tailwind colors (`slate-*`, `gray-*`) — always map to Kumo tokens (`title-primary`, `border-secondary`, etc.). 6. **Check compiled CSS**: Before using a Tailwind class, verify it exists in the compiled bundle. Arbitrary values (`text-[26px]`, `gap-[36px]`) often don't compile in Tailwind v4. Use standard classes instead. ## Step 3: Implement Follow the recipes in `docs/development/ui.md` for each artifact type. Key rules: ### All Files - Absolute imports from `baseUrl: "src"` — never `../../../` - TypeScript strict mode — no `any` without justification - PascalCase component files, `use*` hooks, `on<Action><Event>` handlers ### Styling & Design Tokens - **Always use Kumo design tokens** — see `references/design-tokens.md` for the full mapping - `text-title-primary` / `text-title-secondary` — not `text-slate-800` / `text-slate-500` - `border-border-secondary` — not `border-slate-200` / `border-gray-300` - `bg-surface-grey` — not `bg-slate-100` - `var(--tooltip-dark)` for popover backgrounds — not `bg-gray-800` - `text-icon-secondary` for info icons — not `text-gray-400` - **Inline styles for values that Tailwind v4 won't compile** (arbitrary values, CSS variable references) - **Scoped `<style>` with `#id` selectors** to override shared component internals — don't modify shared components, don't rely on `[&_]` syntax - **Verify in browser** after styling changes — computed values may differ from class names due to Tailwind v4 JIT behavior ### Components - Wrap with `WithErrorBoundary` (or `WithErrorBoundaryForwardRef` for forwardRef) - Use catalog primitives from `@kumo-ai/kumo-ui-catalog` - Use `cn()` for conditional classes - Use Tailwind for layout — inline styles only when Tailwind classes don't compile - Extract business logic into hooks — components only render ### Pages - Use `createLazyModule()` pattern in `Routes.tsx` - Add `navRoutes` enum entry in `utils/Constants/routes.ts` - Add route loader in `Loaders.ts` with `prefetchGetXxx` - Use `useCustomNavigation()` — not raw `useNavigate()` - Guard dirty wizard forms on every exit path (`useBlocker` + `beforeunload`, reusing the cancel confirmation dialog); see `pages/NewJob/Training/Training.tsx` (kumo#30141) ### Hooks - Use Orval-generated hooks from `gen/v1/` for API calls - Use `ReactQueryKeys` enum for query keys - Use `handleErrorFunctional()` for error handling - Use `AbortController` or `isCancelled` ref for cleanup ### Stores - Middleware: `devtools(immer(...))` with `{ name: "StoreName" }` - Separate `StoreState` and `StoreActions` interfaces - Create selector hooks: `const useXxx = () => useStore((s) => s.xxx)` - Use `Promise.allSettled()` for parallel fetches - Use `logStackTrace()` — not `console.log` ### Tests - Import `"tests/mockAxios"` before test code - Use `createQueryClient()` and `createWrapper()` from `tests/testUtil` - Use `store.setState()` for Zustand — not `vi.mock()` - Use `mockNavigateCall()` and `mockLocationStateValue()` from `tests/mockRouter` - Use accessible queries (`getByRole`, `getByText`) — not `getByTestId` - Use `waitFor()` — not `setTimeout` - Render pages that call `useBlocker` inside a data router (`createMemoryRouter` + `RouterProvider`); plain `MemoryRouter` cannot host a blocker - Reuse helpers from `tests/testHelpers.ts` ### API Mocks - Add new endpoint mocks to `tests/mockAxios.ts` dispatch table - Follow existing URL-matching pattern ## Step 3a: Apply Integration Checks Use `references/integration-checklist.md`. This is where `/code-ui` owns: - shared primitive compatibility and caller updates - route, query, invalidation, and mock wiring - UI state coverage - copy consistency checks - incidental in-scope fixes while editing related files ## Step 4: Wire Up After implementing, don't forget integration points: - [ ] Add to barrel export (`index.ts`) if directory has one - [ ] Add route + lazy module + loader (for pages) - [ ] Add `navRoutes` enum entry (for pages) - [ ] Add `ReactQueryKeys` entry (for new data fetching) - [ ] Add invalidation helper in `queryInvalidation.ts` (for new mutations) - [ ] Add store reset in `tests/setup.ts` `beforeEach` (for new stores) - [ ] Add mock endpoints in `tests/mockAxios.ts` (for new API calls) ## Step 5: Validate Run validation after implementation: ```bash # Type check cd ui && npx tsc --noEmit # Lint cd ui && npm run lint # Run tests (specific file or all) cd ui && npx vitest run src/path/to/__tests__/MyFile.test.tsx cd ui && npm test ``` Fix any errors before considering the task complete. ## Step 6: Test Strategy Use `references/testing-playbook.md`. `/code-ui` owns: - targeted test design - test helper reuse - mock completeness for changed behavior - initial failure diagnosis during implementation ## Working with Figma Designs When a Figma URL or node ID is provided: ### Step 1: Fetch design specs via API ```bash curl -s -H "X-Figma-Token: $TOKEN" \ "https://api.figma.com/v1/files/$FILE_ID/nodes?ids=$NODE_ID&depth=10" ``` ### Step 2: Extract design tokens Parse the JSON for: `fills` (colors), `strokes` (borders), `style.fontSize`, `style.fontWeight`, `cornerRadius`, `itemSpacing` (gap), `paddingTop/Left/Right/Bottom`, `layoutMode`. ### Step 3: Map to Kumo tokens (CRITICAL) **Always use design tokens from `references/design-tokens.md`** — never hardcode Tailwind generic colors. | Figma Property | Map To | |---|---| | `fills.color rgb(41,45,54)` | `text-title-primary` | | `fills.color rgb(95,113,140)` | `text-title-secondary` | | `strokes.color rgb(210,220,228)` | `border-border-secondary` | | `fills.color rgb(244,246,248)` | `bg-surface-grey` | | `fills.color rgb(58,58,65)` | `var(--tooltip-dark)` | | `cornerRadius: 4` | `rounded` | | `cornerRadius: 16` | `rounded-2xl` | | `fontSize: 26` | `text-3xl` (NOT `text-[26px]`) | | `fontSize: 16` | `text-base` | | `fontSize: 14` | `text-sm` | | `fontWeight: 700` | `font-bold` | | `fontWeight: 500` | `font-medium` | | `itemSpacing: 4` | `gap-1` | | `itemSpacing: 8` | `gap-2` | | `itemSpacing: 16` | `gap-4` | | `itemSpacing: 24` | `gap-6` | | `itemSpacing: 32` | `gap-8` | | `padding: 16` | `p-4` | | `padding: 24` | `p-6` | ### Step 4: Verify in browser After implementing, use Chrome DevTools or MCP browser tools to verify: - Computed font sizes and colors match Figma - Gaps and padding match pixel values - Alignment between adjacent panels - Design token CSS variables resolve correctly ### Step 5: Verification checklist After implementing, verify each of these in the browser (Chrome DevTools or MCP tools): - [ ] All text uses `text-title-primary` / `text-title-secondary` — no hardcoded slate/gray - [ ] All borders use `border-border-secondary` — no hardcoded slate/gray - [ ] All tooltips/popovers use `var(--tooltip-dark)` bg, `text-sky-300` links, `size-3.5 text-icon-secondary` icons - [ ] Font sizes match Figma (use `getComputedStyle` to verify px values) - [ ] Gaps between elements match Figma `itemSpacing` values - [ ] Padding matches Figma `paddingTop/Left/Right/Bottom` - [ ] Adjacent panels align horizontally (titles at same Y, tab rows at same Y, underlines at same Y) - [ ] Active tab underlines sit ON TOP of separator lines (not above with a gap) - [ ] Shared components (TabCard) render without extra card chrome (border, shadow, padding) ### Tailwind v4 Gotchas - **Arbitrary values (`text-[26px]`, `gap-[36px]`) often don't compile.** Use standard Tailwind classes instead. - **`[&_selector]` descendant overrides may not work.** Use scoped `<style>` with `#id` selectors. - **New classes may need a page reload** to appear in the JIT bundle. - **When overriding shared components (TabCard, etc.)**, use scoped CSS with a wrapper `<div id="...">` + `<style>` tag rather than modifying the shared component. - **`border-r-0`, `rounded-l` may not apply via HMR.** Use inline styles for border-radius and selective borders when Tailwind classes don't take effect. ## Working with UI Catalog ### When to modify the catalog Modify the catalog when you need to: - Add a new reusable primitive or block component - Fix a bug in an existing catalog component - Add variants/props to an existing component Do NOT modify the catalog for: - One-off components specific to a single feature (put these in `ui/src/components/`) - Quick layout tweaks (use Tailwind overrides via `className` prop) ### In-tree catalog workflow The application consumes `packages/kumo-ui-catalog` through a local file reference. Read `packages/kumo-ui-catalog/CLAUDE.md` and its README, then change shared components and UI callers in this same repository. Validate the affected catalog stories/tests and UI integration. A separate repository, registry publication, or two-PR sequence is not a prerequisite. From the repository root, `npm --prefix ui run local:catalog` enables catalog source development with the configured local API. Continue importing catalog components through `@kumo-ai/kumo-ui-catalog`, not package-internal paths. ## Common Patterns Reference ### Error handling in a hook ```tsx import { handleErrorFunctional } from "utils/errorHandler"; import { logStackTrace } from "utils/errorHandler"; import type { AlertData, BannerData } from "types/validation"; const useMyHook = ( showBanner: (data: BannerData) => void, alertError: (data: AlertData) => void ) => { const doAction = async () => { try { await mutation.mutateAsync(params); } catch (e) { const error = e instanceof Error ? e : new Error(String(e)); handleErrorFunctional(error, showBanner, alertError); logStackTrace("doAction failed", error); } }; }; ``` ### Feature flag conditional ```tsx import useFeatureFlags from "hooks/utils/featureFlags"; const MyComponent = () => { const { IS_DATABRICKS_DEPLOY } = useFeatureFlags(); if (IS_DATABRICKS_DEPLOY) return <DatabricksView />; return <DefaultView />; }; ``` ### Storage access ```tsx import { storeToLocalStorage, getFromLocalStorage } from "@kumo-ai/kumo-ui-catalog"; import { storageKeys } from "utils/Constants/enums"; storeToLocalStorage(storageKeys.selectedProject, "project-id"); const projectId = getFromLocalStorage<string>(storageKeys.selectedProject); ``` ### Navigation ```tsx import { useCustomNavigation } from "utils/navigator"; import { navRoutes } from "utils/Constants/routes"; const MyComponent = () => { const navigate = useCustomNavigation();