docs: add CONTRIBUTING.md with guidelines

2 months ago · d33494e6df
1 changed files with 322 additions and 0 deletions
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@ -0,0 +1,322 @@
 # Contribution Guidelines — lukastitch.corneruniverse.com
 ## Project Overview
 **Purpose:** Portfolio and showcase website for Luka Stitch, a handmade plushie business.
 **Audience:** Potential customers interested in custom plushies, people browsing her work, and commission inquiries.
 **Primary Goals:**
 1. Showcase plushie creations with beautiful imagery
 2. Communicate the handmade, personal nature of the work
 3. Direct commission inquiries to Etsy
 4. Build brand personality and connection
 **Note:** This is NOT an e-commerce site. No direct purchases. Etsy handles transactions.
 ---
 ## Design Direction
 **Aesthetic:** Warm, cozy, handcrafted feel. The design should reflect the care and personality that goes into each plushie. Think craft fair booth, not corporate storefront.
 **Mood:** Friendly, approachable, whimsical but not childish.
 **Color Palette:** Soft, warm colors. Pastels or muted tones that complement plushie photography without competing. Define in `/src/styles/variables.css`.
 **Typography:** Friendly and readable. A slightly playful heading font paired with a clean body font.
 **Imagery:** Photography is central. The design should frame and highlight the plushie images, not distract from them.
 ---
 ## 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)
 │   ├── layout/          # Header, Footer, Navigation
 │   └── sections/        # Page sections (HeroSection, GallerySection)
 ├── content/
 │   ├── site-data.js     # General site content
 │   └── plushies.js      # Plushie catalog data
 ├── styles/
 │   ├── variables.css    # CSS custom properties
 │   └── global.css       # Base styles, resets
 ├── assets/
 │   └── images/
 │       └── plushies/    # Plushie photos
 ├── App.vue
 └── main.js
 ```
 ### Component Guidelines
 **Naming:**
 * PascalCase for component files: `GallerySection.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 },
  image: { type: String, required: true },
  available: { type: Boolean, default: false }
 })
 </script>
 ```
 ### Content Management
 **This is critical:** The site owner will want to add new plushies regularly. Make this easy.
 **Plushie Catalog (**`/src/content/plushies.js`):
 ```javascript
 export const plushies = [
  {
    id: 'cozy-bear',
    name: 'Cozy Bear',
    image: '/images/plushies/cozy-bear.jpg',
    description: 'A huggable friend for cold nights.',
    size: '12 inches',
    available: false,
    etsyLink: null
  },
  {
    id: 'sleepy-fox',
    name: 'Sleepy Fox',
    image: '/images/plushies/sleepy-fox.jpg',
    description: 'Always ready for a nap.',
    size: '10 inches',
    available: true,
    etsyLink: 'https://etsy.com/...'
  }
 ]
 ```
 **Site Content (**`/src/content/site-data.js`):
 ```javascript
 export const hero = {
  title: "Luka Stitch",
  tagline: "Handmade plushies with love",
  description: "Each creation is one-of-a-kind, crafted with care."
 }
 export const about = {
  heading: "About",
  text: "...",
  image: "/images/about-photo.jpg"
 }
 export const contact = {
  heading: "Get in Touch",
  text: "Interested in a custom plushie? Reach out!",
  etsyLink: "https://etsy.com/shop/...",
  email: "[email protected]" // or null if not wanted
 }
 ```
 ### Styling
 **CSS Custom Properties (variables.css):**
 ```css
 :root {
  /* Colors */
  --color-primary: #...;
  --color-secondary: #...;
  --color-background: #...;
  --color-text: #...;
  --color-accent: #...;
  /* 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;
  /* Gallery */
  --gallery-gap: 1rem;
  --card-radius: 8px;
 }
 ```
 **Responsive Design:**
 * Mobile-first approach
 * Gallery should be responsive: 1 column mobile, 2 tablet, 3-4 desktop
 * Images should scale beautifully at all sizes
 ---
 ## Components to Build
 ### Layout
 * `AppHeader.vue` — Logo/name, simple navigation
 * `AppFooter.vue` — Social links, copyright
 ### Sections
 * `HeroSection.vue` — Brand name, tagline, featured image or plushie
 * `GallerySection.vue` — Grid of plushies from catalog
 * `AboutSection.vue` — The maker's story, photo
 * `ContactSection.vue` — How to reach out, Etsy link
 ### Common
 * `BaseButton.vue` — Primary and secondary variants
 * `PlushieCard.vue` — Image, name, description, availability badge, Etsy link
 * `SectionWrapper.vue` — Consistent section padding and max-width
 * `ImageLightbox.vue` — Optional: click to enlarge plushie photos
 ---
 ## Gallery & Image Handling
 **PlushieCard Component:**
 ```vue
 <template>
  <article class="plushie-card">
    <img :src="plushie.image" :alt="plushie.name" />
    <h3>{{ plushie.name }}</h3>
    <p>{{ plushie.description }}</p>
    <span v-if="plushie.available" class="badge available">Available</span>
    <span v-else class="badge sold">Sold</span>
    <a v-if="plushie.etsyLink" :href="plushie.etsyLink" target="_blank" rel="noopener">
      View on Etsy
    </a>
  </article>
 </template>
 ```
 **Gallery Grid:**
 ```css
 .gallery {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: var(--gallery-gap);
 }
 ```
 **Image Guidelines:**
 * Consistent aspect ratio preferred (square or 4:3)
 * Optimize images before adding (compress, reasonable resolution)
 * Use descriptive filenames: `cozy-bear.jpg` not `IMG_3847.jpg`
 * Alt text should describe the plushie
 ---
 ## Adding New Plushies (Instructions for Site Owner)
 1. Add the photo to `/public/images/plushies/`
 2. Open `/src/content/plushies.js`
 3. Add a new entry to the array:
 ```javascript
 {
  id: 'new-plushie-name',
  name: 'New Plushie Name',
  image: '/images/plushies/new-plushie-name.jpg',
  description: 'A short description.',
  size: '10 inches',
  available: true,
  etsyLink: 'https://etsy.com/listing/...'
 }
 ```
 4. Commit and push—the site auto-deploys
 ---
 ## Accessibility
 * Semantic HTML: `<header>`, `<main>`, `<section>`, `<footer>`
 * Heading hierarchy: One `<h1>` per page, logical structure
 * Alt text for ALL plushie images (describe the plushie)
 * Sufficient color contrast
 * Links clearly identifiable
 ---
 ## Performance
 * Optimize plushie photos before adding (use tools like Squoosh)
 * Consider lazy-loading gallery images
 * Keep the site lightweight—no heavy frameworks needed
 * Use `loading="lazy"` on images below the fold
 ---
 ## Git Workflow
 **Branch Naming:**
 * `feat/add-gallery-section`
 * `fix/mobile-card-layout`
 * `content/add-new-plushies`
 **Commit Messages:**
 * `feat: add plushie gallery with grid layout`
 * `fix: improve image scaling on mobile`
 * `content: add sleepy fox plushie`
 ---
 ## Do's and Don'ts
 **Do:**
 * Make the plushies the star—design should highlight, not compete
 * Keep adding new plushies simple and documented
 * Optimize every image before adding
 * Test gallery on mobile
 * Use warm, inviting language
 **Don't:**
 * Add e-commerce functionality (Etsy handles sales)
 * Use stock photos—only real plushie photography
 * Clutter the design—let the work speak
 * Forget alt text on images
 * Make the owner dig through code to add content