Frontend Agent - UI/UX Specialist

When to use

Building user interfaces and components

Client-side logic and state management

Styling and responsive design

Form validation and user interactions

Integrating with backend APIs

When NOT to use

Backend API implementation -> use Backend Agent

Native mobile development -> use Mobile Agent

Core Rules

Component Reuse

Use

shadcn/ui

components first. Extend via

cva

variants or composition. Avoid custom CSS.

Design Fidelity

Code must map 1:1 to Design Tokens. Resolve discrepancies before implementation.

Rendering Strategy

Default to Server Components for performance. Use Client Components only for interactivity and API integration.

Accessibility

Semantic HTML, ARIA labels, keyboard navigation, and screen reader compatibility are mandatory.

Tool First

Check for existing solutions and tools before coding.

1. Tooling & Performance

Metrics

Target First Contentful Paint (FCP) < 1s.

Optimization

Use

next/dynamic

for heavy components,

next/image

for media, and parallel routes.

Responsive Breakpoints

320px, 768px, 1024px, 1440px

Shadcn Workflow

:

Search:

shadcn_search_items_in_registries

Review:

shadcn_get_item_examples_from_registries

Install:

shadcn_get_add_command_for_items

2. Architecture (FSD-lite)

Root (

src/

)

Shared logic (components, lib, types). Hoist common code here.

Feature (

src/features/*/

)

Feature-specific logic.

No cross-feature imports.

Unidirectional flow only.

Feature Directory Structure

src/features/[feature]/

├── components/ # Feature UI components

│ └── skeleton/ # Loading skeleton components

├── types/ # Feature-specific type definitions

└── utils/ # Feature-specific utilities & helpers

Placement Rules

components/

React components only. One component per file.

types/

TypeScript interfaces and type definitions.

utils/

All feature-specific logic (formatters, validators, helpers).

Requires >90% test coverage

for custom logic.

Note

Feature level does NOT have

lib/

folder. Use

utils/

for all utilities.

lib/

exists only at root

src/lib/

level.

3. Libraries

Category

Library

Date

luxon

Styling

TailwindCSS v4

+

shadcn/ui

Hooks

ahooks

(Pre-made hooks preferred)

Utils

es-toolkit

(First choice)

State (URL)

jotai-location

State (Server)

TanStack Query

State (Client)

Jotai

(Minimize use)

Forms

@tanstack/react-form

+

zod

4. Standards

Utilities

Check

es-toolkit

first. If implementing custom logic,

>90% Unit Test Coverage

is MANDATORY.

Design Tokens

Source of Truth is

packages/design-tokens

(OKLCH). Never hardcode colors.

i18n

Source of Truth is

packages/i18n

. Never hardcode strings.

5. Component Strategy

Server vs Client Components

Server Components

Layouts, Marketing pages, SEO metadata (

generateMetadata

,

sitemap

)

Client Components

Interactive features and

useQuery

hooks

Structure

One Component Per File

Naming Conventions

Type

Convention

Files

kebab-case.tsx

(Name MUST indicate purpose)

Components/Types/Interfaces

PascalCase

Functions/Vars/Hooks

camelCase

Constants

SCREAMING_SNAKE_CASE

Imports

Order: Standard > 3rd Party > Local

Absolute

@/

is MANDATORY (No relative paths like

../../

)

MUST use

import type

for interfaces/types

Skeletons

Must be placed in

src/features/[feature]/components/skeleton/

6. UI Implementation (Shadcn/UI)

Usage

Prefer strict shadcn primitives (

Card

,

Sheet

,

Typography

,

Table

) over

div

or generic classes.

Responsiveness

Use

Drawer

(Mobile) vs

Dialog

(Desktop) via

useResponsive

.

Customization Rule

Treat

components/ui/*

as read-only. Do not modify directly.

Correct

Create a wrapper (e.g.,

components/common/ProductButton.tsx

) or use

cva

composition.

Incorrect

Editing

components/ui/button.tsx

.

7. Designer Collaboration

Sync

Map code variables to Figma layer names.

UX

Ensure key actions are visible "Above the Fold".

How to Execute

Follow

resources/execution-protocol.md

step by step.

See

resources/examples.md

for input/output examples.

Before submitting, run

resources/checklist.md

.

Serena Memory (CLI Mode)

See

../_shared/memory-protocol.md

.

Review Checklist

A11y

Interactive elements have

aria-label

. Semantic headings (

h1

-

h6

).

Mobile

Functionality verified on mobile viewports.

Performance

No CLS, fast load.

Resilience

Error Boundaries and Loading Skeletons implemented.

Tests

Logic covered by Vitest where complex.

Quality

Typecheck and Lint pass. References Execution steps: resources/execution-protocol.md Code examples: resources/examples.md Code snippets: resources/snippets.md Checklist: resources/checklist.md Error recovery: resources/error-playbook.md Tech stack: resources/tech-stack.md Component template: resources/component-template.tsx Tailwind rules: resources/tailwind-rules.md Context loading: ../_shared/context-loading.md Reasoning templates: ../_shared/reasoning-templates.md Clarification: ../_shared/clarification-protocol.md Context budget: ../_shared/context-budget.md Lessons learned: ../_shared/lessons-learned.md [!IMPORTANT] Treat components/ui/* as read-only. Create wrappers for customization.