docs: add CONTRIBUTING.md with guidelines

2 months ago · 70d9ebaa4d
1 changed files with 335 additions and 0 deletions
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@ -0,0 +1,335 @@
				@@ -0,0 +1,335 @@
+# AI Coding Guidelines — wordofmouth.corneruniverse.com
+
+## Project Overview
+
+**Purpose:** Marketing website for Word of Mouth, a consultancy business.
+
+**Audience:** Potential clients seeking consultancy services.
+
+**Primary Goals:**
+1. Establish credibility and professionalism
+2. Clearly communicate services offered
+3. Convert visitors to contact/book a consultation
+4. Build trust through testimonials and expertise demonstration
+
+---
+
+## Design Direction
+
+**Aesthetic:** Professional, trustworthy, and approachable. Not cold corporate—warm professionalism. The design should convey expertise while remaining personable.
+
+**Mood:** Confident, clear, helpful. The visitor should feel they're in capable hands.
+
+**Color Palette:** Professional but not generic. Consider a primary color that stands out while remaining sophisticated. Define in `/src/styles/variables.css`.
+
+**Typography:** Clean, readable, professional. A modern sans-serif works well. Headings should command attention; body text should be easy to scan.
+
+**Whitespace:** Use generously. Consultancy sites benefit from breathing room—it conveys clarity of thought.
+
+---
+
+## 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, ServicesSection)
+├── content/
+│   └── site-data.js     # All editable content
+├── styles/
+│   ├── variables.css    # CSS custom properties
+│   └── global.css       # Base styles, resets
+├── assets/
+│   └── images/
+├── App.vue
+└── main.js
+```
+
+### Component Guidelines
+
+**Naming:**
+- PascalCase for component files: `ServicesSection.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 },
+  description: { type: String, default: '' }
+})
+</script>
+```
+
+### Content Management
+
+**All text content in `/src/content/site-data.js`:**
+```javascript
+export const hero = {
+  headline: "Strategic Consulting for Growing Businesses",
+  subheadline: "Clarity. Strategy. Results.",
+  cta: {
+    text: "Book a Consultation",
+    link: "#contact"
+  }
+}
+
+export const services = [
+  {
+    title: "Strategy Development",
+    description: "...",
+    icon: "strategy" // or image path
+  },
+  {
+    title: "Market Analysis",
+    description: "...",
+    icon: "analysis"
+  }
+]
+
+export const about = {
+  heading: "About",
+  text: "...",
+  image: "/images/headshot.jpg",
+  credentials: [
+    "10+ years experience",
+    "50+ clients served",
+    "Industry certification"
+  ]
+}
+
+export const testimonials = [
+  {
+    quote: "Working with Word of Mouth transformed our approach...",
+    author: "Jane Smith",
+    role: "CEO, Company Name"
+  }
+]
+
+export const contact = {
+  heading: "Let's Talk",
+  text: "Ready to take the next step? Get in touch.",
+  email: "[email protected]",
+  phone: "(555) 123-4567", // or null
+  calendlyLink: "https://calendly.com/..." // or null
+}
+```
+
+### Styling
+
+**CSS Custom Properties (variables.css):**
+```css
+:root {
+  /* Colors */
+  --color-primary: #...;
+  --color-primary-dark: #...;
+  --color-secondary: #...;
+  --color-background: #...;
+  --color-background-alt: #...;  /* For alternating sections */
+  --color-text: #...;
+  --color-text-light: #...;
+  
+  /* Typography */
+  --font-heading: '...', sans-serif;
+  --font-body: '...', sans-serif;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.25rem;
+  --font-size-xl: 1.5rem;
+  --font-size-2xl: 2rem;
+  --font-size-3xl: 3rem;
+  
+  /* Spacing */
+  --space-xs: 0.25rem;
+  --space-sm: 0.5rem;
+  --space-md: 1rem;
+  --space-lg: 2rem;
+  --space-xl: 4rem;
+  --space-2xl: 6rem;
+  
+  /* Layout */
+  --max-width: 1200px;
+  --section-padding: var(--space-2xl) var(--space-md);
+}
+```
+
+**Responsive Design:**
+- Mobile-first approach
+- Clean single-column on mobile, multi-column on desktop
+- CTA buttons should be prominent at all sizes
+
+---
+
+## Components to Build
+
+### Layout
+- `AppHeader.vue` — Logo, navigation, CTA button
+- `AppFooter.vue` — Contact info, links, copyright
+
+### Sections
+- `HeroSection.vue` — Headline, subheadline, primary CTA (most important)
+- `ServicesSection.vue` — Grid of service offerings
+- `AboutSection.vue` — Photo, bio, credentials
+- `TestimonialsSection.vue` — Client quotes (builds trust)
+- `ProcessSection.vue` — Optional: how the consultancy works (1, 2, 3 steps)
+- `ContactSection.vue` — Contact form or CTA to book
+
+### Common
+- `BaseButton.vue` — Primary (filled) and secondary (outlined) variants
+- `ServiceCard.vue` — Icon, title, description
+- `TestimonialCard.vue` — Quote, author, role
+- `SectionWrapper.vue` — Consistent section padding and max-width
+
+---
+
+## Call-to-Action Strategy
+
+**Primary CTA:** "Book a Consultation" or "Get in Touch"
+- Should appear in: Header, Hero, Contact section
+- Use primary button style (filled, prominent color)
+
+**Secondary CTA:** "Learn More" or section navigation
+- Use secondary button style (outlined or text link)
+
+**CTA Placement:**
+```
+[Header with CTA button]
+[Hero with prominent CTA]
+[Services]
+[About]
+[Testimonials]
+[Contact with CTA]
+[Footer]
+```
+
+The visitor should never be far from a way to take action.
+
+---
+
+## Trust Elements
+
+**Include these to build credibility:**
+- Professional headshot
+- Credentials or certifications
+- Client testimonials with real names (with permission)
+- Years of experience or clients served
+- Clear explanation of services and process
+
+**Testimonial Best Practices:**
+```vue
+<blockquote class="testimonial">
+  <p>"{{ testimonial.quote }}"</p>
+  <footer>
+    <cite>{{ testimonial.author }}</cite>
+    <span>{{ testimonial.role }}</span>
+  </footer>
+</blockquote>
+```
+
+---
+
+## Accessibility
+
+- Semantic HTML: `<header>`, `<main>`, `<section>`, `<footer>`
+- Heading hierarchy: One `<h1>` (the hero headline), logical `<h2>`, `<h3>` structure
+- Alt text for images (especially headshot)
+- Form labels for any input fields
+- Sufficient color contrast—especially for CTA buttons
+- Focus states for interactive elements
+
+---
+
+## Performance
+
+- Optimize the headshot and any images
+- Keep dependencies minimal
+- Fast load time builds trust—don't make visitors wait
+
+---
+
+## Git Workflow
+
+**Branch Naming:**
+- `feat/add-testimonials-section`
+- `fix/cta-button-contrast`
+- `content/update-services`
+
+**Commit Messages:**
+- `feat: add services section with card grid`
+- `fix: improve mobile navigation`
+- `content: update testimonials`
+
+---
+
+## Do's and Don'ts
+
+**Do:**
+- Keep messaging clear and benefit-focused
+- Make the CTA impossible to miss
+- Use professional, confident language
+- Include trust-building elements (testimonials, credentials)
+- Test on mobile—many visitors will come from LinkedIn or email links
+
+**Don't:**
+- Use jargon or buzzwords without substance
+- Hide the contact information
+- Use generic stock photos (real headshot preferred)
+- Clutter the page—whitespace is your friend
+- Forget to make the value proposition clear immediately
+
+---
+
+## Example Hero Section
+
+```vue
+<template>
+  <section class="hero">
+    <div class="hero-content">
+      <h1>{{ hero.headline }}</h1>
+      <p class="subheadline">{{ hero.subheadline }}</p>
+      <BaseButton :href="hero.cta.link" variant="primary" size="large">
+        {{ hero.cta.text }}
+      </BaseButton>
+    </div>
+  </section>
+</template>
+
+<script setup>
+import { hero } from '@/content/site-data.js'
+import BaseButton from '@/components/common/BaseButton.vue'
+</script>
+
+<style scoped>
+.hero {
+  min-height: 80vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: var(--section-padding);
+}
+
+.hero h1 {
+  font-size: var(--font-size-3xl);
+  margin-bottom: var(--space-md);
+}
+
+.subheadline {
+  font-size: var(--font-size-xl);
+  color: var(--color-text-light);
+  margin-bottom: var(--space-lg);
+}
+</style>
+```