Frontend Engineering Skill
Activate this skill when creating or modifying user interfaces, client components, styling systems, design tokens, hooks, or frontend state.
Operational Directive: Build responsive, accessible, resilient, and high-performance interfaces adhering strictly to the project's single design system with zero state-mutation bugs.
1. Strict Negative Guardrail: Zero Unrequested Styling & Token Invariant
- Zero Unrequested Styling Rule: NEVER add, alter, or restyle CSS, classes, colors, gradients, dark-mode themes, or animations unless visual/styling changes are explicitly requested by the user.
- Logic/State Isolation: When implementing business logic, state management, API integration, or bugfixes, leave all styling attributes, classNames, and visual tags strictly untouched.
- Inspect
.ai/UI.md(or workspace manifests) first: Identify the established styling framework (Tailwind CSS, CSS Modules, Styled Components, Vanilla CSS, shadcn/ui). - Strict Single Framework Rule: Never import secondary styling frameworks (e.g. do not introduce Bootstrap, MUI, or Chakra if the project uses Tailwind CSS).
- Zero Invented Tokens: Never invent ad-hoc hex codes, magic margins/paddings, or arbitrary animations. Always reuse existing project theme tokens.
- Unstyled Fallback: If the project has no styling system and styling was not explicitly asked for, output clean, semantic, unstyled HTML. Never invent a custom CSS theme or inline styles unprompted.
2. Component Hierarchy & Separation of Concerns
Structure UI components using the Smart Container vs Presentational Component pattern:
┌────────────────────────────────────────────────────────┐
│ Smart / Container Component │
│ - Handles data fetching, URL query params, hooks │
│ - Passes data and event callbacks to UI components │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ Presentational / Dumb Component │
│ - Pure visual rendering, receives data via props │
│ - Completely stateless or localized animation state │
│ - High reusability across pages │
└────────────────────────────────────────────────────────┘3. Performance & Core Web Vitals Optimization
- Cumulative Layout Shift (CLS): Always set explicit
widthandheight(or aspect-ratio) on images, videos, and embed frames to eliminate visual jank. - Largest Contentful Paint (LCP): Preload critical hero images and utilize modern formats (
.webp,.avif). - Prevent Unnecessary Re-Renders:
- Avoid defining inline object literals or inline arrow functions inside hot loop renders.
- Utilize
useMemoanduseCallbackjudiciously on computationally heavy operations.
- Loading & Error State Ergonomics: Every async component must gracefully handle 4 distinct states:
- Initial Loading (Skeleton placeholder, no layout shift)
- Data Rendered (Normal view)
- Empty State (Friendly message with actionable CTA)
- Error State (Clear feedback with retry button)
4. React Hook & State Lifecycle Invariants (Anti-Bug Guardrails)
A. Immutable State Updates (Zero Direct Mutation)
- Insecure / Buggy:
// ❌ WRONG: Mutates state array directly; fails to trigger re-renders reliably items.push(newItem); setItems(items); - Correct Standard:
// ✅ CORRECT: Return a brand new array reference setItems((prev) => [...prev, newItem]);
B. No Redundant useEffect for Derived State
- Anti-Pattern: Syncing props to state or calculating filtered items inside
useEffect:// ❌ WRONG: Unnecessary state + extra render cycle const [filtered, setFiltered] = useState([]); useEffect(() => { setFiltered(items.filter((i) => i.active)); }, [items]); - Correct Standard: Calculate directly during rendering (or wrap with
useMemoif expensive):// ✅ CORRECT: Pure computation with zero extra render passes const filtered = useMemo(() => items.filter((i) => i.active), [items]);
C. Strict List Key Invariant (Never Use Array Index for Dynamic Lists)
- Anti-Pattern:
<li key={index}>on lists that can be reordered, deleted, or inserted dynamically (causes subtle input value corruption and rendering bugs). - Correct Standard: Always use a stable, unique item identifier:
{items.map((item) => ( <UserRow key={item.id} user={item} /> ))}
D. Memory Leak Prevention & Effect Cleanup
Every effect initiating an async network call, event listener, timer, or WebSocket must return an explicit cleanup function:
useEffect(() => {
const controller = new AbortController();
async function loadData() {
try {
const res = await fetch(`/api/items?id=${id}`, { signal: controller.signal });
const data = await res.json();
setData(data);
} catch (err: any) {
if (err.name !== 'AbortError') setError(err);
}
}
loadData();
return () => controller.abort(); // Cancel in-flight request when component unmounts or ID changes
}, [id]);5. Mandatory Frontend Pre-Commit Checklist
Before approving any UI or component change, verify:
- Styling Isolation: Did not alter existing visual styles unless requested.
- Key Invariant: No dynamic lists use array index as
key. - Cleanup Invariant: All
useEffectlisteners, intervals, and fetch subscriptions have cleanup handlers. - Derived State: No redundant state variables synced via
useEffect. - 4-State UI Coverage: Loading, Error, Empty, and Success states handled cleanly.