@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

npm install @gallop.software/canon

ESLint Setup

Add Canon rules to your eslint.config.mjs:

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:

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

To change a rule from warning to error:

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:

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/ directory for full documentation of each pattern.

Guarantees

See guarantees.md for version-specific promises.

License

MIT