@gallop.software/canon 1.0.0

package/patterns/015-no-inline-hover-styles.md

@@ -0,0 +1,132 @@
+# Pattern 015: No Inline Hover Styles
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Styling  
+**Enforcement:** Documentation
+
+## Decision
+
+Use Tailwind hover/focus classes. Do not use inline styles for interactive states.
+
+## Rationale
+
+1. **CSS handles it** — Pseudo-classes work in stylesheets, not inline
+2. **No JavaScript** — Hover effects without React state
+3. **Performance** — No re-renders on hover
+4. **Consistency** — All hover states follow Tailwind patterns
+
+## Examples
+
+### Good: Tailwind Pseudo-Classes
+
+```tsx
+<button className="
+  bg-accent text-white
+  hover:bg-accent2
+  focus:ring-2 focus:ring-accent
+  active:bg-accent3
+  transition-colors
+">
+  Click Me
+</button>
+```
+
+### Bad: State-Based Styling
+
+```tsx
+function Button() {
+  const [isHovered, setIsHovered] = useState(false)
+  
+  return (
+    <button
+      style={{ backgroundColor: isHovered ? '#6b4a3a' : '#8b5a4a' }}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      Click Me
+    </button>
+  )
+}
+```
+
+## Common Hover Patterns
+
+### Color Changes
+
+```tsx
+// Background color
+<div className="bg-gray-100 hover:bg-gray-200">
+
+// Text color
+<a className="text-body hover:text-accent">
+
+// Border color
+<div className="border-gray-300 hover:border-accent">
+```
+
+### Transforms
+
+```tsx
+// Scale up on hover
+<div className="hover:scale-105 transition-transform">
+
+// Lift effect
+<div className="hover:-translate-y-1 hover:shadow-lg transition-all">
+```
+
+### Opacity
+
+```tsx
+// Fade in overlay
+<div className="opacity-0 hover:opacity-100 transition-opacity">
+
+// Dim on hover
+<button className="hover:opacity-80 transition-opacity">
+```
+
+### Group Hover
+
+```tsx
+// Parent hover affects child
+<div className="group">
+  <img className="group-hover:scale-110 transition-transform" />
+  <span className="group-hover:text-accent">Title</span>
+</div>
+```
+
+## Focus States
+
+Always include focus states for accessibility:
+
+```tsx
+<button className="
+  hover:bg-accent2
+  focus:outline-none focus:ring-2 focus:ring-accent focus:ring-offset-2
+">
+```
+
+## Transitions
+
+Add transitions for smooth effects:
+
+```tsx
+// Single property
+<div className="transition-colors duration-200">
+
+// Multiple properties
+<div className="transition-all duration-300">
+
+// Specific properties
+<div className="transition-[transform,opacity] duration-200">
+```
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Check:** No `onMouseEnter`/`onMouseLeave` for styling
+
+## References
+
+- Tailwind hover/focus docs
+- `src/components/button.tsx` — Button with hover states

package/patterns/016-client-extraction.md

@@ -0,0 +1,149 @@
+# Pattern 016: Client Extraction
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Rendering  
+**Enforcement:** ESLint (via 001)
+
+## Decision
+
+Extract client-side logic (hooks, event handlers) into dedicated client components. Blocks and most components should remain server components.
+
+## Rationale
+
+1. **Minimal client JavaScript** — Only interactive parts need client runtime
+2. **Better performance** — Server components don't add to bundle
+3. **Clear boundaries** — Easy to identify what runs where
+4. **Easier testing** — Server components are pure renders
+
+## Extraction Patterns
+
+### Pattern A: Init Components (Side Effects Only)
+
+For effects that don't render UI, create "init" components that return null:
+
+```tsx
+// src/hooks/use-circle-animation.tsx
+'use client'
+import { useEffect } from 'react'
+import { useInView } from 'react-intersection-observer'
+
+export default function CircleAnimationInit({ targetId }: { targetId: string }) {
+  const { ref, inView } = useInView({ threshold: 0.1 })
+  
+  useEffect(() => {
+    if (inView) {
+      // Animation logic
+    }
+  }, [inView, targetId])
+  
+  return null // No UI, just side effects
+}
+```
+
+Usage in server block:
+
+```tsx
+// src/blocks/hero-16.tsx (server component)
+import CircleAnimationInit from '@/hooks/use-circle-animation'
+
+export default function Hero16() {
+  return (
+    <Section>
+      <div id="circle-text">...</div>
+      <CircleAnimationInit targetId="circle-text" />
+    </Section>
+  )
+}
+```
+
+### Pattern B: Interactive Components
+
+For UI that needs interactivity, create client components:
+
+```tsx
+// src/components/video-popup.tsx
+'use client'
+import { useState } from 'react'
+import { Dialog } from '@headlessui/react'
+
+export function VideoPopup({ videoId }: { videoId: string }) {
+  const [isOpen, setIsOpen] = useState(false)
+  
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Play</button>
+      <Dialog open={isOpen} onClose={() => setIsOpen(false)}>
+        {/* Video player */}
+      </Dialog>
+    </>
+  )
+}
+```
+
+### Pattern C: Event Delegation
+
+For many clickable items, use event delegation:
+
+```tsx
+// src/components/sidebar-click-handler.tsx
+'use client'
+
+export function SidebarClickHandler({ children }: { children: React.ReactNode }) {
+  const handleClick = (e: React.MouseEvent) => {
+    const link = (e.target as HTMLElement).closest('a[data-sidebar]')
+    if (link) {
+      e.preventDefault()
+      // Handle sidebar navigation
+    }
+  }
+  
+  return <div onClick={handleClick}>{children}</div>
+}
+```
+
+## What Stays Server-Side
+
+- Static content rendering
+- Data fetching
+- Metadata generation
+- Layout structure
+
+## What Moves to Client
+
+- `useState`, `useEffect`, `useRef`
+- Event handlers (`onClick`, `onChange`)
+- Browser APIs (`window`, `document`)
+- Animation libraries (Framer Motion)
+- Third-party interactive widgets
+
+## Static IDs
+
+When server components need to reference DOM elements for client scripts:
+
+```tsx
+// Server component
+const sliderId = 'hero-slider'
+const circleId = 'hero-circle'
+
+return (
+  <>
+    <div id={sliderId}>...</div>
+    <div id={circleId}>...</div>
+    <SwiperSliderInit swiperId={sliderId} />
+    <CircleAnimationInit targetId={circleId} />
+  </>
+)
+```
+
+## Enforcement
+
+- **ESLint rule:** `gallop/no-client-blocks` (Pattern 001)
+- **Severity:** Warning
+
+## References
+
+- `src/hooks/use-circle-animation.tsx` — Init component pattern
+- `src/hooks/swiper-slider-init.tsx` — Init component pattern
+- `src/components/video-popup.tsx` — Interactive component pattern
+- `src/components/sidebar-stack/` — Event delegation pattern

package/patterns/017-seo-metadata.md

@@ -0,0 +1,181 @@
+# Pattern 017: SEO Metadata
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** SEO  
+**Enforcement:** Documentation
+
+## Decision
+
+Every page must have complete SEO metadata including Open Graph, Twitter cards, and structured data.
+
+## Rationale
+
+1. **Search visibility** — Proper metadata improves rankings
+2. **Social sharing** — OG/Twitter cards control previews
+3. **Rich results** — Structured data enables rich snippets
+4. **Consistency** — All pages follow the same pattern
+
+## Required Metadata
+
+### Core Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `title` | Yes | Page title with site name (50-60 chars) |
+| `description` | Yes | SEO description (150-160 chars) |
+| `keywords` | Yes | Array of relevant keywords |
+| `focusKeyword` | Yes | Primary keyword for the page |
+| `featuredImage` | Yes | OG image path |
+| `alternates.canonical` | Yes | Canonical URL |
+
+### Open Graph
+
+```typescript
+openGraph: {
+  type: 'website',           // or 'article' for blog posts
+  locale: 'en_US',
+  url: 'https://example.com/page',
+  siteName: 'Site Name',
+  title: 'Page Title',
+  description: 'Page description',
+  image: {
+    url: '/images/og-image.jpg',
+    alt: 'Image description',
+  },
+}
+```
+
+### Twitter Cards
+
+```typescript
+twitter: {
+  card: 'summary_large_image',
+  site: '@sitehandle',
+  creator: '@authorhandle',
+  title: 'Page Title',
+  description: 'Page description',
+  image: '/images/twitter-image.jpg',
+}
+```
+
+### Structured Data
+
+```typescript
+structuredData: [
+  {
+    '@context': 'https://schema.org',
+    '@type': 'WebPage',      // or Organization, Product, Article, etc.
+    name: 'Page Title',
+    description: 'Page description',
+    // Additional properties based on type
+  },
+]
+```
+
+## Common Structured Data Types
+
+### Organization (Homepage)
+
+```typescript
+{
+  '@context': 'https://schema.org',
+  '@type': 'Organization',
+  name: 'Company Name',
+  url: 'https://example.com',
+  logo: 'https://example.com/logo.png',
+  contactPoint: {
+    '@type': 'ContactPoint',
+    telephone: '+1-555-555-5555',
+    contactType: 'customer service',
+  },
+}
+```
+
+### LocalBusiness (Contact Page)
+
+```typescript
+{
+  '@context': 'https://schema.org',
+  '@type': 'LocalBusiness',
+  name: 'Business Name',
+  address: {
+    '@type': 'PostalAddress',
+    streetAddress: '123 Main St',
+    addressLocality: 'City',
+    addressRegion: 'State',
+    postalCode: '12345',
+  },
+  telephone: '+1-555-555-5555',
+}
+```
+
+### Article (Blog Post)
+
+```typescript
+{
+  '@context': 'https://schema.org',
+  '@type': 'Article',
+  headline: 'Article Title',
+  author: {
+    '@type': 'Person',
+    name: 'Author Name',
+  },
+  datePublished: '2026-01-15',
+  dateModified: '2026-01-15',
+  image: 'https://example.com/article-image.jpg',
+}
+```
+
+### Product (Product Page)
+
+```typescript
+{
+  '@context': 'https://schema.org',
+  '@type': 'Product',
+  name: 'Product Name',
+  description: 'Product description',
+  brand: {
+    '@type': 'Brand',
+    name: 'Brand Name',
+  },
+  offers: {
+    '@type': 'Offer',
+    price: '99.00',
+    priceCurrency: 'USD',
+    availability: 'https://schema.org/InStock',
+  },
+}
+```
+
+## Image Guidelines
+
+### Featured/OG Images
+
+- Minimum size: 1200x630px
+- Recommended: 1200x630px (1.91:1 ratio)
+- Format: JPG or PNG
+- Max file size: 5MB
+
+### Twitter Images
+
+- Minimum: 300x157px
+- Recommended: 1200x600px (2:1 ratio)
+- Format: JPG, PNG, or GIF
+
+## Validation Tools
+
+- [Google Rich Results Test](https://search.google.com/test/rich-results)
+- [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/)
+- [Twitter Card Validator](https://cards-dev.twitter.com/validator)
+
+## Enforcement
+
+- **Method:** Code review / SEO audit
+- **Future:** CI validation of metadata completeness
+
+## References
+
+- `src/utils/page-helpers.ts` — Metadata generation utilities
+- `src/app/(hero)/page.tsx` — Homepage metadata example
+- Schema.org documentation: https://schema.org

package/schema.json

@@ -0,0 +1,245 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "Gallop Canon",
+  "version": "1.0.0",
+  "description": "Gallop Enterprise Architecture Canon - Versioned, AI-compatible, auditable web architecture patterns",
+  "categories": [
+    {
+      "id": "rendering",
+      "name": "Rendering",
+      "description": "Server/client component boundaries and rendering strategies"
+    },
+    {
+      "id": "layout",
+      "name": "Layout",
+      "description": "Layout hierarchy, spacing, and responsive design"
+    },
+    {
+      "id": "typography",
+      "name": "Typography",
+      "description": "Text component usage and styling"
+    },
+    {
+      "id": "structure",
+      "name": "Structure",
+      "description": "File and folder organization patterns"
+    },
+    {
+      "id": "styling",
+      "name": "Styling",
+      "description": "CSS, Tailwind, and visual styling patterns"
+    },
+    {
+      "id": "components",
+      "name": "Components",
+      "description": "Component design and implementation patterns"
+    },
+    {
+      "id": "seo",
+      "name": "SEO",
+      "description": "Search engine optimization and metadata patterns"
+    }
+  ],
+  "patterns": [
+    {
+      "id": "001",
+      "title": "Server-First Blocks",
+      "file": "patterns/001-server-first-blocks.md",
+      "category": "rendering",
+      "status": "stable",
+      "enforcement": "eslint",
+      "rule": "gallop/no-client-blocks",
+      "summary": "Blocks must be server components"
+    },
+    {
+      "id": "002",
+      "title": "Layout Hierarchy",
+      "file": "patterns/002-layout-hierarchy.md",
+      "category": "layout",
+      "status": "stable",
+      "enforcement": "eslint",
+      "rule": "gallop/no-container-in-section",
+      "summary": "No Container inside Section"
+    },
+    {
+      "id": "003",
+      "title": "Typography Components",
+      "file": "patterns/003-typography-components.md",
+      "category": "typography",
+      "status": "stable",
+      "enforcement": "eslint",
+      "rule": "gallop/prefer-typography-components",
+      "summary": "Use Paragraph/Span, not raw tags"
+    },
+    {
+      "id": "004",
+      "title": "Component Props",
+      "file": "patterns/004-component-props.md",
+      "category": "typography",
+      "status": "stable",
+      "enforcement": "eslint",
+      "rule": "gallop/prefer-component-props",
+      "summary": "Use props over className for supported styles"
+    },
+    {
+      "id": "005",
+      "title": "Page Structure",
+      "file": "patterns/005-page-structure.md",
+      "category": "structure",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "PageWrapper, generatePageMetadata pattern"
+    },
+    {
+      "id": "006",
+      "title": "Block Naming",
+      "file": "patterns/006-block-naming.md",
+      "category": "structure",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "{type}-{n}.tsx naming, PascalCase exports"
+    },
+    {
+      "id": "007",
+      "title": "Import Paths",
+      "file": "patterns/007-import-paths.md",
+      "category": "structure",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "@/ aliases, destructured imports"
+    },
+    {
+      "id": "008",
+      "title": "Tailwind Only",
+      "file": "patterns/008-tailwind-only.md",
+      "category": "styling",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "No inline styles, use Tailwind exclusively"
+    },
+    {
+      "id": "009",
+      "title": "Color Tokens",
+      "file": "patterns/009-color-tokens.md",
+      "category": "styling",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "Use semantic color tokens"
+    },
+    {
+      "id": "010",
+      "title": "Spacing System",
+      "file": "patterns/010-spacing-system.md",
+      "category": "layout",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "Standard padding/margin values"
+    },
+    {
+      "id": "011",
+      "title": "Responsive Mobile-First",
+      "file": "patterns/011-responsive-mobile-first.md",
+      "category": "layout",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "sm/md/lg/xl breakpoint usage"
+    },
+    {
+      "id": "012",
+      "title": "Icon System",
+      "file": "patterns/012-icon-system.md",
+      "category": "components",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "Iconify with Icon component"
+    },
+    {
+      "id": "013",
+      "title": "New Component Pattern",
+      "file": "patterns/013-new-component-pattern.md",
+      "category": "components",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "Props for margin/color/fontSize"
+    },
+    {
+      "id": "014",
+      "title": "clsx Not classnames",
+      "file": "patterns/014-clsx-not-classnames.md",
+      "category": "styling",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "Use clsx, never classnames package"
+    },
+    {
+      "id": "015",
+      "title": "No Inline Hover Styles",
+      "file": "patterns/015-no-inline-hover-styles.md",
+      "category": "styling",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "Tailwind for hover states"
+    },
+    {
+      "id": "016",
+      "title": "Client Extraction",
+      "file": "patterns/016-client-extraction.md",
+      "category": "rendering",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "Extract hooks to components, not blocks (see Pattern 001 for enforcement)"
+    },
+    {
+      "id": "017",
+      "title": "SEO Metadata",
+      "file": "patterns/017-seo-metadata.md",
+      "category": "seo",
+      "status": "stable",
+      "enforcement": "documentation",
+      "rule": null,
+      "summary": "PageMetadata structure, structured data"
+    }
+  ],
+  "guarantees": [
+    {
+      "id": "SEO_STABLE",
+      "name": "SEO Stability",
+      "since": "1.0.0",
+      "status": "stable",
+      "patterns": ["001", "016", "017"]
+    },
+    {
+      "id": "PERF_BASELINE",
+      "name": "Performance Baseline",
+      "since": "1.0.0",
+      "status": "stable",
+      "patterns": ["001", "007", "010", "016"]
+    },
+    {
+      "id": "MAINTAIN",
+      "name": "Maintainability",
+      "since": "1.0.0",
+      "status": "stable",
+      "patterns": ["004", "005", "006", "007", "013"]
+    },
+    {
+      "id": "DESIGN_SYSTEM",
+      "name": "Design System Compliance",
+      "since": "1.0.0",
+      "status": "stable",
+      "patterns": ["003", "004", "009", "010", "011"]
+    }
+  ]
+}