---

name: perfect-pixel description: This is a new rule

Overview

Sculptique - Cursor AI Rules

Next.js 16 + shadcn/ui + TypeScript + Tailwind CSS 4

Core Principles

• Prioritize pixel-perfect UI implementation with precise spacing, typography, and responsive design
• Write clean, type-safe TypeScript code with minimal dependencies
• Follow Next.js 16 App Router best practices and React 19 conventions
• Leverage React Compiler optimizations (avoid manual memoization unless proven necessary)
• Maintain consistency with shadcn/ui design patterns and component architecture

Tech Stack Specifics

Next.js 16 (App Router)

• Use App Router exclusively with the app/ directory structure
• Implement Server Components by default; use 'use client' only when necessary (interactivity, hooks, browser APIs)
• Leverage Server Actions for form submissions and mutations
• Use next/image for all images with proper width, height, and sizes attributes
• Implement dynamic imports with next/dynamic for code splitting when appropriate
• Use searchParams and params as async props in page components
• Prefer Server Components for data fetching with async/await
• Use Route Handlers (app/api/**/route.ts) for API endpoints
• Implement proper loading.tsx and error.tsx boundaries
• Use Metadata API for SEO (generateMetadata for dynamic, export metadata for static)

TypeScript

• Enable strict mode and use the strictest possible configuration
• Define explicit return types for all functions and components
• Use interfaces for object shapes, types for unions/intersections
• Leverage TypeScript utility types (Partial, Pick, Omit, Record, etc.)
• Avoid 'any' type; use 'unknown' when type is truly unknown
• Create custom type guards for runtime type checking
• Use const assertions and satisfies operator where appropriate
• Define component props with descriptive names and JSDoc comments when needed
• Export types/interfaces that might be reused across files

Tailwind CSS 4

• Use Tailwind's utility classes exclusively; avoid custom CSS unless absolutely necessary
• Follow mobile-first responsive design (default → sm: → md: → lg: → xl: → 2xl:)
• Leverage Tailwind's design tokens for consistency:
  • Spacing: Use the spacing scale (0, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 56, 64)
  • Colors: Use semantic color scales (gray-50 to gray-950, etc.)
  • Typography: Use text-* utilities with proper line-height and letter-spacing
• Use arbitrary values sparingly: [14px], [#1da1f2]
• Combine utilities with @apply only in component-level CSS when pattern repeats 5+ times
• Use clsx or cn utility for conditional classes
• Implement consistent padding/margin patterns (p-4, px-6, py-8, etc.)
• Use grid and flexbox utilities for layouts
• Apply group-* and peer-* utilities for interactive states
• Use data-* attributes with Tailwind for state-based styling

shadcn/ui Components

• Install components from shadcn/ui as needed; don't preinstall all components
• Maintain the components/ui directory structure
• Never modify the core component files directly; extend via composition
• Use component composition patterns (wrap shadcn components in custom components)
• Follow the cn() utility pattern from lib/utils.ts for className merging
• Implement variants using class-variance-authority (cva)
• Use Radix UI primitives patterns (asChild, etc.)
• Maintain consistent component API design (size, variant, className props)
• Add custom variants to shadcn components in separate wrapper components

Code Style & Patterns

Component Structure

Copy// 1. Imports (grouped: React, Next.js, third-party, local)
import { type ReactNode } from 'react'
import Image from 'next/image'
import { Button } from '@/components/ui/button'
import { cn } from '@/lib/utils'

// 2. Types/Interfaces
interface ComponentProps {
  children: ReactNode
  className?: string
  variant?: 'default' | 'outline'
}

// 3. Component (use function declarations for better stack traces)
export function Component({ children, className, variant = 'default' }: ComponentProps) {
  return (
    <div className={cn('base-classes', className)}>
      {children}
    </div>
  )
}

File Naming Conventions

• Components: PascalCase (Button.tsx, UserProfile.tsx)
• Utilities: kebab-case (format-date.ts, api-client.ts)
• Pages/Routes: lowercase (page.tsx, layout.tsx)
• Use barrel exports (index.ts) sparingly; prefer explicit imports

Pixel-Perfect UI Guidelines

Spacing & Layout

• Use consistent spacing scale: 4px base unit (space-1 = 4px)
• Common patterns:
  • Section padding: py-12 md:py-16 lg:py-24
  • Container max-width: max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
  • Card padding: p-6 or p-8
  • Gap between elements: gap-4, gap-6, gap-8
• Avoid inconsistent spacing; stick to the design system

Typography

• Use semantic heading hierarchy (h1 → h6)
• Common patterns:
  • Page title: text-3xl md:text-4xl lg:text-5xl font-bold tracking-tight
  • Section heading: text-2xl md:text-3xl font-semibold
  • Body text: text-base leading-relaxed
  • Small text: text-sm text-muted-foreground
• Maintain consistent line-height ratios (1.5 for body, 1.2 for headings)
• Use font-medium (500), font-semibold (600), font-bold (700) consistently

Colors & Theming

• Use CSS variables for theming: bg-background, text-foreground, border-border
• Implement dark mode with class="dark" strategy
• Common semantic colors:
  • Primary action: bg-primary text-primary-foreground
  • Muted/secondary: bg-muted text-muted-foreground
  • Destructive: bg-destructive text-destructive-foreground
• Use opacity utilities for hover states: hover:bg-primary/90

Responsive Design

• Design mobile-first, enhance for larger screens
• Common breakpoints:
  • sm: 640px (small tablets)
  • md: 768px (tablets)
  • lg: 1024px (laptops)
  • xl: 1280px (desktops)
  • 2xl: 1536px (large desktops)
• Stack vertically on mobile, use grid/flex on desktop
• Example: flex-col md:flex-row

Animations & Transitions

• Use tw-animate-css classes for entrance animations
• Add transitions for interactive states: transition-colors, transition-all
• Duration: duration-200 for quick interactions, duration-300 for smooth transitions
• Easing: ease-in-out for most transitions

Performance Optimization

• Use React 19 features (use transitions, Server Actions)
• Let React Compiler handle optimizations (avoid useMemo/useCallback unless profiled)
• Implement proper image optimization with next/image
• Use dynamic imports for heavy components
• Implement proper loading states with Suspense
• Use Server Components for non-interactive content
• Minimize client-side JavaScript bundle

Accessibility

• Use semantic HTML elements (nav, main, aside, article, section)
• Include proper ARIA labels when semantic HTML isn't sufficient
• Ensure keyboard navigation works (focus states, tab order)
• Maintain color contrast ratios (WCAG AA minimum)
• Add alt text to all images
• Use proper heading hierarchy
• Implement focus-visible for keyboard users

State Management

• Use React 19 useActionState for form state
• Server state: fetch in Server Components or use Server Actions
• Client state: useState, useReducer for local component state
• URL state: searchParams for filters, pagination, etc.
• Avoid global state libraries unless absolutely necessary

Error Handling

• Use error boundaries (error.tsx) for graceful error handling
• Implement proper form validation with descriptive error messages
• Use toast notifications for user feedback (install sonner if needed)
• Log errors appropriately (avoid console.log in production)

Testing Philosophy

• Write components that are easy to test (pure, with clear props)
• Prefer integration tests over unit tests
• Test user interactions, not implementation details
• Use data-testid attributes when necessary

File Organization

Copyapp/
├── (marketing)/          # Route groups for layout separation
│   ├── page.tsx
│   └── layout.tsx
├── (dashboard)/
│   └── ...
├── api/                  # API routes
│   └── route.ts
├── layout.tsx            # Root layout
└── page.tsx              # Home page

components/
├── ui/                   # shadcn components (auto-generated)
│   ├── button.tsx
│   └── ...
├── forms/                # Form components
├── layouts/              # Layout components (header, footer, etc.)
└── ...                   # Feature-specific components

lib/
├── utils.ts              # Utility functions (cn, etc.)
├── constants.ts          # App constants
└── ...                   # Helper functions

public/                   # Static assets

types/                    # Shared TypeScript types

Common Patterns

Server Component with Data Fetching

Copyasync function Page() {
  const data = await fetchData()
  
  return (
    <div className="container mx-auto py-8">
      <h1 className="text-3xl font-bold">{data.title}</h1>
    </div>
  )
}

Client Component with Interactivity

Copy'use client'

import { useState } from 'react'
import { Button } from '@/components/ui/button'

export function InteractiveComponent() {
  const [count, setCount] = useState(0)
  
  return (
    <Button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </Button>
  )
}

Form with Server Action

Copy// app/actions.ts
'use server'

export async function submitForm(formData: FormData) {
  const name = formData.get('name')
  // Process form
  return { success: true }
}

// Component
'use client'

import { useActionState } from 'react'
import { submitForm } from './actions'

export function Form() {
  const [state, formAction] = useActionState(submitForm, null)
  
  return (
    <form action={formAction}>
      <input name="name" />
      <button type="submit">Submit</button>
    </form>
  )
}

Code Quality Checklist

Before committing code, verify:

• TypeScript has no errors (npm run type-check if available)
• ESLint passes (npm run lint)
• Components use proper semantic HTML
• Spacing follows the design system
• Responsive design works on mobile, tablet, desktop
• Images use next/image with proper optimization
• No console.logs in production code
• Proper error handling is implemented
• Accessibility requirements are met
• Code follows the file organization structure
• Server/Client components are used appropriately

Anti-Patterns to Avoid

• ❌ Don't use CSS-in-JS libraries (styled-components, emotion)
• ❌ Don't create custom CSS files unless absolutely necessary
• ❌ Don't use Pages Router (use App Router only)
• ❌ Don't modify shadcn/ui component files directly
• ❌ Don't use inline styles (style prop) unless dynamic values from props
• ❌ Don't use 'any' type in TypeScript
• ❌ Don't fetch data in Client Components when Server Components can do it
• ❌ Don't overuse 'use client' directive
• ❌ Don't use hardcoded colors/spacing (use Tailwind utilities)
• ❌ Don't forget to add loading and error states

When You're Unsure

• Check Next.js 16 documentation
• Reference shadcn/ui component examples
• Follow Tailwind CSS best practices
• Prioritize user experience and accessibility
• Ask for clarification on design requirements

---

Remember: The goal is pixel-perfect, performant, and maintainable code that provides an exceptional user experience.