Frontend Quality Standards

Core Principles

Deliver working code, not plans. Make reasonable assumptions when not blocked. Complete implementations to a runnable state.

Avoid "AI slop." Every design choice should be intentional:

• •Typography: Choose fonts that serve the content, not defaults
• •Colors: Use meaningful color palettes that enhance UX
• •Spacing: Consistent, purposeful rhythm
• •No generic boilerplate or placeholder content

Preserve existing design systems. Before creating new components:

1. •Check for existing UI components in components/ui/
2. •Use existing design tokens (CSS variables, Tailwind config)
3. •Follow established patterns and conventions
4. •Only introduce new patterns when necessary

Design Guidelines

Typography

• •Use existing font families from the design system
• •Establish clear hierarchy (headings, body, captions)
• •Ensure readable line heights and letter spacing
• •Test at different viewport sizes

Colors

• •Use CSS variables (e.g., var(--primary), var(--accent))
• •Maintain contrast ratios for accessibility
• •Support both light and dark modes
• •Avoid hardcoded color values

Motion & Animations

• •Use Framer Motion for animations (project standard)
• •Keep animations tasteful and purposeful:
  • •Subtle transitions (200-300ms)
  • •Ease-in-out timing functions
  • •Avoid excessive motion that distracts
• •Respect prefers-reduced-motion media query

Responsive Design

• •Mobile-first approach
• •Test at breakpoints: mobile (320px+), tablet (768px+), desktop (1024px+)
• •Use Tailwind responsive utilities (sm:, md:, lg:, xl:)
• •Ensure touch targets are at least 44x44px on mobile
• •Test horizontal scrolling doesn't occur unintentionally

Implementation Checklist

Before considering code complete:

• • Code runs without errors
• • Uses existing design system components/tokens
• • Responsive on mobile and desktop
• • Animations are subtle and purposeful
• • No hardcoded colors (use CSS variables)
• • Typography follows established hierarchy
• • No placeholder text or generic boilerplate
• • Accessibility: proper semantic HTML, ARIA labels where needed
• • Dark mode support (if applicable)

Common Patterns

Using Existing Components

// ✅ Good: Use existing Button component
import { Button } from "@/components/ui/button"

<Button variant="default" size="lg">Submit</Button>

// ❌ Avoid: Creating new button styles from scratch
<button className="px-4 py-2 bg-blue-500">Submit</button>

Color Usage

// ✅ Good: Use design tokens
<div className="bg-primary text-primary-foreground">
<div className="text-accent">

// ❌ Avoid: Hardcoded colors
<div className="bg-[#ff2936]">

Responsive Layouts

// ✅ Good: Mobile-first responsive
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">

// ❌ Avoid: Desktop-only layouts
<div className="grid grid-cols-3 gap-4">

Animations

// ✅ Good: Subtle, purposeful animation
import { motion } from "framer-motion"

<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.3, ease: "easeOut" }}
>

// ❌ Avoid: Excessive or distracting motion
<motion.div
  animate={{
    rotate: [0, 360],
    scale: [1, 1.2, 1],
  }}
  transition={{ repeat: Infinity, duration: 2 }}
>

When to Break Rules

Only introduce new patterns when:

• •No existing component meets the need
• •The new pattern solves a specific UX problem
• •The pattern can be reused elsewhere
• •It aligns with the overall design language

When introducing new patterns, document them and consider adding to the design system.