factory-frontend-engineer

Apply the frontend-engineer specialist workflow. Scaffold UI surfaces grounded in the factory's CRUD conventions, not generic React. Load factory-frontend, factory-design, and factory-stack through the host's skill capability when needed. factory-design owns visual coherence; factory-frontend owns CRUD shape.

How to think (in order)

1. What surface is this? Restate the request in one sentence. Pick one:

   • List (queue of entities; filter/sort/paginate)
   • Detail (one entity's full view)
   • Form (create/edit, including multi-step)
   • Dashboard (rollup/chart heavy)
   • Hybrid — name it and split into two surfaces if you can.

2. Is this CRUD? If yes, the default shape is DataTable + drawer with mode union. Don't deviate without naming why. The drawer mode is the tagged union {kind:'closed'}|{kind:'create'}|{kind:'edit'; entity}. The drawer edits only the clicked target; relations open their own drawers.

3. Which component library? Check the project's CLAUDE.md or DECISIONS.md. If unset:

   • Mantine when CRUD-heavy / internal tool / form-table dense. Pair with @mantine/form + schemaResolver.
   • shadcn when there's a marketing site, design flexibility matters, or Tailwind muscle memory dominates. Pair with react-hook-form + zodResolver.
   • Flag the choice in your output if you had to make it.

4. What primitives already exist? Before writing anything new, check:

   • src/components/datatable/ — DataTable, RowActions, ColumnDef, ValidationRules
   • src/lib/format.ts — formatCurrency, formatInteger, formatPercent
   • src/components/PageHeader.tsx / CardHeader.tsx / FormSection.tsx — heading tiers
   • src/features/<sibling>/ — peer feature folders for the colocated shape
   • If a primitive is missing where it should exist, create it first — don't inline. Single source.

5. What's the schema shape? Three Zod variants for a CRUD entity:

   • Input schema — server-side strict (UUIDs are UUIDs, no empty strings)
   • Form schema — client-side lenient (empty-string defaults, nullable().or(literal('')))
   • Patch schema — partial input for updates (input.partial() or .pick({}) per field)
   • All three live in features/<entity>/schema.ts.

6. What's the data path? Default: server action wrapped by TanStack Query mutation. tRPC only if the project already commits to it.

   • Action in features/<entity>/actions.ts with "use server" directive
   • Hook in features/<entity>/hooks.ts wrapping the action with useMutation
   • Query keys: ['entity', 'list', filters] / ['entity', 'detail', id]
   • Invalidate at ['entity'] after mutations.

7. What conventions must hold?

   • Semantic tokens only — consume named tokens (bg, surface, fg, fg-muted, accent, border, etc. — see factory-design.md). No hex literals in components, ever. No dark: variants on individual elements — let CSS-var swap handle modes.
   • Format helpers from src/lib/format.ts — never inline currency math.
   • Tier components — PageHeader / CardHeader / FormSection. Never freeform <h1>/<h2>.
   • Empty + error + loading states — required, not optional.
   • Feature folders are peers — code in features/cases/ doesn't import from features/products/. Shared logic goes to lib/.

8. What's the smallest correct change? If asked for a table, build the table — don't redesign the whole space. If a change implies redesigning something else, name it and stop.