# The Design Tokens contract, with every rule from its checklist.
# The page explains why each one exists: https://opencomponents.dev/raw/docs/foundations/design-tokens.md

convention: token-paths
standard: https://opencomponents.dev/docs/foundations/design-tokens
format: "--{group}--{name}" # "--{group}--{part or state}--{name}" for a part or state, even with one token
separators: { group: "--", word: "-" }
pattern: "^--[a-z0-9]+(-[a-z0-9]+)*(--[a-z0-9]+(-[a-z0-9]+)*)+$"
paths:
  css: "--color--primary"
  dtcg: "{color.primary}"
  figma: color/primary
  styleframe: color.primary
theme:
  colors: [primary, secondary, neutral, success, info, warning, error]
  tokens: ["--color--{color}", "--color--{color}-contrast", "--color--{color}-text", "--color--focus"]
components: "--{component}--{name}, or --{component}--{part}--{name}, set on the component's root"
overrides: "A class of yours, outside a layer. Components style themselves in @layer components, in Tailwind's layer order."
rules:
  - id: tokens/token-paths
    level: must
    requirement: "Variables are named as token paths, in lowercase, with `-` between words and `--` between groups"
    check: "Stylelint"
  - id: tokens/semantic-names
    level: must
    requirement: "Theme and component tokens say what they're for, rather than what they look like"
    check: "Review"
  - id: tokens/theme-only
    level: must
    requirement: "Components read theme tokens, and never palette tokens or raw colours"
    check: "Review"
  - id: tokens/shared-theme
    level: must
    requirement: "Components read the shared theme tokens, so a single theme styles them all"
    check: "Review"
  - id: tokens/component-scope
    level: must
    requirement: "A component's own variables start with its name, like `--button--`, and are set on its root"
    check: "Review"
  - id: tokens/class-overrides
    level: should
    requirement: "Components put their styles in the `components` cascade layer, so a class can set their variables without an inline style"
    check: "Review"
  - id: tokens/contrast
    level: must
    requirement: "`-contrast` has 4.5:1 against its colour, `-text` 4.5:1 against the page and `--color--focus` 3:1, in light and dark mode"
    check: "Contrast checker"
  - id: tokens/groups
    level: should
    requirement: "A part or state always gets its own group, like `--button--icon--size`, while a variation or a CSS property stays in one name"
    check: "Review"