frontend · diff
git:20260630.95d2bc8 to git:20261007.4c4eb8c
83 added, 65 removed. Audit A to A.
---
name: frontend
description: >-
- Frontend engineering audit for TypeScript, UI accessibility, Next.js
- boundaries, Tailwind/component patterns, and browser security. Use when
- reviewing .ts/.tsx/.jsx frontend code, designing UI components, checking
- type/runtime boundaries, handling XSS/CSP/token storage, or deciding frontend
- file structure. For React runtime/rendering pitfalls, use the react skill.
+ Frontend engineering for browser-facing applications: TypeScript trust
+ boundaries, semantic accessibility, UI systems, responsive browser behavior,
+ security, resilient user states, and feature ownership. Use when building or
+ auditing frontend contracts, styling infrastructure, browser integrations, or
+ file organization. Use react for React composition, state, effects, Suspense,
+ and rendering; use nextjs-app-architecture for Next.js-specific mechanics.
---
# Frontend Engineering
- TypeScript + Next.js + UI/UX + frontend security. The philosophy: write
- **inevitable code** — type-safe enough that wrong usage won't compile, obvious
- enough that the next reader doesn't need comments, effortless to compose.
- Measure before optimizing. Accessibility from day one, not a retrofit.
+ Build browser-facing code that is trustworthy at its boundaries, coherent at its
+ surface, and easy to locate by product ownership. Match the user's request: build,
+ recommend, or audit. A focused implementation does not require a full audit.
- ## Core Philosophy
+ ## Workflow
- - **Composition over inheritance** — hooks and small focused components beat
- HOCs and class hierarchies when React is involved
- - **Types are documentation that never lies** — if the types are right, the
- logic is constrained; if the logic is wrong, the types will tell you
- - **Runtime boundaries matter** — TypeScript types disappear at runtime. Zod /
- Valibot / ArkType at every external boundary (API responses, form inputs, URL
- params)
- - **Measure before optimizing** — premature memoization adds noise without
- benefit; the Profiler tells you what's actually slow
- - **Accessibility is correctness** — semantic HTML, keyboard nav, and ARIA are
- not polish; they are correctness constraints like type safety
+ ### 1. Read the environment
- ## Universal Checks
+ Inspect the package manifest, configuration, directory structure, and nearby code.
+ Identify the framework, installed libraries, relevant versions, design-system
+ conventions, validation library, and existing feature boundaries before proposing a
+ pattern.
- These checks take seconds to scan and catch the most common frontend mistakes.
- Inspect project files first; ask the user only when project state cannot answer
- the question.
+ Honor a sound installed stack. Recommend a new dependency only when a demonstrated
+ capability gap justifies it.
- 1. **`any` without justification** — `any` disables type checking for the
- entire expression tree below it. Prefer `unknown` and narrow explicitly.
- Legitimate uses: third-party lib without types, `catch (e)` (use
- `e instanceof Error`), genuine escape hatch with a comment explaining why.
+ **Complete when:** the active stack and local conventions are known, or the missing
+ facts that block the work have been requested.
- 2. **No runtime validation at external boundaries** — TypeScript types exist
- only at compile time. Add Zod/Valibot/ArkType at every network call, form
- submit, URL param parse, and `localStorage` read.
+ ### 2. Frame the frontend contract
- 3. **Unsafe type assertions at trust boundaries** — `as SomeApiResponse` or
- `JSON.parse(...) as T` turns untrusted data into trusted state. Replace casts
- with schema validation or explicit narrowing.
+ Name the user-visible behavior, untrusted inputs, browser APIs, semantic controls,
+ responsive constraints, and owning feature. For audits, trace every claim to a file,
+ line, rendered state, or browser observation.
- 4. **Client/server boundary drift** — Next.js Server Components should stay
- server-only unless they need event handlers, state, effects, or browser APIs.
- Keep `'use client'` boundaries narrow.
+ **Complete when:** expected behavior, trust boundaries, ownership, and verification
+ surface are explicit.
- 5. **Accessibility at the call site** — semantic HTML (`<button>` not
- `<div onClick>`), keyboard nav for custom controls, ARIA only when native
- HTML semantics are insufficient.
+ ### 3. Apply the universal checks
- 6. **Browser security footguns** — flag `dangerouslySetInnerHTML`, unsanitized
- URL construction, missing CSP considerations, and auth tokens in
- `localStorage` unless justified by the threat model.
+ 1. **Trust once:** untrusted data is validated when it enters a trusted domain;
+ internal code consumes the validated type.
+ 2. **Type honest:** public types describe runtime reality; assertions do not promote
+ unknown data into trusted state.
+ 3. **Semantic surface:** controls use native semantics, labels, keyboard behavior,
+ and visible focus. ARIA supplements native HTML.
+ 4. **Complete states:** loading, empty, error, pending, disabled, success, and recovery
+ behavior exist where the workflow can reach them.
+ 5. **System coherence:** components use the project's tokens, variants, responsive
+ rules, and installed primitives rather than parallel styling conventions.
+ 6. **Local ownership:** feature code stays with its owner; shared code is promoted only
+ after demonstrated reuse.
+ 7. **Browser proof:** the target flow works at relevant widths and input modes without
+ console errors, accidental overflow, inaccessible controls, or unsafe storage.
- ## Ownership Boundary with React
+ **Complete when:** every applicable check is satisfied or recorded as an evidence-backed
+ finding.
- Frontend owns TypeScript, runtime boundaries, browser security, accessibility,
- Next.js boundaries, Tailwind/component API patterns, and file structure. The
- `react` skill owns React runtime/rendering issues: `useEffect`, re-renders,
- Context provider values, keys, Server Actions, React 19 APIs, hydration, and
- waterfalls.
+ ### 4. Load only the matching reference
- ## References — Priority Table
+ Use the routing table below. Load multiple references only when the task crosses real
+ branches. Version-sensitive mechanics come from the project's installed documentation
+ or current primary documentation after the version is known.
- Load the reference that matches the issue. Security and type correctness issues
- are CRITICAL (silent bugs at runtime); UI and optimization issues are lower.
+ React component behavior, state ownership, Effects, Suspense, and rendering belong to
+ the `react` skill. Next.js route, cache, Server Action, and App Router architecture
+ belong to `nextjs-app-architecture`.
+ ### 5. Implement or report
+
+ - **Build:** make the smallest coherent change and follow repository validation.
+ - **Recommend:** compare viable choices against the current stack and demonstrated
+ constraints; state a preferred path.
+ - **Audit:** report only evidence-backed findings, ordered by user impact and risk.
+
+ For browser-visible work, invoke the installed `agent-browser` skill to exercise the
+ flow and capture relevant semantic state, console/page errors, screenshots, or traces.
+ The frontend skill defines the expected behavior; `agent-browser` performs the browser
+ interaction.
+
+ **Complete when:** the requested artifact exists, applicable checks pass, and any
+ unverified behavior or residual risk is explicit.
+
+ ## References
+
| Priority | Load when | Reference |
- |----------|-----------|-----------|
- | 1 — Critical | XSS, `dangerouslySetInnerHTML`, CSP headers, input sanitization, `localStorage` security, auth token storage, CORS, third-party scripts | `references/security.md` |
- | 2 — High | TypeScript types, generics, branded types, discriminated unions, `DistributiveOmit`, Zod/Valibot/ArkType, `tsconfig`, TypeScript 6.x/7.0 | `references/type-system.md` |
- | 3 — High | Next.js App Router, RSC vs Client Components, Server Actions, hydration mismatch, rendering model choice (SSR/SSG/ISR/CSR/RSC) | `references/nextjs.md` |
- | 4 — Medium | Component composition, compound components, `asChild`, CVA variants, Tailwind patterns, animation, `prefers-reduced-motion`, accessibility deep-dive, design tokens, dark mode, forms | `references/ui-patterns.md` |
- | 5 — Medium | Project structure, feature folders, "where should this file go", cross-feature imports, barrel files causing pain, scaling the codebase | `references/feature-architecture.md` |
+ |---|---|---|
+ | 1 — Critical | XSS, unsafe HTML or URLs, auth storage, CSP, CORS, third-party scripts, browser trust concerns | `references/security.md` |
+ | 1 — High | TypeScript component contracts, unions, generics, assertions, wrapper props, compiler configuration | `references/typescript.md` |
+ | 1 — High | External API data, forms, URL/search input, storage, schemas, parsing at trust boundaries | `references/runtime-validation.md` |
+ | 2 — High | Semantic HTML, labels, keyboard/focus behavior, announcements, basic accessibility verification | `references/accessibility.md` |
+ | 2 — Medium | Tokens, variants, styling contracts, responsive layout, theming, installed UI primitives | `references/ui-systems.md` |
+ | 2 — Medium | Loading/error/empty states, touch and keyboard input, reduced motion, browser APIs, compatibility | `references/browser-resilience.md` |
+ | 2 — Medium | Feature folders, ownership, imports, colocating code, promoting shared code, scaling structure | `references/feature-architecture.md` |
- ### When to load a reference
+ ## Completion Gate
- - Load the **highest-priority matching reference first** — security issues before
- optimization issues
- - If multiple references match, load in priority order; they don't repeat each other
- - The body above (universal checks) is always active — references add depth, load
- only when the checklist surface is insufficient
+ Before finishing:
+
+ - the implementation follows the detected stack rather than an assumed one;
+ - trust boundaries and public types agree with runtime behavior;
+ - the primary workflow has complete and operable user states;
+ - ownership and placement follow repository evidence;
+ - static checks and available browser verification have run;
+ - the response distinguishes verified behavior from remaining uncertainty.