DESIGN.md Design System Validator

Validate, diff, and export DESIGN.md files to ensure consistent design tokens, WCAG compliance, and design system integrity across projects.

Security Scan

The skill's declared purpose (linting, diffing, exporting DESIGN.md) matches the instructions and required actions; it is an instruction-only wrapper around the @google/design.md CLI and requests nothing disproportionate.

Purpose & Capability

Name/description describe DESIGN.md validation and token exports; SKILL.md exclusively documents using the @google/design.md CLI to lint, diff, view spec, and export—these requirements are expected and proportional to the stated purpose.

Instruction Scope

Runtime instructions tell the agent to read project DESIGN.md files and run npx/npm CLI commands against them. The instructions reference only project paths and the DESIGN.md tooling; they do not ask the agent to collect unrelated system files, environment variables, or send data to unexpected endpoints.

Install Mechanism

The skill is instruction-only (no install spec), but it directs use of npm/npx to fetch @google/design.md from the npm registry. This is normal for CLI tooling, but npx/npm will fetch and run remote code at runtime—users should be aware and may prefer a pinned dependency or auditing the package before global installation.

Credentials

No environment variables, credentials, or config paths are requested or referenced. The actions described (lint, diff, export) do not require secrets or unrelated credentials.

Persistence & Privilege

always is false and the skill does not request persistent system privileges or to modify other skills. Autonomous invocation is allowed (platform default) but not combined with other risky permissions.

Assessment

This skill appears coherent and limited to using the @google/design.md CLI to validate and export DESIGN.md files. Before installing or running it: 1) verify the npm package and GitHub repo (ownership, recent releases, maintainer reputation); 2) prefer adding the package as a project devDependency (pin a specific version) instead of running npm install -g or npx from an unpinned name; 3) inspect package contents (or run in a sandbox) to check for malicious postinstall scripts or unexpected network calls; and 4) if you operate on sensitive repositories, run the tooling on a copy or in CI with least privilege to avoid accidental leakage. These are standard precautions for any tool fetched from npm.

DESIGN.md Skill — Design System Validation & Management

Validate, diff, and export DESIGN.md files for consistent design systems across projects.

Overview

DESIGN.md is a format specification (by Google Labs) for describing a visual identity to coding agents. It combines:

• YAML front matter — Machine-readable design tokens
• Markdown body — Human-readable design rationale

Installation

The skill uses @google/design.md npm package:

npm install -g @google/design.md

Commands

1. Lint — Validate DESIGN.md

npx @google/design.md lint DESIGN.md

Checks:

• Token references resolve (broken-ref → error)
• WCAG contrast ratios (contrast-ratio → warning)
• Missing primary colors (missing-primary → warning)
• Section order (section-order → warning)

Output: JSON with findings

2. Diff — Compare Versions

npx @google/design.md diff DESIGN.md DESIGN-v2.md

Detects:

• Added/removed/modified tokens
• Regressions between versions

3. Export — Convert to Other Formats

npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

4. Spec — View Format Specification

npx @google/design.md spec
npx @google/design.md spec --rules

Quick Start

1. Read existing DESIGN.md in project
2. Run lint to validate structure
3. Run export to generate Tailwind config
4. Update components based on findings

Usage in Coding

When working on UI components:

# Before editing a component, lint current state
npx @google/design.md lint design-md/markiosi/DESIGN.md

# After changes, diff to check for regressions
npx @google/design.md diff design-md/markiosi/DESIGN.md design-md/markiosi/DESIGN.md.new

# Export updated tokens
npx @google/design.md export --format tailwind design-md/markiosi/DESIGN.md > tailwind.tokens.json

Workflow Integration

1. Before making UI changes:

   • Read project's DESIGN.md
   • Run lint to understand current design state

2. After UI changes:

   • Update DESIGN.md tokens accordingly
   • Run diff to detect regressions
   • Run lint to validate WCAG compliance

3. For new components:

   • Check DESIGN.md for existing component patterns
   • Define new components in DESIGN.md first
   • Use token references ({colors.primary}) over hardcoded values

Resources

• Spec: https://github.com/google-labs-code/design.md
• Stitch Tool: https://stitch.withgoogle.com/
• Design Tokens Format: https://www.designtokens.org/