npm package: @gallop.software/canon
Description: Gallop Canon - Architecture patterns, ESLint plugin, and CLI for template governance
Author: Gallop
Latest version: 2.34.0

# @gallop.software/canon

**Gallop Canon** — A versioned, AI-compatible, auditable system of approved web architecture patterns.

## What is the Canon?

The Canon is a closed set of authoritative patterns that define how web applications should be built. Each pattern is:

- **Versioned** — Pin to a specific version, upgrade deliberately
- **Documented** — Decision-level documentation, not just code comments
- **Enforced** — ESLint rules, CI validation, or AI constraints
- **Immutable** — Once released, patterns don't change

## Installation

```bash
npm install @gallop.software/canon
```

## ESLint Setup

Add Canon rules to your `eslint.config.mjs`:

```javascript
import nextConfig from 'eslint-config-next'
import gallop from '@gallop.software/canon/eslint'

export default [
  ...nextConfig,
  {
    files: ['src/app/**/_blocks/**/*.tsx', 'src/components/**/*.tsx'],
    plugins: {
      gallop,
    },
    rules: {
      ...gallop.recommended,
    },
  },
]
```

### Opting Out of Rules

To disable specific rules, override them after spreading `recommended`:

```javascript
rules: {
  ...gallop.recommended,
  // Disable specific rules
  'gallop/no-inline-styles': 'off',
  'gallop/no-arbitrary-colors': 'off',
}
```

To change a rule from warning to error:

```javascript
rules: {
  ...gallop.recommended,
  'gallop/no-cross-zone-imports': 'error',
}
```

### Available Rules

| Rule | Description |
|------|-------------|
| `gallop/no-client-blocks` | Blocks must be server components |
| `gallop/block-naming-convention` | Block export names must match filename |
| `gallop/no-container-in-section` | No Container inside Section |
| `gallop/prefer-component-props` | Use props over className for styles |
| `gallop/prefer-typography-components` | Use Paragraph/Span, not raw tags |
| `gallop/prefer-layout-components` | Use Grid/Columns, not raw div |
| `gallop/no-arbitrary-colors` | Use color tokens, not arbitrary values |
| `gallop/no-raw-colors` | Use semantic color tokens |
| `gallop/no-cross-zone-imports` | Enforce import boundaries |
| `gallop/no-native-intersection-observer` | Use react-intersection-observer |
| `gallop/no-component-in-blocks` | Exported components belong in /components |
| `gallop/prefer-list-components` | Use List/Li, not raw ul/li |
| `gallop/no-native-date` | Use Luxon, not native Date |
| `gallop/require-canon-setup` | Validate Canon ESLint configuration |
| `gallop/no-classnames-package` | Use clsx, not classnames |
| `gallop/prefer-alias-imports` | Use @/ aliases for imports |
| `gallop/no-inline-svg` | Use Icon component, not inline SVG |

## CLI Commands

### Audit Code

Check code compliance:

```bash
npx gallop audit
npx gallop audit src/ --strict
```

## Pattern Categories

| Category | Description |
|----------|-------------|
| `rendering` | Server/client component boundaries |
| `layout` | Layout hierarchy and spacing |
| `typography` | Text component usage |
| `structure` | File and folder organization |
| `styling` | CSS and Tailwind patterns |
| `components` | Component design patterns |
| `seo` | SEO and metadata patterns |

## Patterns

See the [patterns/](./patterns) directory for full documentation of each pattern.

## Guarantees

See [guarantees.md](./guarantees.md) for version-specific promises.

## License

MIT