@cognivo/eslint-plugin

Six ESLint rules that enforce the Cognivo token system inside Lit css template literals. Blocks raw hex, rgba(), transition: all, references to nonexistent tokens, and token fallbacks. CI fails on violations.

Installation

pnpm add -D @cognivo/eslint-plugin

Peer dependency: ESLint 9+ (flat config).

Quick start

Enable the recommended preset in eslint.config.js:

import cognivo from '@cognivo/eslint-plugin';

export default [
  cognivo.configs.recommended,
  // …rest of your config
];

That turns on all six rules. Four run at error level and two at warn — override individually if needed.

Rules

Rule	Level	Catches
`@cognivo/no-raw-hex`	error	Raw hex literals like `#fff` / `#2d2d30` inside css`…`.
`@cognivo/no-raw-rgba`	error	Raw `rgba()` / `rgb()` calls — use surface or overlay tokens.
`@cognivo/no-transition-all`	error	`transition: all` — always specify an explicit property list.
`@cognivo/no-fake-tokens`	error	References to `--cg-*` names that don't exist in `@cognivo/tokens`.
`@cognivo/no-token-fallbacks`	warn	`var(--cg-x, fallback)` — tokens are guaranteed to resolve.
`@cognivo/cg-token-prefix`	warn	Author-defined tokens that don't use the `--cg-` prefix.

Rule examples

no-raw-hex

// ✗ Fail
static styles = css`
  :host { background: #2d2d30; }
`;

// ✓ Pass
static styles = css`
  :host { background: var(--cg-color-surface-cards-background); }
`;

no-raw-rgba

// ✗ Fail
css`:host { background: rgba(255,255,255,0.04); }`

// ✓ Pass
css`:host { background: var(--cg-overlay-white-subtle); }`

no-transition-all

// ✗ Fail — paints every property, including unintended ones
css`.btn { transition: all 150ms ease; }`

// ✓ Pass — explicit, GPU-friendly
css`.btn {
  transition:
    background-color var(--cg-motion-duration-fast) var(--cg-motion-easing-default),
    transform var(--cg-motion-duration-fast) var(--cg-motion-easing-default);
}`

no-fake-tokens

// ✗ Fail — this token does not exist
css`.card { background: var(--cg-brand-primary-background); }`

// ✓ Pass — real tier-2 semantic token
css`.card { background: var(--cg-color-action-primary-background-default); }`

no-token-fallbacks

// ✗ Fail — tokens always resolve; fallback masks drift
css`.card { color: var(--cg-color-text-primary, #fff); }`

// ✓ Pass
css`.card { color: var(--cg-color-text-primary); }`

cg-token-prefix

// ✗ Fail — non-standard prefix
css`:host { --my-padding: 16px; }`

// ✓ Pass — follow the --cg- convention
css`:host { --cg-component-mything-padding: 16px; }`

Caveats

Scope is Lit css tagged templates. The rules only scan content inside css`…`. Plain .css / .scss files are out of scope.
Requires the flat config. ESLint 9+ only; the legacy .eslintrc format is not supported.
Token list is bundled. no-fake-tokens uses a snapshot of @cognivo/tokens at build time — bump the plugin after adding new tokens.
Override any rule. Spread cognivo.configs.recommended and set an individual rule to off / warn if your codebase needs a different bar.