ui

name	ui
description	React/Next.js frontend development standards with TypeScript, Tailwind CSS, and Kaizen UI. Enforces ESLint, Prettier, and browser validation via MCP. Use when creating React components, modifying pages, styling with Tailwind, implementing hooks, or working in src/ui/. Validates changes in browser when MCP tools available.

Overview

Technology Stack (Mandatory)

All frontend code MUST use the following stack:

• Next.js 14+ (App Router)
• React 18+
• Tailwind CSS for styling
• shadcn/ui for component library
• TypeScript for type safety

UI Development (Mandatory)

• For every new component, feature, or modification, ALWAYS create or update tests.
• Components must be responsive and accessible (WCAG 2.1 AA).
• Use semantic HTML elements.
• Follow React best practices (hooks, composition, etc.).

Required Tooling (Non-Negotiable)

All frontend code MUST comply with the following tools:

Linting & Formatting

• Use ESLint with Next.js configuration
• Use Prettier for code formatting
• Code must pass:
  • npm run lint (or pnpm lint / yarn lint)
  • Formatting checks
• No unused imports, unreachable code, or console.log statements in production code

Type Checking

• Use TypeScript with strict mode enabled
• All components and functions MUST have proper type definitions
• No any types unless explicitly justified in comments
• Use interface/type definitions for props

Testing

• Use Vitest or Jest for unit tests
• Use React Testing Library for component tests
• Use Playwright or Cypress for E2E tests (optional but recommended)
• Tests must be deterministic and not rely on external state

Workflow Order (Strict)

Cursor MUST follow this order when generating or modifying frontend code:

1. Implement the component/feature
2. Add or update unit/component tests
3. Ensure ESLint compliance
4. Ensure TypeScript type checks pass
5. Validate in browser using MCP tools (see Browser Validation section)
6. Only then consider the task complete

If any step fails or is missing, the work is incomplete.

Retail-Agentic-Commerce UI CI Parity (Mandatory)

Before committing UI-related changes in this repo, run the same checks used in CI from src/ui:

pnpm lint
pnpm format:check
pnpm typecheck
pnpm test:run

Rules:

• Do not commit if any command above fails.
• Run from src/ui to match CI environment and scripts.
• If the change also touches backend code, run backend CI parity commands in .cursor/skills/features/SKILL.md before commit.

Browser Validation (Mandatory When Available)

When browser MCP tools are available (cursor-browser-extension or cursor-ide-browser), you MUST use them to validate UI changes:

When to Validate

• New Features: Launch the UI and verify the feature works as expected
• Bug Fixes: Reproduce the bug, apply the fix, and confirm resolution
• UI Modifications: Visually verify changes render correctly
• Component Changes: Test component interactions and states

Validation Workflow

1. Start the development server if not already running
2. Use browser_navigate to open the relevant page
3. Use browser_snapshot to capture the page state (preferred over screenshots)
4. Use browser_click, browser_type, browser_fill_form to interact with UI elements
5. Verify expected behavior through snapshots or element inspection
6. Use browser_console_messages to check for JavaScript errors
7. Use browser_network_requests to verify API calls if needed

Example Validation Flow

1. Navigate to http://localhost:3000
2. Take a snapshot to verify page loaded
3. Interact with UI elements (click buttons, fill forms)
4. Take another snapshot to verify state changes
5. Check console for errors
6. Report findings

React/Next.js Coding Standards

• Use functional components with hooks
• Prefer Server Components where possible (Next.js App Router)
• Use 'use client' directive only when necessary
• Follow the Next.js file conventions:
  • page.tsx for routes
  • layout.tsx for layouts
  • loading.tsx for loading states
  • error.tsx for error boundaries
• Use Next.js Image component for optimized images
• Use Next.js Link component for navigation

Component Structure

src/
├── app/                    # Next.js App Router pages
│   ├── page.tsx
│   ├── layout.tsx
│   └── (routes)/
├── components/
│   ├── ui/                 # shadcn/ui components
│   └── features/           # Feature-specific components
├── lib/                    # Utilities and helpers
├── hooks/                  # Custom React hooks
├── types/                  # TypeScript type definitions
└── styles/                 # Global styles

Styling Standards

• Use Tailwind CSS utility classes
• Follow mobile-first responsive design
• Use CSS variables for theming (via shadcn/ui)
• Avoid inline styles; prefer Tailwind classes
• Use cn() utility for conditional classes

shadcn/ui Usage

• Install components via CLI: npx shadcn@latest add <component>
• Customize components in components/ui/
• Follow shadcn/ui patterns for variants and sizing
• Use Radix UI primitives for accessibility

Accessibility Requirements

• All interactive elements must be keyboard accessible
• Use proper ARIA attributes when needed
• Ensure sufficient color contrast
• Provide alt text for images
• Use semantic HTML elements

Testing Standards

• Test files must be named *.test.tsx or *.spec.tsx
• Test user interactions, not implementation details
• Use screen queries from React Testing Library
• Prefer getByRole over getByTestId
• Test accessibility with jest-axe or similar

Performance Considerations

• Use React.memo for expensive re-renders
• Implement proper loading states
• Use Suspense boundaries appropriately
• Optimize images and assets
• Avoid unnecessary client-side JavaScript

Code Review Expectations

• No commented-out code
• No TODOs without an issue reference
• No console.log statements (use proper logging in production)
• Clear, descriptive component and variable names
• Props must be properly typed

Update documentation

• Add clear and simple instructions on the README.md
• Update AGENTS.md and CLAUDE.md for agentic development.

If these standards are not met, the solution MUST be revised.