Contract Spec#

TasteKernel contract files are YAML-first and validated with the @tastekernel/contract-schema package.

Default file name:

• tastekernel.contract.yml

Validate at any time:

tastekernel validate

Top-level structure#

Required top-level sections:

• version
• project
• sources
• tokens
• components
• motion
• copy
• rules
• ignore
• waivers

Project#

project controls scan targets and framework assumptions.

• name: display name for reports and exports
• framework: nextjs or react
• styling: tailwind or css
• componentDirs: component discovery roots
• codeGlobs: source globs for TS/JS/TSX/JSX
• cssGlobs: CSS globs for PostCSS parsing

Sources#

sources declares token origin mode.

• tailwindMode: v3-config | v4-theme | manual
• tailwindFiles: source files inspected
• configFiles: supporting config files
• detectedFiles: best-effort detection traces

Tokens#

Token groups:

• colors
• spacing
• radius
• shadows
• typography

Each token entry supports:

• id
• value
• aliases
• preferredClassNames
• cssVar
• description

Components#

components.allowed defines approved usage:

• importSource
• bannedHtmlSubstitutes
• allowedVariants
• allowedSizes
• deprecated
• replacement

components.deprecated maps legacy component names to replacements.

Motion#

Motion constraints:

• maxDurationMs
• allowedDurationsMs
• allowedEasings
• bannedEasings
• allowedAnimationNames
• disallowInlineAnimationValues

Copy#

Copy constraints:

• toneKeywords
• bannedPhrases
• preferredReplacements
• checkedProps
• checkTextNodes
• allowlistPatterns

Rules and severity#

Rules are keyed by rule id. Each entry can define:

• severity: off | info | warn | error | ignore
• ignoreGlobs
• folderGlobs

Example:

rules:
  token/no-raw-color:
    severity: error
  component/no-inline-style:
    severity: warn

Ignore and waivers#

Ignore levels:

• .tastekernelignore file
• contract-level ignore.globs
• contract-level ignore.perRule
• inline comments (rule-specific, with justification)

Waivers:

• file
• ruleId
• reason
• optional expiresAt

Minimal valid example#

version: 1
project:
  name: Example
  framework: nextjs
  styling: tailwind
  componentDirs: [src/components/ui]
  codeGlobs: [src/**/*.{ts,tsx,js,jsx}]
  cssGlobs: [src/**/*.css]
sources:
  tailwindMode: manual
  tailwindFiles: []
  configFiles: []
  detectedFiles: []
tokens:
  colors: []
  spacing: []
  radius: []
  shadows: []
  typography: []
components:
  allowed: {}
  deprecated: {}
motion:
  maxDurationMs: 250
  allowedDurationsMs: [75, 100, 150, 200, 250]
  allowedEasings: [ease, ease-in, ease-out, ease-in-out]
  bannedEasings: []
  allowedAnimationNames: [spin, pulse]
  disallowInlineAnimationValues: true
copy:
  toneKeywords: [calm, direct, friendly]
  bannedPhrases: []
  preferredReplacements: {}
  checkedProps: [title, placeholder, aria-label]
  checkTextNodes: true
  allowlistPatterns: []
rules: {}
ignore:
  globs: [node_modules/**, .next/**, dist/**, build/**]
  perRule: {}
waivers: []