Imported from haseebace/skiny (AGENTS.md). Install upstream with npx skills add haseebace/skiny. Copyright stays with the author.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Skiny — Agent Briefing

Project Overview

Skiny is a web app that helps users generate personalized skincare routines.

For the full product definition — features, user flows, success metrics, roadmap, and open questions — see PRD.md. This file focuses on how agents should build the project.

For now the project is in the setup/briefing phase. Build incrementally, validate each step, and keep the codebase clean and easy to extend.

Tech Stack

• Framework: Next.js (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: shadcn/ui
• Backend/Database: Supabase (PostgreSQL + Auth)
• Animations: Framer Motion
• Icons: Lucide React
• State Management: React hooks / server actions; escalate to a store only when necessary

Design System

The project's design system is defined in DESIGN.md at the repository root. This is the single source of truth for:

• Colors: tokens, semantic roles, brand vs. neutral palettes
• Typography: font family, scale, weights, line heights, letter spacing
• Spacing: base unit, token scale, section rhythm
• Radii / Shapes: border-radius scale, pill vs. rounded vs. sharp rules
• Shadows / Elevation: depth levels and their usage
• Components: button variants, card types, input fields, badges, tabs, nav items, data tables, promo strips — each with explicit background, text, border, padding, and typography specs
• Responsive breakpoints and collapsing strategy
• Do's and Don'ts for using the system

Always read DESIGN.md before implementing any UI. When designing new components, reference existing component tokens and patterns. Do not introduce colors, typography variants, spacing values, or shapes that aren't in the system.

Animation Rules

• Use Framer Motion for all motion.
• Micro-interactions: button presses, hover states, input focus, checkbox/radio selection.
• Page/section transitions: gentle fades and slides (not jarring).
• Questionnaire: smooth step transitions between questions.
• Staggered entrance for lists/cards.
• Respect prefers-reduced-motion.

Project Structure

Prefer the following conventions:

src/
  app/                # Next.js App Router pages
  components/
    ui/               # shadcn/ui components (auto-generated)
    forms/            # questionnaire form sections
    routine/          # routine display components
    layout/           # shared layout components
  lib/
    supabase/         # Supabase client setup
    utils.ts          # cn() and helpers
  types/              # shared TypeScript types
  actions/            # Server Actions for Supabase mutations

Coding Conventions

• Use TypeScript everywhere.
• Prefer Server Components by default; use Client Components only when needed (forms, animations, interactivity).
• Use Server Actions for mutations to Supabase.
• Use cn() from lib/utils for conditional Tailwind classes.
• Avoid large components. Split into small, focused files.
• Prefer named exports for components.
• Keep constants, types, and data separate from UI.
• Use environment variables for Supabase keys/URL.
• Never commit secrets.
• Use official CLIs when working with external tools/services. For example:
  • npx shadcn@latest add <component> for shadcn/ui components.
  • npx supabase <command> or the Supabase CLI for local dev, migrations, types, and linking projects.
  • npx ctx7@latest ... for documentation lookups.
  • Avoid manually scaffolding files that a tool's CLI is meant to generate.

Development Process

Feature-by-Feature Delivery

Build the app one feature at a time. Do not start the next feature until the current one is complete and verified.

For each feature:

1. Define the scope clearly (use PRD.md as the source of truth).
2. Implement the UI, data layer, and server actions needed.
3. Verify the happy path manually or with a basic test.
4. Fix issues and clean up before moving on.

Feature order and release phases are defined in PRD.md.

Reusability

Build every component, hook, helper, and server action as if it will be reused.

• Components should accept clear props and avoid hard-coding business logic.
• Shared logic belongs in lib/, hooks/, or actions/ — not inside page components.
• Types should live in types/ and be imported wherever needed.
• Avoid copy-pasting. If something is used twice, extract it.

Styling Architecture

Styles should have one main entry point and only branch when a specific instance needs to look different.

• Use the global Tailwind config and CSS variables as the single source of truth for colors, spacing, typography, radii, and shadows.
• Base shadcn/ui components should define the default appearance.
• Only add component-level or page-level styles when that specific instance intentionally needs to deviate from the default.
• Use cn() for conditional overrides. Avoid inline style objects.
• Prefer utility classes over one-off custom CSS. If custom CSS is needed, document why.

Dependencies

Install when starting development:

npx shadcn@latest init --yes --template next --base-color stone
npx shadcn add button card input label checkbox radio-group select slider stepper dialog sheet toast
npm install framer-motion lucide-react @supabase/ssr @supabase/supabase-js

Adjust shadcn components based on actual UI needs.

LLM for Routine Generation (Optional / Testing)

Routine generation can start as deterministic rule-based logic using the questionnaire answers. An LLM is not required for the MVP.

If experimenting with AI-generated routines:

• Keep the routine-generation function isolated in lib/routine-generation/ or actions/generate-routine.ts.
• Use a provider-agnostic interface so the underlying model can be swapped without changing the UI.
• Store the provider/API key in environment variables (e.g., GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY).
• Default to the deterministic rule-based generator; make the LLM path opt-in via feature flag or env var.

For recommended free providers, free-tier details, and providers to avoid, see PRD.md.

Notes for Agents

• Read this file before making architectural decisions.
• Read PRD.md for product requirements and DESIGN.md for visual design.
• Keep the UI minimal: do not add unnecessary decorative elements.
• Every new feature should include a basic happy-path test or manual verification step.
• When adding animations, ensure they are subtle and purposeful.
• Maintain a clear user journey: landing → questionnaire → routine → save → reminders.