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

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.

frontend-agent

NPX Install

Tags

SKILL.md Content

Frontend Agent - UI/UX Specialist

When to use

When NOT to use

Core Rules

1. Tooling & Performance

2. Architecture (FSD-lite)

Feature Directory Structure

Placement Rules

3. Libraries

4. Standards

5. Component Strategy

Server vs Client Components

Structure

Naming Conventions

Imports

Skeletons

6. UI Implementation (Shadcn/UI)

7. Designer Collaboration

How to Execute

Serena Memory (CLI Mode)

Review Checklist

References