| name | frontend-engineer |
|---|---|
| description | Execution model for the Message Gateway Portal (Vite/React/TypeScript). Use for frontend/, Storybook, shadcn/ui, and docs/frontend — guides humans and AI agents (phases, boundaries, verification, output). |
This document is both a team playbook and an operational contract for anyone (including agents) changing the Portal under frontend/. It demands the mindset and restraint of a Principal UI Engineer who rejects generic aesthetics in favor of deliberate, production-grade output.
It complements conventions.md, frontend/README.md, and shadcn/SKILL.md.
Agent skills (load both for frontend work):
- typescript-react-reviewer — React 19 + component review + overlay — skills.sh/dotneet/claude-code-marketplace/typescript-react-reviewer
- typescript-advanced-types — API unions, DTOs, generics + overlay — skills.sh/wshobson/agents/typescript-advanced-types
- software-architecture — feature-sliced boundaries + overlay — skills.sh/sickn33/antigravity-awesome-skills/software-architecture
For non-trivial tasks (new feature slice, API wiring, component API changes, routing), follow this sequence:
Before writing any code, establish a BOLD point-of-view:
- Visual thesis: One sentence describing mood and tone. Reject generic "AI slop."
- Content plan: What is the singular job of this view? Keep copy extremely sparse.
- Interaction thesis: 1-2 intentional UI motions (via Framer Motion) that change the feel of the page while maintaining clarity.
- Read
app/, affectedfeatures/,core/, andcomponents/before editing. - Map user intent, data flow (API → state → UI), routing, and feature boundaries.
- List files to touch and why (minimal set).
- Outline Performance & Composition Hooks: Memoization (
useMemo/React.memo), component lifecycle, and code isolation boundaries. - Note Storybook, tests, and security (tokens, user input).
- Execute with restraint. Default toward typography, spacing, and bold contrast.
- Follow conventions.md and architecture.md (barrels,
*.api.ts, shadcn).
Run verification.md:
- Fast lint on touched frontend paths
-
/smell develop— no BLOCKER/HIGH on the diff -
make auditpasses from repo root - No cross-feature imports (maintain DDD isolation)
- Accessible markup: focus traps,
aria-*, keyboard navigation - Storybook updated for visual assertions
See architecture.md for the layer diagram, ESLint boundaries, and how to add features.
| Layer | Responsibility |
|---|---|
src/core/ |
HTTP client, React Query, router/ (ROUTES + route tree) |
src/features/<name>/ |
Pages, layouts, hooks, *.api.ts, *.types.ts, index.ts barrel |
src/shared/ |
Generic layouts/UI — no feature imports |
src/components/ui/ |
shadcn primitives |
src/app/ |
Bootstrap helpers (e.g. home redirect) |
src/lib/ |
Utilities |
Compose features in core/router/router.tsx only — not by importing feature A from feature B.
Ship interfaces that feel deliberate, premium, and current (e.g., Linear-style restraint):
- Start with composition, not components. Prefer full-bleed layouts, generous whitespace, and sharp alignment.
- No cards by default. If a layout works as plain text hierarchy, remove the card border. Avoid mosaic "dashboard-card" soup.
- Reject overused AI aesthetics. Avoid clichéd purple gradients on white backgrounds and uninspired floating components.
- Sparse, utility-driven typography. Treat the first view as a poster. If 30% of the copy can be deleted without losing meaning, delete it.
- Motion must be intentional. Exclude decorative motion noise. Use it for section reveals, shared layout transitions, and context persistence.
- Composition Over Inheritance: Avoid "God components" with 20 configure props. Use Compound Components (e.g.,
<Tabs><TabList><Tab/></TabList></Tabs>). - Code Splitting & Lazy Loading: Use
lazy()and<Suspense>to separate heavy charts, 3D backgrounds, or complex below-the-fold interactions. - Virtualization: Use tools like
@tanstack/react-virtualfor data tables or infinite feeds that exceed 50+ rows to maintain 60FPS scrolling. - Decoupled Data Flow: Create pure presentation components fed by custom data-fetching hooks (e.g.,
useMarketsQuery) or generalized state wrappers (e.g.,useToggle,useDebounce).
- shadcn/SKILL.md and
shadcn/rules/are the absolute contract for styling, forms, and composition. - Do not guess APIs: Use
npx shadcn@latest info. - Incorporate upstream components cleanly via the CLI using
--dry-runand--diffchecks for local overwrites. - Canonical docs: ui.shadcn.com/docs — Installation Guide
- Semantic tokens exclusively: Use
bg-backgroundandtext-muted-foregroundincn()strings over rawbg-gray-900.
- Auth: Never log or commit tokens. Rely entirely on
core/api/clientlogic to hydrateAuthorizationheaders. - XSS: Rely on React’s default escaping; avoid
dangerouslySetInnerHTML. - Env: Do not embed secrets in client bundles.
- Stories:
src/components/**/*.stories.tsx, foundations:src/stories/. - Update stories in the same PR when component structural changes occur.
- Run
make auditto implicitly ensurenpm run build-storybookvalidates successfully.
- AI Aesthetic Slop: Defaulting to Inter/Roboto, arbitrary shadow blobs, and repeating generic "SaaS card grid" impressions.
- Cross-feature imports to “save a line” — directly couples execution.
- Space-y/Space-x hacks: Using
space-x-4instead offlex gap-4. Avoid at all costs. - God Props:
export function Card({ title, subtitle, image, footer, actions ... })instead of pure composition. - Prop-drilled callbacks everywhere instead of Context/Reducer or centralized Zustand stores.
- Simpler over clever.
- Explicit composition over implicit prop configuration.
- Local (feature-scoped) states over global wrappers.
- Temporary duplication over wrong abstractions.
Prefer frameworks and visual rules that stay bold, intentional, and easy to alter. Precision always outperforms excessive decoration.
| Doc | Link |
|---|---|
| Architecture (layers, routing) | architecture.md |
| Portal README (scripts) | frontend/README.md |
| Conventions | conventions.md |
| Doc index | README.md |
| shadcn skill | shadcn/SKILL.md |