Cicd Integration

validate-token-names.js

/**
 * Validates token names against the configured naming convention.
 * Exits with code 1 if violations are found.
 *
 * Generated by Design System Ops — cicd-integration
 */

const fs = require('fs');
const path = require('path');

// Configuration — adjust these to match your conventions
// A segment is lowercase letters and digits, optionally hyphenated:
// spacing.4, font-size.base, color.blue.500, color.action.primary-hover,
// button.background.hover all pass. 2–5 segments.
const SEGMENT = '[a-z0-9]+(?:-[a-z0-9]+)*';
const TOKEN_NAME = new RegExp(`^${SEGMENT}(?:\\.${SEGMENT}){1,4}$`);

// Tier comes from where a token is defined (file or set), not from how many
// segments its name has — spacing.4 and button.background.default can't be
// told apart by shape alone.
const TIER_BY_PATH = {
  primitive: 'primitives/',
  semantic: 'semantic/',
  component: 'component/',
};

// Token file path — adjust to your project
const TOKEN_DIR = process.env.TOKEN_DIR || 'packages/tokens/src';

// [Full implementation: recursively read token files, assign each token
//  a tier from TIER_BY_PATH, validate its name against TOKEN_NAME and any
//  tier-specific rules, collect violations, read the threshold for
//  `token-naming` from .ds-ops/quality-gates.yml, output violations, and
//  exit 1 only if the count exceeds the threshold and block_merge is true]

The block above is the header and configuration only; the generated file contains the implementation its comment describes. Provide complete, working implementations for each script. Include:

• Clear comments explaining what the script checks
• Configurable paths and patterns at the top of each file
• Thresholds read from .ds-ops/quality-gates.yml (Step 4) via a shared helper, not hardcoded
• Exit codes: 1 only when a gate with block_merge: true is exceeded; otherwise 0, printing warnings (on GitHub, as ::warning:: lines so they show on the PR)
• Human-readable output: which files, which violations, what to fix
• Provenance comment: "Generated by Design System Ops — cicd-integration"

Scripts to generate

1. validate-token-names.js — Regex-based token name validation (Style Dictionary doesn't validate names; Terrazzo's lint rules can, if the team is on Terrazzo, in which case skip this script)
2. find-orphaned-tokens.js — Cross-reference token definitions with component usage
3. verify-exports.js — Compare directory listing with barrel file exports
4. check-docs-exist.js — Verify documentation files exist for each component
5. check-stories-exist.js — Verify Storybook story files exist for each component
6. read-gates.js — Shared helper that loads .ds-ops/quality-gates.yml and returns the threshold and block_merge flag for a gate

DTCG validation and the hardcoded-value check are not scripts: they run Terrazzo or Style Dictionary, and Stylelint or ESLint, with the config the team has (or governance-encoder writes). Don't reimplement a linter in scripts/ds-checks/.

Prerequisites the pipeline assumes

Two steps call tools the scripts above don't create. Generate them, or list them as prerequisites the team must add before the pipeline goes green:

• Stylelint config with stylelint-declaration-strict-value on the token-backed properties (and eslint-plugin-tailwindcss for Tailwind). Run governance-encoder to write it from the team's rules, or generate a minimal one here and say it's a starting point.
• test:a11y script in package.json — for example "test:a11y": "vitest run --project a11y" with jest-axe/vitest-axe tests, or "test:a11y": "test-storybook" with the Storybook test-runner and axe. Generate one example test per component type found.
• size-limit config — a .size-limit.json listing each entry point with a limit, plus size-limit and its preset (e.g. @size-limit/preset-small-lib) as dev dependencies.

Step 4: Generate a quality gate configuration

Produce a quality gate definition that the pipeline enforces on pull requests:

The scripts/ds-checks/ scripts read this file through read-gates.js. Checks run by other tools (Style Dictionary, axe, size-limit, Chromatic) are gated by their own exit codes and config — set their thresholds there, and say so in PIPELINE.md.

# .ds-ops/quality-gates.yml
# Quality gates for design system pull requests, read by scripts/ds-checks/
# Adjust thresholds based on your system's maturity

gates:
  token-naming:
    threshold: 0          # Zero tolerance for naming violations
    block_merge: true
    message: "Token naming violations must be fixed before merge"

  orphaned-tokens:
    threshold: 5          # Allow some orphans during migration periods
    block_merge: false    # Warn only: tokens consumed outside this repo look orphaned
    message: "Possibly orphaned tokens — check external consumers before removing"

  exports:
    threshold: 0
    block_merge: true
    message: "Every component directory must be exported from the package entry point"

  docs-and-stories:
    threshold: 0
    block_merge: false
    message: "Components without docs or stories detected"

Step 5: Generate documentation

Produce a PIPELINE.md file that explains:

1. What each check does — in plain language a product manager would understand
2. How to add a new check — step-by-step for an engineer
3. How to adjust thresholds — where the configuration lives and what each threshold means
4. What to do when a check fails — troubleshooting guide for each check type
5. How this relates to Design System Ops audits — which audit findings each check automates

Adaptation by platform

For teams using Figma MCP

Add a step that auto-pulls Figma variable values and compares them against token file definitions. This catches design-code drift at the CI level.

For teams using Style Dictionary or Terrazzo

Style Dictionary's build catches broken and circular references and, with usesDtcg, bad value shapes; it does not validate names, so validate-token-names.js stays. Terrazzo's lint covers DTCG validation and has configurable lint rules that can replace the naming script. Use the tool the repo has; don't add a second token toolchain for CI.

For teams using Storybook

Integrate the visual regression step with Storybook's built-in visual testing or Chromatic. Generate test-runner configuration for accessibility checks within stories.

For monorepo projects

Scope jobs by changed paths inside the pipeline (the changes job above), not with workflow-level paths: filters, so required checks never sit pending. Token changes run token checks; component changes run component checks. Use job dependencies so that token validation runs before component validation (since components depend on tokens).

Quality checks

• Pipeline configuration is valid YAML that passes the platform's schema validation
• All referenced scripts exist and are executable, and every tool a step calls (test:a11y, size-limit) is either generated or listed as a prerequisite
• Actions are pinned to current majors and Node is 22 or 24
• Gate thresholds come from .ds-ops/quality-gates.yml, and the user is told to enable branch protection for blocking checks
• Scripts have clear error messages that explain what went wrong and how to fix it
• Quality gate thresholds are reasonable defaults (not so strict they block everything, not so loose they catch nothing)
• Documentation explains every check in language a non-engineer can understand
• Provenance marker present in all generated files
• Pipeline configuration respects monorepo structure if applicable
• No secrets or credentials are hardcoded — all sensitive values use environment variables or secrets management