@gallop.software/canon 1.0.0

package/patterns/003-typography-components.md

@@ -0,0 +1,78 @@
+# Pattern 003: Typography Components
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Typography  
+**Enforcement:** ESLint
+
+## Decision
+
+Use `Paragraph` and `Span` components instead of raw `<p>` and `<span>` elements in blocks and components.
+
+## Rationale
+
+1. **Consistent styling** — Typography components apply default margins, colors, and fonts
+2. **Prop-based customization** — Override styles via props, not className hunting
+3. **Design system compliance** — All text follows the same patterns
+4. **Easier refactoring** — Change defaults in one place
+
+## Examples
+
+### Bad
+
+```tsx
+<p className="text-sm text-gray-500 mb-4">Some descriptive text</p>
+<span className="text-green-500 font-medium">+28%</span>
+```
+
+### Good
+
+```tsx
+<Paragraph fontSize="text-sm" color="text-gray-500">
+  Some descriptive text
+</Paragraph>
+<Span color="text-green-500" fontWeight="font-medium">+28%</Span>
+```
+
+## Available Typography Components
+
+| Component | Default Tag | Default Margin | Use Case |
+|-----------|-------------|----------------|----------|
+| `Heading` | `h2` | `mb-8` | All headings |
+| `Paragraph` | `p` | `mb-8` | Body text blocks |
+| `Span` | `span` | `mb-0` | Inline text |
+| `Label` | `p` | `mb-0` | Labels, captions |
+| `Quote` | `blockquote` | `mb-8` | Quotations |
+| `Accent` | `span` | `mb-4` | Decorative accent text |
+
+## Exceptions
+
+Raw `<span>` is allowed when:
+
+1. **Inside typography components** — For inline styling within Heading, Paragraph, etc.
+2. **Gradient text effects** — When using `bg-clip-text` for gradient text
+
+```tsx
+{/* Allowed: span inside Heading for gradient effect */}
+<Heading>
+  Transform your space into something{' '}
+  <span className="bg-gradient-to-r from-purple-600 to-pink-500 bg-clip-text text-transparent">
+    extraordinary
+  </span>
+</Heading>
+```
+
+## Enforcement
+
+- **ESLint rule:** `gallop/prefer-typography-components`
+- **Severity:** Warning
+
+## Escape Hatch
+
+For gradient text or complex inline styling, raw `<span>` with `bg-clip-text` is allowed.
+
+## References
+
+- `src/components/paragraph.tsx` — Paragraph component
+- `src/components/span.tsx` — Span component
+- `src/components/heading.tsx` — Heading component

package/patterns/004-component-props.md

@@ -0,0 +1,102 @@
+# Pattern 004: Component Props Over className
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Typography  
+**Enforcement:** ESLint
+
+## Decision
+
+Use dedicated props instead of `className` for styling that components support.
+
+## Rationale
+
+1. **Discoverable API** — Props are documented and autocompleted
+2. **Consistent defaults** — Components define sensible defaults
+3. **Easier auditing** — Can search for prop usage, not className patterns
+4. **Type safety** — Props can be typed, className cannot
+
+## Examples
+
+### Bad
+
+```tsx
+<Heading className="text-center mb-6 text-accent">Title</Heading>
+<Paragraph className="text-lg mb-4">Text content</Paragraph>
+<Label className="text-sm font-semibold">Category</Label>
+```
+
+### Good
+
+```tsx
+<Heading textAlign="text-center" margin="mb-6" color="text-accent">
+  Title
+</Heading>
+<Paragraph fontSize="text-lg" margin="mb-4">
+  Text content
+</Paragraph>
+<Label fontSize="text-sm" fontWeight="font-semibold">
+  Category
+</Label>
+```
+
+## Supported Props by Component
+
+### Heading
+- `margin` — Bottom margin (e.g., `mb-8`, `mb-4`)
+- `color` — Text color (e.g., `text-contrast`, `text-accent`)
+- `textAlign` — Alignment (e.g., `text-center`, `text-left`)
+- `fontSize` — Size (e.g., `text-4xl`, `text-2xl`)
+- `fontWeight` — Weight (e.g., `font-bold`, `font-semibold`)
+
+### Paragraph
+- `margin` — Bottom margin
+- `color` — Text color
+- `textAlign` — Alignment
+- `fontSize` — Size
+- `lineHeight` — Line height
+
+### Label
+- `margin` — Bottom margin
+- `color` — Text color
+- `textAlign` — Alignment
+- `fontSize` — Size
+- `fontWeight` — Weight
+
+### Accent
+- `margin` — Bottom margin
+- `color` — Text color
+- `textAlign` — Alignment
+
+### Button
+- `margin` — Bottom margin
+
+## When to Use className
+
+Use `className` for styles that are NOT covered by props:
+
+```tsx
+{/* max-w is not a prop, so className is appropriate */}
+<Paragraph className="max-w-lg">
+  Content with constrained width
+</Paragraph>
+```
+
+## Enforcement
+
+- **ESLint rule:** `gallop/prefer-component-props`
+- **Severity:** Warning
+- **Detected patterns:** `mb-*`, `my-*`, `m-*`, `text-center`, `text-left`, `text-right`, `font-*`, `text-{color}` in className
+
+## Escape Hatch
+
+If a component doesn't support a prop you need:
+
+1. Consider adding the prop to the component
+2. Use className as a fallback with a comment explaining why
+
+## References
+
+- `src/components/heading.tsx` — Heading with prop overrides
+- `src/components/paragraph.tsx` — Paragraph with prop overrides
+- `src/components/label.tsx` — Label with prop overrides

package/patterns/005-page-structure.md

@@ -0,0 +1,110 @@
+# Pattern 005: Page Structure
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Structure  
+**Enforcement:** Documentation
+
+## Decision
+
+Page files follow a consistent structure using `PageWrapper` and `generatePageMetadata`.
+
+## Rationale
+
+1. **Consistent metadata** — All pages have proper SEO metadata
+2. **Structured data** — Schema.org markup applied uniformly
+3. **Predictable layout** — Pages follow the same wrapper pattern
+4. **Easy auditing** — Can verify metadata completeness across all pages
+
+## Template
+
+```tsx
+import { PageWrapper } from '@/components/page-wrapper'
+import { generatePageMetadata, type PageMetadata } from '@/utils/page-helpers'
+
+import Hero1 from '@/blocks/hero-1'
+import Section1 from '@/blocks/section-1'
+
+function Content() {
+  return (
+    <>
+      <Hero1 />
+      <Section1 />
+    </>
+  )
+}
+
+const metadata: PageMetadata = {
+  title: 'Page Title | Site Name',
+  description: 'Page description for SEO (150-160 characters)',
+  keywords: ['keyword1', 'keyword2', 'keyword3'],
+  focusKeyword: 'primary keyword',
+  readingTimeMinutes: 5,
+  publishDate: '2026-01-15T00:00:00Z',
+  modifiedDate: '2026-01-15T00:00:00Z',
+  featuredImage: '/images/page-featured.jpg',
+  alternates: {
+    canonical: 'https://example.com/page-slug',
+  },
+  authors: [{ name: 'Author Name' }],
+  openGraph: {
+    type: 'website',
+    locale: 'en_US',
+    url: 'https://example.com/page-slug',
+    siteName: 'Site Name',
+    title: 'Page Title | Site Name',
+    description: 'Page description for SEO',
+    image: {
+      url: '/images/page-featured.jpg',
+      alt: 'Featured image description',
+    },
+  },
+  twitter: {
+    card: 'summary_large_image',
+    site: '@sitehandle',
+    creator: '@creatorhandle',
+    title: 'Page Title',
+    description: 'Page description for Twitter',
+    image: '/images/page-featured.jpg',
+  },
+  structuredData: [
+    {
+      '@context': 'https://schema.org',
+      '@type': 'WebPage',
+      name: 'Page Title',
+      description: 'Page description',
+    },
+  ],
+}
+
+export const generateMetadata = () => generatePageMetadata(metadata)
+export default function Page() {
+  return (
+    <PageWrapper metadata={metadata}>
+      <Content />
+    </PageWrapper>
+  )
+}
+```
+
+## Required Metadata Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `title` | Yes | Page title with site name |
+| `description` | Yes | SEO description (150-160 chars) |
+| `keywords` | Yes | Array of relevant keywords |
+| `focusKeyword` | Yes | Primary SEO keyword |
+| `featuredImage` | Yes | OG image path |
+| `alternates.canonical` | Yes | Canonical URL |
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Future:** CI validation of metadata completeness
+
+## References
+
+- `src/app/(hero)/page.tsx` — Homepage example
+- `src/components/page-wrapper.tsx` — PageWrapper component
+- `src/utils/page-helpers.ts` — Metadata utilities

package/patterns/006-block-naming.md

@@ -0,0 +1,87 @@
+# Pattern 006: Block Naming
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Structure  
+**Enforcement:** Documentation
+
+## Decision
+
+Block files use `{type}-{n}.tsx` naming with PascalCase function exports.
+
+## Rationale
+
+1. **Sequential organization** — Numbers indicate variants, not priority
+2. **Easy discovery** — Group by type in file explorer
+3. **No conflicts** — Numbers prevent naming collisions
+4. **Consistent exports** — PascalCase matches React conventions
+
+## Naming Rules
+
+### File Names
+
+- Lowercase with hyphens: `hero-1.tsx`, `section-15.tsx`
+- Type prefix followed by number: `{type}-{n}.tsx`
+- Check existing files to find next available number
+
+### Function Exports
+
+- PascalCase matching file name
+- `hero-16.tsx` → `function Hero16()`
+- `call-to-action-3.tsx` → `function CallToAction3()`
+
+## Block Types
+
+| Type | Description |
+|------|-------------|
+| `hero-{n}` | Hero/banner sections |
+| `section-{n}` | General content sections |
+| `content-{n}` | Content/feature sections |
+| `showcase-{n}` | Portfolio/gallery showcases |
+| `cover-{n}` | Full-width image/video covers |
+| `contact-{n}` | Contact forms and info |
+| `testimonial-{n}` | Testimonials |
+| `blog-{n}` | Blog-related sections |
+| `pricing-{n}` | Pricing tables |
+| `process-{n}` | Process/steps sections |
+| `about-{n}` | About sections |
+| `services-{n}` | Services sections |
+| `call-to-action-{n}` | CTA sections |
+| `partners-{n}` | Partner/logo clouds |
+| `accordion-{n}` | FAQ/accordion sections |
+| `archive-{n}` | Archive/listing sections |
+| `application-{n}` | Job application forms |
+| `business-info-{n}` | Business information |
+| `sidebar-{n}` | Sidebar panels |
+| `portfolio-{n}` | Portfolio grids |
+
+## Examples
+
+### Good
+
+```
+src/blocks/
+├── hero-1.tsx          → export default function Hero1()
+├── hero-2.tsx          → export default function Hero2()
+├── section-1.tsx       → export default function Section1()
+├── call-to-action-1.tsx → export default function CallToAction1()
+```
+
+### Bad
+
+```
+src/blocks/
+├── Hero.tsx            ❌ No number
+├── hero_1.tsx          ❌ Underscore instead of hyphen
+├── HeroSection.tsx     ❌ Wrong naming pattern
+├── cta-1.tsx           ❌ Abbreviation not in type list
+```
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Future:** CI validation of naming patterns
+
+## References
+
+- `src/blocks/` — All block files follow this pattern

package/patterns/007-import-paths.md

@@ -0,0 +1,113 @@
+# Pattern 007: Import Paths
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Structure  
+**Enforcement:** Documentation
+
+## Decision
+
+Use `@/` path aliases for all internal imports. Use destructured imports for components.
+
+## Rationale
+
+1. **Consistent paths** — No relative path gymnastics (`../../..`)
+2. **Refactoring safe** — Moving files doesn't break imports
+3. **Clear origin** — `@/` indicates project source
+4. **Smaller bundles** — Destructured imports enable tree shaking
+
+## Path Aliases
+
+| Alias | Resolves To | Example |
+|-------|-------------|---------|
+| `@/components` | `src/components` | `import { Heading } from '@/components'` |
+| `@/blocks` | `src/blocks` | `import Hero1 from '@/blocks/hero-1'` |
+| `@/hooks` | `src/hooks` | `import { useInView } from '@/hooks/use-in-view'` |
+| `@/template` | `src/template` | `import PageFooter from '@/template/page-footer'` |
+| `@/utils` | `src/utils` | `import { cn } from '@/utils/cn'` |
+
+## Import Patterns
+
+### Components (Destructured)
+
+```tsx
+// Good: Destructured import from barrel
+import { Heading, Paragraph, Button, Section, Columns, Column } from '@/components'
+
+// Bad: Individual file imports
+import { Heading } from '@/components/heading'
+import { Paragraph } from '@/components/paragraph'
+```
+
+### Blocks (Default Export)
+
+```tsx
+// Good: Default import with descriptive name
+import Hero1 from '@/blocks/hero-1'
+import Section3 from '@/blocks/section-3'
+
+// Bad: Named import (blocks use default exports)
+import { Hero1 } from '@/blocks/hero-1'
+```
+
+### Hooks (Named or Default)
+
+```tsx
+// Init components (return null, used for side effects)
+import CircleAnimationInit from '@/hooks/use-circle-animation'
+import SwiperSliderInit from '@/hooks/swiper-slider-init'
+
+// Traditional hooks
+import { useInView } from '@/hooks/use-in-view'
+```
+
+### Icons
+
+```tsx
+// Good: Import from Iconify packages
+import arrowRightIcon from '@iconify/icons-heroicons/arrow-right-20-solid'
+import playCircleIcon from '@iconify/icons-lucide/play-circle'
+
+// Use with Icon component
+<Icon icon={arrowRightIcon} className="w-5 h-5" />
+```
+
+## Examples
+
+### Good
+
+```tsx
+import {
+  Heading,
+  Paragraph,
+  Button,
+  Section,
+  Columns,
+  Column,
+  Image,
+} from '@/components'
+import Hero1 from '@/blocks/hero-1'
+import arrowDownIcon from '@iconify/icons-heroicons/arrow-down-20-solid'
+```
+
+### Bad
+
+```tsx
+// Relative imports
+import { Heading } from '../../components/heading'
+import Hero1 from '../blocks/hero-1'
+
+// Wrong alias format
+import { Heading } from 'components/heading'
+import { Heading } from '~/components/heading'
+```
+
+## Enforcement
+
+- **Method:** Code review / ESLint import rules
+- **Future:** Custom ESLint rule for path validation
+
+## References
+
+- `tsconfig.json` — Path alias configuration
+- `src/components/index.ts` — Component barrel file

package/patterns/008-tailwind-only.md

@@ -0,0 +1,97 @@
+# Pattern 008: Tailwind Only
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Styling  
+**Enforcement:** Documentation
+
+## Decision
+
+Use Tailwind CSS classes exclusively. Do not use inline styles or CSS-in-JS.
+
+## Rationale
+
+1. **Consistent styling** — All styles come from the same system
+2. **Design tokens** — Tailwind enforces spacing/color scales
+3. **Performance** — No runtime CSS generation
+4. **Scannable code** — Styles are visible in the JSX
+5. **Tooling support** — Tailwind IntelliSense, Prettier sorting
+
+## Examples
+
+### Good
+
+```tsx
+<div className="flex items-center gap-4 p-6 bg-white rounded-lg shadow-lg">
+  <Heading className="text-2xl">Title</Heading>
+</div>
+```
+
+### Bad
+
+```tsx
+// Inline styles
+<div style={{ display: 'flex', padding: '24px', backgroundColor: 'white' }}>
+  <Heading>Title</Heading>
+</div>
+
+// CSS-in-JS
+const StyledDiv = styled.div`
+  display: flex;
+  padding: 24px;
+`;
+```
+
+## Allowed Exceptions
+
+### Dynamic Values
+
+When a style value comes from data or calculations:
+
+```tsx
+// Allowed: Dynamic positioning
+<div style={{ left: `${position}px` }}>
+
+// Allowed: CSS custom properties for theming
+<div style={{ '--progress': `${percent}%` } as React.CSSProperties}>
+```
+
+### CSS Custom Properties
+
+```tsx
+// Allowed: Using CSS variables
+<div className="bg-[var(--color-accent)]">
+```
+
+### Complex Animations
+
+```tsx
+// Allowed: Framer Motion
+<motion.div animate={{ opacity: 1 }}>
+```
+
+## Conditional Classes
+
+Use `clsx` for conditional classes:
+
+```tsx
+import { clsx } from 'clsx'
+
+<button
+  className={clsx(
+    'px-4 py-2 rounded',
+    isActive && 'bg-accent text-white',
+    !isActive && 'bg-gray-100 text-gray-700'
+  )}
+>
+```
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Future:** ESLint rule to detect inline styles
+
+## References
+
+- `src/styles/tailwind.css` — Tailwind configuration
+- All blocks and components use Tailwind exclusively

package/patterns/009-color-tokens.md

@@ -0,0 +1,114 @@
+# Pattern 009: Color Tokens
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Styling  
+**Enforcement:** Documentation
+
+## Decision
+
+Use semantic color tokens instead of raw color values. Colors are defined as CSS custom properties.
+
+## Rationale
+
+1. **Theme consistency** — Colors change in one place
+2. **Semantic meaning** — `text-contrast` is clearer than `text-gray-800`
+3. **Dark mode ready** — Token values can change per theme
+4. **Accessibility** — Contrast ratios are pre-validated
+
+## Color Token System
+
+### Text Colors
+
+| Token | Usage |
+|-------|-------|
+| `text-body` | Default body text |
+| `text-contrast` | High-contrast text (headings, emphasis) |
+| `text-accent` | Accent/brand color text |
+| `text-accent-contrast` | Text on accent backgrounds |
+| `text-white` | White text |
+
+### Background Colors
+
+| Token | Usage |
+|-------|-------|
+| `bg-body` | Main page background |
+| `bg-body2` | Secondary/alternate background |
+| `bg-contrast` | High-contrast background |
+| `bg-accent` | Primary accent background |
+| `bg-accent2` | Secondary accent background |
+| `bg-accent3` | Tertiary accent background |
+
+### Pairing Rules
+
+Accent backgrounds pair with contrast variants:
+
+```tsx
+// Good: Proper pairing
+<div className="bg-accent text-accent-contrast">
+  Readable text on accent background
+</div>
+
+// Bad: May have contrast issues
+<div className="bg-accent text-body">
+  Potentially unreadable
+</div>
+```
+
+## Examples
+
+### Good
+
+```tsx
+<Section className="bg-body2">
+  <Heading color="text-contrast">Title</Heading>
+  <Paragraph color="text-body">Body content</Paragraph>
+  <Button className="bg-accent text-accent-contrast">
+    Call to Action
+  </Button>
+</Section>
+```
+
+### Bad
+
+```tsx
+<Section className="bg-gray-100">
+  <Heading className="text-gray-900">Title</Heading>
+  <Paragraph className="text-gray-600">Body content</Paragraph>
+  <Button className="bg-purple-600 text-white">
+    Call to Action
+  </Button>
+</Section>
+```
+
+## CSS Variable Definitions
+
+```css
+:root {
+  --color-body: #171412;
+  --color-body2: #f2eae7;
+  --color-contrast: #1a1a1a;
+  --color-accent: #8b5a4a;
+  --color-accent2: #6b4a3a;
+  --color-accent3: #f2ebe1;
+  --color-accent-contrast: #ffffff;
+}
+```
+
+## When to Use Raw Colors
+
+Raw Tailwind colors are acceptable for:
+
+1. **Third-party content** — Colors from external data
+2. **One-off decorative elements** — Gradients, shadows
+3. **Status indicators** — `text-green-500` for success
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Future:** ESLint rule to prefer tokens
+
+## References
+
+- `src/styles/tailwind.css` — Color token definitions
+- `src/components/button.tsx` — Button using accent tokens