Swipd Web Development Assistant
Expert assistant for developing and maintaining the Swipd Web landing page - a Next.js 15 marketing website for a swipe-based affiliate shopping iOS app.
Project Context
**Framework**: Next.js 15 with App Router**Language**: TypeScript 5**React**: Version 19 (Server Components)**Styling**: Tailwind CSS 4 + shadcn/ui**Components**: Radix UI primitives**Testing**: Playwright (E2E)**Analytics**: Google Analytics 4Project Structure
The codebase follows Next.js 15 App Router conventions:
```
swipd-web/
├── app/ # App Router pages
│ ├── layout.tsx # Root layout
│ ├── page.tsx # Landing page
│ └── globals.css # Global styles + CSS variables
├── components/
│ ├── ui/ # shadcn/ui components
│ └── [other components] # Custom components
├── lib/
│ ├── constants.ts # App metadata & config
│ └── utils.ts # Utilities
└── public/ # Static assets
```
Step-by-Step Instructions
1. Understanding the Codebase
When starting any task:
Read `lib/constants.ts` to understand app metadata and configurationCheck `app/globals.css` for theme colors and CSS variables (OKLch color space)Review `app/layout.tsx` for root-level configurationExamine existing components in `components/ui/` before creating new ones2. Development Tasks
**Starting Development:**
```bash
npm install
npm run dev
```
**Building for Production:**
```bash
npm run build
npm start
```
**Linting:**
```bash
npm run lint
```
3. Working with Components
**Using Existing shadcn/ui Components:**
Check `components/ui/` directory firstAvailable components: button, card, dropdown-menu, separatorUse Radix UI primitives for accessibility**Adding New shadcn/ui Components:**
```bash
npx shadcn@latest add [component-name]
```
Configuration is already set in `components.json`:
Style: new-yorkPath alias: @/*Icons: lucide**Component Development Guidelines:**
Prefer Server Components by default (Next.js 19)Only add "use client" when necessary (interactivity, hooks, events)Use the `cn()` utility from `lib/utils.ts` for conditional classesFollow existing component patterns in `components/ui/`4. Styling Guidelines
**Theme System:**
Uses next-themes for dark/light/system modesColors defined in `app/globals.css` using OKLch color spaceTheme colors: background, foreground, primary, secondary, accent, muted, destructiveDark mode via `.dark` class (automatic)**Tailwind Usage:**
Mobile-first responsive designUse CSS variables: `bg-background`, `text-foreground`, `border-border`, etc.Animations via `tw-animate-css`Reference existing classes in `globals.css` before adding new ones**Adding New Styles:**
1. Check if CSS variable exists in `globals.css`
2. Use Tailwind utilities with existing variables
3. Only add new CSS variables if absolutely necessary
4. Maintain consistency between light and dark modes
5. Environment Configuration
**Required Variables:**
`NEXT_PUBLIC_APP_STORE_URL` - iOS App Store link`NEXT_PUBLIC_SITE_URL` - Site URL for metadata`NEXT_PUBLIC_SITE_NAME` - Site name**Optional Variables:**
`NEXT_PUBLIC_GA_MEASUREMENT_ID` - Google Analytics ID**Setup:**
```bash
cp .env.example .env.local
```
6. Landing Page Development
The main landing page (`app/page.tsx`) includes:
Hero section with App Store CTAFeatures grid showcasing app capabilitiesTarget users sectionAdditional CTA sections**When modifying the landing page:**
Keep sections modular and reusableMaintain mobile-first responsive designUse semantic HTML for accessibilityTest both light and dark themesVerify App Store link functionality7. Testing
**Running E2E Tests:**
```bash
npx playwright test
```
**Writing Tests:**
Use Playwright for E2E scenariosTest critical user flows (navigation, CTAs, theme switching)Verify responsive behaviorTest both light and dark modes8. Analytics Integration
Google Analytics 4 integration via `components/google-analytics.tsx`Only loads when `NEXT_PUBLIC_GA_MEASUREMENT_ID` is setRespects user privacy preferences9. Performance Optimization
Use Next.js Image component for imagesLazy load non-critical componentsMinimize client-side JavaScript (prefer Server Components)Leverage Next.js automatic code splittingTest build output with `npm run build`10. Accessibility
All interactive components use Radix UI primitives (accessible by default)Maintain proper heading hierarchyUse semantic HTML elementsTest keyboard navigationVerify screen reader compatibilityEnsure sufficient color contrast in both themesCommon Tasks
Adding a New Section to Landing Page
1. Create component in `components/` or inline in `app/page.tsx`
2. Use Server Component unless interactivity needed
3. Apply theme colors via Tailwind utilities
4. Test responsive behavior (mobile, tablet, desktop)
5. Verify in both light and dark modes
Updating Theme Colors
1. Modify CSS variables in `app/globals.css`
2. Update both `:root` (light) and `.dark` (dark) definitions
3. Use OKLch color space for consistency
4. Test changes across all components
Adding New UI Component
1. Check if shadcn/ui has the component: `npx shadcn@latest add [name]`
2. Customize in `components/ui/` if needed
3. Follow existing component structure and typing
4. Use Radix UI primitives for complex interactions
Modifying Metadata
1. Update values in `lib/constants.ts`
2. Metadata is consumed by `app/layout.tsx`
3. Changes apply site-wide automatically
Important Constraints
**Next.js 15 specific**: Use App Router conventions, not Pages Router**Server Components**: Default to Server Components; only use Client Components when necessary**Styling**: Use existing CSS variables; avoid arbitrary colors**Icons**: Use Lucide React (already configured with shadcn/ui)**Accessibility**: Maintain WCAG 2.1 AA compliance minimum**Mobile-first**: Always design and test mobile experience first**Theme support**: Every UI change must work in both light and dark modesTroubleshooting
**Build Errors:**
Check TypeScript errors: `npm run build`Verify all environment variables are setClear `.next` directory: `rm -rf .next && npm run build`**Styling Issues:**
Verify Tailwind class names are correctCheck if CSS variables are defined in `globals.css`Inspect element to see computed stylesTest in both light and dark modes**Component Issues:**
Ensure proper "use client" directive for interactive componentsCheck Radix UI documentation for component-specific requirementsVerify imports use @/* path alias correctly