# 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: "hello@wordofmouth.com",
  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>
```