Skip to content

feat: add prose-token-leak lint rule - #167

Open
zachshallbetter wants to merge 1 commit into
google-labs-code:mainfrom
zachshallbetter:feat/prose-token-leak
Open

feat: add prose-token-leak lint rule#167
zachshallbetter wants to merge 1 commit into
google-labs-code:mainfrom
zachshallbetter:feat/prose-token-leak

Conversation

@zachshallbetter

Copy link
Copy Markdown
Contributor

Added a new lint rule, prose-token-leak, to flag literal token value duplication in markdown body text to prevent documentation drift (resolves Issue #16).

Background & Motivation

The spec explicity separates machine-readable tokens (YAML frontmatter) and human-readable context (markdown body). When authors duplicate literal values (such as hex colors #ffffff, functional colors rgb(...) / hsl(...), or dimensions 16px) in their prose descriptions or tables, it introduces a dual source of truth. If token values are updated, the prose is frequently forgotten and drifts out of sync.

As discussed in Issue #16, there is community consensus that:

  • The markdown body should describe design intent and perceptual registers, but never contain literal values.
  • Prose should instead reference tokens by name (e.g., {colors.primary}, body-md type scale).
  • A linter warning is the natural guardrail to catch these leaks during development before they are committed.

This rule builds on the pattern established in PR #155 (custom linter checks and omitted-sections validations) by keeping standard linter warnings as the primary gate for format compliance.

Relation to other PRs

Changes

  • Model State:
    • Extend DesignSystemState to include documentSections to expose parsed section content to the rules.
    • Forward input.documentSections in ModelHandler.
  • Linter Rule & Registration:
    • Add prose-token-leak.ts containing the validation logic. Regex patterns flag literal hex colors, functional color notations (rgb, rgba, hsl, hsla), and CSS dimensions.
    • To prevent false-positives, the rule strips out:
      • Markdown links and HTML tags (ignoring anchor targets).
      • HTML comments, headings, fenced code blocks, and inline code backticks.
      • Curly-brace token references (e.g., {colors.primary}).
      • The YAML frontmatter block inside the prelude.
    • Register the rule in rules/index.ts and update rules count assertions in test files.
  • Documentation:
    • Update spec.mdx to define the prose token duplication policy.
    • Regenerate docs/spec.md (see docs/spec.md#L8).

Add a new lint rule, prose-token-leak, to flag literal token value duplication in markdown body text to prevent documentation drift (Issue google-labs-code#16).

* Extend Model State:
  - Add 'documentSections' to DesignSystemState type interface and forward it inside the model compilation handler.

* Rule Implementation & Registration:
  - Add 'prose-token-leak.ts' containing regex evaluation of CSS dimensions and hex values, omitting markdown links, HTML tags/comments, headings, and code blocks.
  - Register the rule in index.ts and update test assertions to expect 12 rule descriptors.

* Documentation:
  - Update spec.mdx to describe the prose token replication policy, and compile docs/spec.md.
@zachshallbetter

Copy link
Copy Markdown
Contributor Author

Also, future extensions might/could include:

  • Font Families: Warn on registered font-family names written as raw text in prose (forcing references like {typography.body.fontFamily}).
  • Font Weights: Flag raw numeric weights (e.g., 600, 700) when close to keywords like weight or fontWeight.
  • Box-Shadows: Match literal CSS box-shadow styles once elevation/shadow tokens are standard in the spec.
  • Custom Token Keys: Warn on raw custom token keys in prose unless formatted as code ticks (e.g., `brand-primary`) or references.
  • Breakpoints: Flag hardcoded pixel/em media query widths (e.g., @media (max-width: 1024px)) once breakpoint tokens are supported.
  • Z-Index Layering: Flag literal z-index declarations in prose.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant