From 12bbaf3ae73942fa8ff9ee5a9ebdb8a7e5948f3f Mon Sep 17 00:00:00 2001
From: Diego Vester <diego@corneruniverse.com>
Date: Sat, 24 Jan 2026 07:03:12 -0600
Subject: [PATCH] docs: add CONTRIBUTING.md with guidelines

---
 docs/CONTRIBUTING.md | 230 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 230 insertions(+)
 create mode 100644 docs/CONTRIBUTING.md

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 0000000..411c24c
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,230 @@
+# 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