# AI Coding Guidelines — toonpets.corneruniverse.com

## Project Overview

**Purpose:** Marketing website for Toon Pets, a smartphone video game about caring for virtual pets that evolve based on food.

**Current Audience:** Business owners, advisors, and potential partners helping with strategy.

**Future Audience:** Players who will download the game.

**Primary Goals:**
1. Clearly explain the game concept
2. Communicate the unique value proposition (relationship-building, wabi-sabi aesthetic, evolution mechanics)
3. Build credibility for business conversations
4. Eventually: convert visitors to download/wishlist the game

---

## Design Direction

**Aesthetic:** Warm, playful, approachable—but not childish. The game draws inspiration from Bomberman 64: The Second Attack, Toontown Online, Pocket Pikachu, and Megaman Battle Network. The visual identity should feel nostalgic yet fresh.

**Wabi-Sabi Influence:** Embrace imperfection, warmth, and organic feel. Avoid overly polished corporate aesthetics.

**Color Palette:** Define in `/src/styles/variables.css`. Prefer warm, inviting colors.

**Typography:** Friendly but readable. Consider a playful heading font paired with a clean body font.

---

## Technical Standards

### Vue 3 Conventions

- Use Composition API with `<script setup>` syntax
- Single File Components (.vue)
- Scoped styles by default
- TypeScript optional but prop types required

### File Structure

```
src/
├── components/
│   ├── common/          # Reusable components (Button, Card, Section)
│   ├── layout/          # Header, Footer, Navigation
│   └── sections/        # Page sections (HeroSection, FeaturesSection)
├── content/
│   └── site-data.js     # Editable content separate from components
├── styles/
│   ├── variables.css    # CSS custom properties
│   └── global.css       # Base styles, resets
├── assets/
│   └── images/
├── App.vue
└── main.js
```

### Component Guidelines

**Naming:**
- PascalCase for component files: `HeroSection.vue`
- Components should be self-contained with clear, single responsibilities
- Prefix common components: `BaseButton.vue`, `BaseCard.vue`

**Props:**
```vue
<script setup>
defineProps({
  title: { type: String, required: true },
  subtitle: { type: String, default: '' }
})
</script>
```

**Content Separation:**
Keep text content in `/src/content/site-data.js` so it can be updated without modifying component logic:

```javascript
// src/content/site-data.js
export const hero = {
  title: "Toon Pets",
  subtitle: "Nurture, Feed, Evolve",
  description: "A virtual pet game where your choices shape who your companion becomes."
}

export const features = [
  { title: "Relationship-Focused", description: "..." },
  { title: "Evolution Through Food", description: "..." }
]
```

### Styling

**CSS Custom Properties (variables.css):**
```css
:root {
  /* Colors */
  --color-primary: #...;
  --color-secondary: #...;
  --color-background: #...;
  --color-text: #...;
  
  /* Typography */
  --font-heading: '...', sans-serif;
  --font-body: '...', sans-serif;
  
  /* Spacing */
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 2rem;
  --space-xl: 4rem;
  
  /* Breakpoints (for reference) */
  /* Mobile: < 640px */
  /* Tablet: 640px - 1024px */
  /* Desktop: > 1024px */
}
```

**Responsive Design:**
- Mobile-first approach
- Use CSS Grid and Flexbox for layouts
- Breakpoints: 640px (tablet), 1024px (desktop)

**Scoped Styles:**
```vue
<style scoped>
.hero {
  padding: var(--space-xl) var(--space-md);
}
</style>
```

---

## Components to Build

### Layout
- `AppHeader.vue` — Logo, navigation
- `AppFooter.vue` — Links, copyright

### Sections
- `HeroSection.vue` — Main headline, tagline, primary CTA
- `ConceptSection.vue` — Explain what Toon Pets is
- `FeaturesSection.vue` — Key game features with icons/illustrations
- `EvolutionSection.vue` — Showcase the food-based evolution mechanic
- `MediaSection.vue` — Screenshots, GIFs, or video
- `SignupSection.vue` — Email capture for updates

### Common
- `BaseButton.vue` — Primary and secondary variants
- `BaseCard.vue` — Reusable card component
- `SectionWrapper.vue` — Consistent section padding and max-width

---

## Content Strategy

**Current Phase (Business/Strategy):**
- Emphasize the unique game design
- Highlight market positioning and influences
- Professional but personality-filled tone

**Future Phase (Player Marketing):**
- Focus on emotional appeal and fun
- Showcase gameplay and pet personalities
- Strong download/wishlist CTA

Consider a config flag to switch messaging phases:
```javascript
// src/content/site-data.js
export const sitePhase = 'business' // or 'player'
```

---

## Accessibility

- Semantic HTML: `<header>`, `<main>`, `<section>`, `<footer>`
- Heading hierarchy: One `<h1>` per page, logical `<h2>`, `<h3>` structure
- Alt text for all images
- Sufficient color contrast
- Keyboard-navigable interactive elements

---

## Performance

- Optimize images before adding to repo
- Lazy-load images below the fold
- Minimize dependencies—vanilla CSS over utility frameworks
- Use `v-once` for static content sections

---

## Git Workflow

**Branch Naming:**
- `feat/add-hero-section`
- `fix/mobile-navigation`
- `content/update-features-text`

**Commit Messages:**
- `feat: add hero section with CTA`
- `fix: correct spacing on mobile`
- `content: update game description`

**Pull Requests:**
- Keep PRs focused on single features or fixes
- Preview builds are automatic—review before merging

---

## Do's and Don'ts

**Do:**
- Keep components small and focused
- Separate content from presentation
- Test on mobile viewport sizes
- Use CSS custom properties for consistency
- Write descriptive alt text

**Don't:**
- Hardcode text content in components
- Use inline styles
- Add unnecessary dependencies
- Forget mobile responsiveness
- Over-engineer—start simple