lint-and-fix-design-md

name	lint-and-fix-design-md
description	Lints a DESIGN.md file and uses the format specification and examples to automatically fix any errors or warnings.

Lint and Fix DESIGN.md

This skill runs the design-md linter on a target DESIGN.md file. If any errors or warnings are found, it uses the official specifications and example design-md files to systematically resolve the issues, ensuring the design system conforms to standard rules and best practices.

Reference Material

Use the following files in the repository as specification references and examples to guide your fixes:

• Format Specification: design-md-library/design-md-spec/spec.md
• Example 1 (Atmospheric Glass): design-md-library/design-md-spec/DESIGN-example-1.md
• Example 2: design-md-library/design-md-spec/DESIGN-example-2.md
• Example 3: design-md-library/design-md-spec/DESIGN-example-3.md

Requirements

1. Locate the Input:

   • The user will provide the path to a DESIGN.md file.

2. Run Linter:

   • Run the linting command from the repository root:

     npx @google/design.md lint <path-to-design-md-file>
     

3. Analyze Linter Output:

   • Read the output to identify errors and warnings. Common linter issues include:
     • Incorrect Section Order: Headings must strictly follow this order:
       1. ## Overview (or ## Brand & Style)
       2. ## Colors
       3. ## Typography
       4. ## Layout (or ## Layout & Spacing)
       5. ## Elevation & Depth (or ## Elevation)
       6. ## Shapes
       7. ## Components
       8. ## Do's and Don'ts
     • Malformed Colors: Color hex codes must begin with # (e.g., #1A1C1E).
     • Contrast Violations: Maintain proper contrast ratios (WCAG AA ratio of at least 4.5:1 for body/normal text).
     • Unresolved/Orphaned Tokens: Tokens defined in YAML but never mentioned in the markdown, or references to tokens that do not exist (e.g. {colors.non-existent}).
     • Invalid Token Reference Syntax: References must be enclosed in curly braces with their full object path (e.g., {colors.primary} or {typography.body-md}).
     • Duplicate Section Headings: Reject/remove duplicate headings (e.g. two ## Colors sections).

4. Review Specifications & Examples:

   • Cross-reference the identified issue against the guidelines in design-md-spec/spec.md and the structures in DESIGN-example-1.md, DESIGN-example-2.md, or DESIGN-example-3.md.

5. Apply Fixes:

   • Modify the DESIGN.md file using appropriate file editing tools to fix the errors and warnings. Ensure formatting, typography tokens, shape scales, and component properties adhere strictly to the specification.

6. Verify and Iterate:

   • Re-run the linter command:

     npx @google/design.md lint <path-to-design-md-file>
     

   • If errors or warnings persist, repeat steps 3-5. Continue until the linter passes without errors/warnings.