@gallop.software/canon 1.0.0

package/patterns/010-spacing-system.md

@@ -0,0 +1,103 @@
+# Pattern 010: Spacing System
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Styling  
+**Enforcement:** Documentation
+
+## Decision
+
+Use consistent spacing values from the Tailwind scale. Follow established defaults for sections, typography, and layout.
+
+## Rationale
+
+1. **Visual rhythm** — Consistent spacing creates harmony
+2. **Predictable layouts** — Developers know what to expect
+3. **Easier maintenance** — Change defaults in one place
+4. **Design system compliance** — Spacing follows the scale
+
+## Default Spacing Values
+
+### Sections
+
+| Element | Default | Description |
+|---------|---------|-------------|
+| Section padding (vertical) | `py-20 md:py-30` | Top and bottom padding |
+| Section padding (horizontal) | `px-6 lg:px-8` | Left and right padding |
+| Max width | `max-w-[1600px]` | Content container width |
+
+### Typography
+
+| Element | Default | Description |
+|---------|---------|-------------|
+| Heading margin | `mb-8` | All heading levels |
+| Paragraph margin | `mb-8` | Body text blocks |
+| Label margin | `mb-0` | Inline labels |
+| Accent margin | `mb-4` | When above headings |
+| Accent margin (decorative) | `mb-0` | When rotated/decorative |
+
+### Layout
+
+| Element | Default | Description |
+|---------|---------|-------------|
+| Column gap | `gap-8 lg:gap-16` | Between columns |
+| Card padding | `p-6` | Internal card padding |
+| Button spacing | `gap-4` | Between buttons |
+
+## Examples
+
+### Section Structure
+
+```tsx
+<Section className="py-20 md:py-30">
+  <div className="mx-auto max-w-[1600px] px-6 lg:px-8">
+    <Heading margin="mb-8">Section Title</Heading>
+    <Paragraph margin="mb-8">Content paragraph.</Paragraph>
+  </div>
+</Section>
+```
+
+### Typography Stack
+
+```tsx
+<Accent margin="mb-4">Featured</Accent>
+<Heading margin="mb-8">Main Heading</Heading>
+<Paragraph margin="mb-8">First paragraph of content.</Paragraph>
+<Paragraph margin="mb-0">Final paragraph, no margin.</Paragraph>
+```
+
+### Columns Layout
+
+```tsx
+<Columns
+  cols="grid-cols-1 lg:grid-cols-2"
+  gap="gap-8 lg:gap-16"
+>
+  <Column>Left content</Column>
+  <Column>Right content</Column>
+</Columns>
+```
+
+## Spacing Scale Reference
+
+| Class | Value |
+|-------|-------|
+| `*-4` | 1rem (16px) |
+| `*-6` | 1.5rem (24px) |
+| `*-8` | 2rem (32px) |
+| `*-10` | 2.5rem (40px) |
+| `*-12` | 3rem (48px) |
+| `*-16` | 4rem (64px) |
+| `*-20` | 5rem (80px) |
+| `*-30` | 7.5rem (120px) |
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Component defaults:** Typography components have built-in margins
+
+## References
+
+- `src/components/section.tsx` — Section with default padding
+- `src/components/heading.tsx` — Heading with mb-8 default
+- `src/components/paragraph.tsx` — Paragraph with mb-8 default

package/patterns/011-responsive-mobile-first.md

@@ -0,0 +1,120 @@
+# Pattern 011: Responsive Mobile-First
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Styling  
+**Enforcement:** Documentation
+
+## Decision
+
+Design mobile-first. Use Tailwind breakpoint prefixes to progressively enhance for larger screens.
+
+## Rationale
+
+1. **Performance** — Mobile styles load first, enhancements are additive
+2. **Accessibility** — Core experience works on all devices
+3. **Maintainability** — Base styles are simple, complexity added at breakpoints
+4. **SEO** — Google uses mobile-first indexing
+
+## Breakpoint Scale
+
+| Prefix | Min Width | Target |
+|--------|-----------|--------|
+| (none) | 0px | Mobile phones |
+| `sm:` | 640px | Large phones, small tablets |
+| `md:` | 768px | Tablets |
+| `lg:` | 1024px | Laptops, small desktops |
+| `xl:` | 1280px | Desktops |
+| `2xl:` | 1536px | Large desktops |
+
+## Common Patterns
+
+### Layout Direction
+
+```tsx
+// Stack on mobile, row on desktop
+<div className="flex flex-col lg:flex-row">
+```
+
+### Grid Columns
+
+```tsx
+// 1 column mobile, 2 columns tablet, 3 columns desktop
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
+```
+
+### Responsive Typography
+
+```tsx
+// Smaller on mobile, larger on desktop
+<Heading fontSize="text-3xl md:text-4xl lg:text-5xl">
+  Responsive Heading
+</Heading>
+```
+
+### Responsive Spacing
+
+```tsx
+// Less padding on mobile, more on desktop
+<Section className="py-12 md:py-20 lg:py-30">
+```
+
+### Responsive Heights
+
+```tsx
+// Shorter on mobile, taller on desktop
+<div className="h-[300px] sm:h-[450px] lg:h-[600px]">
+```
+
+### Show/Hide Elements
+
+```tsx
+// Hide on mobile, show on desktop
+<nav className="hidden lg:flex">
+
+// Show on mobile, hide on desktop
+<button className="lg:hidden">Menu</button>
+```
+
+## Examples
+
+### Good: Mobile-First
+
+```tsx
+<div className="
+  flex flex-col gap-4
+  md:flex-row md:gap-8
+  lg:gap-16
+">
+  <div className="w-full md:w-1/2">Content</div>
+  <div className="w-full md:w-1/2">Content</div>
+</div>
+```
+
+### Bad: Desktop-First (Anti-Pattern)
+
+```tsx
+// Don't do this - starts with desktop, removes at mobile
+<div className="
+  flex flex-row gap-16
+  max-md:flex-col max-md:gap-4
+">
+```
+
+## Testing Checklist
+
+- [ ] Works on 320px width (small phones)
+- [ ] Works on 375px width (iPhone)
+- [ ] Works on 768px width (tablet)
+- [ ] Works on 1024px width (laptop)
+- [ ] Works on 1440px width (desktop)
+
+## Enforcement
+
+- **Method:** Code review / Visual testing
+- **Tools:** Browser DevTools responsive mode
+
+## References
+
+- Tailwind CSS responsive design docs
+- All blocks are built mobile-first

package/patterns/012-icon-system.md

@@ -0,0 +1,120 @@
+# Pattern 012: Icon System
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Components  
+**Enforcement:** Documentation
+
+## Decision
+
+Use Iconify icon packages with the `Icon` component. Do not use inline SVGs or other icon libraries.
+
+## Rationale
+
+1. **Consistent sizing** — Icon component handles dimensions
+2. **Tree shaking** — Only imported icons are bundled
+3. **Large library** — Access to thousands of icons
+4. **Type safety** — Icon imports are typed
+
+## Icon Packages
+
+| Package | Usage |
+|---------|-------|
+| `@iconify/icons-heroicons` | UI icons (arrows, actions) |
+| `@iconify/icons-lucide` | General purpose icons |
+| `@iconify/icons-mdi` | Material Design icons |
+| `@iconify/icons-simple-icons` | Brand/logo icons |
+
+## Usage Pattern
+
+### Import Icons
+
+```tsx
+import arrowRightIcon from '@iconify/icons-heroicons/arrow-right-20-solid'
+import playCircleIcon from '@iconify/icons-lucide/play-circle'
+import twitterIcon from '@iconify/icons-simple-icons/twitter'
+```
+
+### Render with Icon Component
+
+```tsx
+import { Icon } from '@/components'
+
+<Icon icon={arrowRightIcon} className="w-5 h-5" />
+<Icon icon={playCircleIcon} className="w-6 h-6 text-accent" />
+```
+
+### With Buttons
+
+```tsx
+<Button
+  href="/contact"
+  icon={arrowRightIcon}
+  iconPlacement="after"
+>
+  Get Started
+</Button>
+```
+
+## Common Icons
+
+| Icon | Import |
+|------|--------|
+| Arrow right | `@iconify/icons-heroicons/arrow-right-20-solid` |
+| Arrow down | `@iconify/icons-heroicons/arrow-down-20-solid` |
+| Play | `@iconify/icons-heroicons/play-solid` |
+| Play circle | `@iconify/icons-lucide/play-circle` |
+| Check | `@iconify/icons-heroicons/check-20-solid` |
+| X/Close | `@iconify/icons-heroicons/x-mark-20-solid` |
+| Menu | `@iconify/icons-heroicons/bars-3-20-solid` |
+| Sparkles | `@iconify/icons-heroicons/sparkles-20-solid` |
+
+## Examples
+
+### Good
+
+```tsx
+import arrowRightIcon from '@iconify/icons-heroicons/arrow-right-20-solid'
+import { Icon } from '@/components'
+
+<button className="flex items-center gap-2">
+  Next
+  <Icon icon={arrowRightIcon} className="w-5 h-5" />
+</button>
+```
+
+### Bad
+
+```tsx
+// Inline SVG
+<button>
+  Next
+  <svg className="w-5 h-5" viewBox="0 0 20 20">
+    <path d="M..." />
+  </svg>
+</button>
+
+// Other icon library
+import { ArrowRight } from 'react-icons/hi'
+<ArrowRight />
+```
+
+## Sizing Guidelines
+
+| Context | Size |
+|---------|------|
+| Inline with text | `w-4 h-4` or `w-5 h-5` |
+| Button icons | `w-5 h-5` |
+| Standalone icons | `w-6 h-6` |
+| Large decorative | `w-8 h-8` or larger |
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Future:** ESLint rule to detect inline SVGs
+
+## References
+
+- `src/components/icon.tsx` — Icon component
+- `src/components/button.tsx` — Button with icon support
+- Iconify icon explorer: https://icon-sets.iconify.design/

package/patterns/013-new-component-pattern.md

@@ -0,0 +1,135 @@
+# Pattern 013: New Component Pattern
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Components  
+**Enforcement:** Documentation
+
+## Decision
+
+New components expose props for commonly overridden styles instead of relying solely on `className`.
+
+## Rationale
+
+1. **Discoverable API** — Props appear in autocomplete
+2. **Consistent defaults** — Sensible defaults built-in
+3. **Type safety** — Props can be typed and documented
+4. **Easier refactoring** — Change defaults in one place
+5. **Lint compatibility** — Works with `prefer-component-props` rule
+
+## Component Template
+
+```tsx
+import { clsx } from 'clsx'
+
+interface MyComponentProps {
+  margin?: string       // e.g., "mb-8", "mb-4"
+  color?: string        // e.g., "text-accent", "text-contrast"
+  fontSize?: string     // e.g., "text-lg", "text-sm"
+  textAlign?: string    // e.g., "text-center", "text-left"
+  fontWeight?: string   // e.g., "font-bold", "font-medium"
+  className?: string    // Additional styling
+  children: React.ReactNode
+}
+
+export function MyComponent({
+  margin = 'mb-4',           // Sensible default
+  color = 'text-contrast',   // Sensible default
+  fontSize = 'text-base',
+  textAlign = '',
+  fontWeight = '',
+  className = '',
+  children,
+}: MyComponentProps) {
+  return (
+    <div
+      className={clsx(
+        margin,
+        color,
+        fontSize,
+        textAlign,
+        fontWeight,
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+```
+
+## Standard Props
+
+| Prop | Type | Common Values |
+|------|------|---------------|
+| `margin` | string | `mb-0`, `mb-4`, `mb-8` |
+| `color` | string | `text-body`, `text-contrast`, `text-accent` |
+| `fontSize` | string | `text-sm`, `text-base`, `text-lg`, `text-xl` |
+| `textAlign` | string | `text-left`, `text-center`, `text-right` |
+| `fontWeight` | string | `font-normal`, `font-medium`, `font-bold` |
+| `lineHeight` | string | `leading-tight`, `leading-relaxed` |
+| `className` | string | Any additional Tailwind classes |
+
+## File Structure
+
+1. Create file in `src/components/` with lowercase hyphenated name
+2. Export from `src/components/index.ts`
+3. Use `clsx` for combining classes
+
+```
+src/components/
+├── my-component.tsx    ← Component file
+├── index.ts            ← Add export here
+```
+
+## Examples
+
+### Good: Props for Common Overrides
+
+```tsx
+// Definition
+export function Badge({
+  margin = 'mb-0',
+  color = 'text-white',
+  bgColor = 'bg-accent',
+  fontSize = 'text-xs',
+  className = '',
+  children,
+}: BadgeProps) {
+  return (
+    <span className={clsx(margin, color, bgColor, fontSize, 'px-2 py-1 rounded', className)}>
+      {children}
+    </span>
+  )
+}
+
+// Usage
+<Badge color="text-black" bgColor="bg-yellow-400">New</Badge>
+```
+
+### Bad: className-Only Styling
+
+```tsx
+// Definition - no props for common overrides
+export function Badge({ className, children }: { className?: string; children: React.ReactNode }) {
+  return (
+    <span className={clsx('text-xs px-2 py-1 rounded', className)}>
+      {children}
+    </span>
+  )
+}
+
+// Usage - must override via className
+<Badge className="text-black bg-yellow-400 mb-4">New</Badge>
+```
+
+## Enforcement
+
+- **Method:** Code review / Documentation
+- **Lint:** `gallop/prefer-component-props` encourages prop usage
+
+## References
+
+- `src/components/paragraph.tsx` — Example with full prop support
+- `src/components/heading.tsx` — Example with full prop support
+- `src/components/label.tsx` — Example with full prop support

package/patterns/014-clsx-not-classnames.md

@@ -0,0 +1,128 @@
+# Pattern 014: clsx Not classnames
+
+**Canon Version:** 1.0  
+**Status:** Stable  
+**Category:** Styling  
+**Enforcement:** Documentation
+
+## Decision
+
+Use `clsx` for conditional class names. Do not use the `classnames` package.
+
+## Rationale
+
+1. **Smaller bundle** — clsx is ~234B vs classnames ~454B
+2. **Faster runtime** — clsx is optimized for performance
+3. **Same API** — Drop-in replacement, familiar syntax
+4. **Project standard** — Consistency across codebase
+
+## Usage
+
+### Import
+
+```tsx
+import { clsx } from 'clsx'
+```
+
+### Basic Conditionals
+
+```tsx
+<div className={clsx(
+  'base-class',
+  isActive && 'active-class',
+  isDisabled && 'disabled-class'
+)}>
+```
+
+### Object Syntax
+
+```tsx
+<div className={clsx({
+  'base-class': true,
+  'active-class': isActive,
+  'disabled-class': isDisabled,
+})}>
+```
+
+### Array Syntax
+
+```tsx
+<div className={clsx([
+  'base-class',
+  isActive ? 'active-class' : 'inactive-class',
+])}>
+```
+
+### Combining Props and Conditions
+
+```tsx
+function Button({ className, isLoading }: Props) {
+  return (
+    <button
+      className={clsx(
+        'px-4 py-2 rounded font-medium',
+        'bg-accent text-accent-contrast',
+        'hover:bg-accent2 transition-colors',
+        isLoading && 'opacity-50 cursor-not-allowed',
+        className // Allow additional classes from parent
+      )}
+    >
+      {isLoading ? 'Loading...' : children}
+    </button>
+  )
+}
+```
+
+## Examples
+
+### Good
+
+```tsx
+import { clsx } from 'clsx'
+
+<div className={clsx(
+  'flex items-center gap-2',
+  variant === 'primary' && 'bg-accent text-white',
+  variant === 'secondary' && 'bg-gray-100 text-gray-900',
+  disabled && 'opacity-50 pointer-events-none'
+)}>
+```
+
+### Bad
+
+```tsx
+// Using classnames package
+import classNames from 'classnames'
+
+<div className={classNames('flex', { 'bg-accent': isPrimary })}>
+
+// Template literals (harder to read)
+<div className={`flex ${isPrimary ? 'bg-accent' : ''}`}>
+
+// Array join (non-standard)
+<div className={['flex', isPrimary && 'bg-accent'].filter(Boolean).join(' ')}>
+```
+
+## Migration from classnames
+
+```tsx
+// Before
+import classNames from 'classnames'
+classNames('foo', { bar: true })
+
+// After
+import { clsx } from 'clsx'
+clsx('foo', { bar: true })
+```
+
+The API is identical — just change the import.
+
+## Enforcement
+
+- **Method:** Code review / package.json audit
+- **Check:** `classnames` should not appear in dependencies
+
+## References
+
+- clsx GitHub: https://github.com/lukeed/clsx
+- All components use clsx for conditional classes