Maintenance Prompt for Design System

Improved Prompt:

You are a dedicated design system auditor tasked with conducting a comprehensive synchronization audit between the CLAUDE.md documentation and the live codebase.

Your primary objective is to identify and catalog any discrepancies, ensuring our design system remains a trustworthy source of truth that accurately reflects the current state of our components and tokens.

Audit Parameters

Documentation Reference

• Primary Source: The CLAUDE.md documentation file that defines our current design system's official specifications.
• Version: ${version_of_documentation}
• Last Updated: ${last_updated_date}

Codebase Reference

• Scope: The entire production codebase, including all components, tokens, and utility functions.
• Version: ${version_of_codebase}
• Path: ${path_to_codebase}

Audit Criteria

Token Audits

1. Token Inventory Comparison

   • Thoroughly compare the token definitions in CLAUDE.md against the actual codebase.
   • Identify any tokens in the codebase that are not documented (New Undocumented Tokens).
   • Locate any tokens documented as deprecated that are still actively used (Deprecated Tokens).

2. Token Usage Analysis

   • Identify any color, spacing, font size, or weight values used in the code that are not defined in the documentation.
   • Categorize these undocumented values based on their severity (critical, breaking, cosmetic).

Component Audits

1. Component Library Sync

   • Cross-reference the components listed in the CLAUDE.md component library with the actual codebase.
   • Identify any components that have been created or modified since the last CLAUDE.md update (New Undocumented Components).
   • Check for any components that have been removed or renamed in the codebase but not updated in the documentation.

2. Component Prop Analysis

   • Analyze the props of each component in both the documentation and the codebase.
   • Detect any props that have been added, removed, or renamed between the two sources (Modified Props).
   • Identify any new variants or visual changes that are not documented but are in use in the code.

Reference Integrity Check

1. Broken References Audit
   • Verify that all the tokens, components, and file paths referenced in CLAUDE.md are still valid and exist in the current codebase.
   • Identify any broken references, outdated import paths, or file paths that have changed (Broken References).

Convention Compliance Audit

1. Style Guide Violations
   • Review the codebase for any instances that violate the design system's style guide as defined in CLAUDE.md.
   • Count the occurrences of each violation type (inline colors, missing focus states, etc.).
   • Prioritize the violations based on their severity (breaking → inconsistent → cosmetic).

Report Generation

Summary Section

• Present a summary table containing the following statistics:
  • New undocumented tokens: Count and examples
  • Deprecated tokens in use: Count, names, and usage frequencies
  • New undocumented components: Count and names
  • Modified components: Count, names, and brief descriptions of changes
  • Broken references: Count, types, and examples
  • Style guide violations: Count per violation type and total

Action Items

• Prioritize the identified issues based on the following criteria (highest to lowest priority):
  • Critical: Breaking changes, undocumented tokens in core components
  • High: Deprecated tokens in active use, missing focus states
  • Medium: Inconsistent naming, outdated references
  • Low: Cosmetic violations, minor prop changes

Documentation Update

• Prepare a clean, formatted markdown output containing only the sections of CLAUDE.md that need to be updated based on your findings.
• Ensure the output is ready for easy copy-pasting into the CLAUDE.md file.

Please generate a comprehensive, easy-to-understand report that allows our engineering and design teams to swiftly address these discrepancies and maintain a robust, accurate design system.