How to Contribute a DESIGN.md File to the awesome-design-md Repository

The awesome-design-md repository does not accept pull requests for new DESIGN.md files; contributions are limited to improving existing design specifications.

The awesome-design-md project by VoltAgent maintains a curated collection of DESIGN.md files that document the visual design systems of popular websites. While the repository welcomes community contributions, the maintainers have established strict guidelines regarding how to contribute a DESIGN.md file to the awesome-design-md repository. According to the source code in CONTRIBUTING.md, you cannot submit new brand designs, but you can improve existing ones by correcting hex values, adding missing tokens, or updating preview HTML files.

Understanding the Contribution Policy

Before submitting any changes, review the CONTRIBUTING.md file located in the repository root. The maintainers explicitly state that they do not accept new DESIGN.md pull requests. This policy ensures quality control and consistent curation of the visual language collection. The only way to "add" a new design is to request that the repository owners first create a directory for the brand; once that directory exists under design-md/<brand>/, you can then contribute improvements using the standard workflow.

Step-by-Step Contribution Workflow

To contribute improvements to an existing DESIGN.md file, follow this issue-first workflow:

1. Open an Issue First

Always start by creating an issue at https://github.com/VoltAgent/awesome-design-md/issues/new describing the specific changes you want to make. Whether you are fixing color values, correcting typography errors, or adding missing design tokens, maintainer feedback is required before you begin editing.

2. Fork the Repository

Create a personal fork of the repository by clicking the "Fork" button on the GitHub interface. Then clone your fork locally and create a feature branch:

git clone https://github.com/<your-username>/awesome-design-md.git
cd awesome-design-md
git checkout -b fix-brand-tokens

3. Edit the Target DESIGN.md

Locate the file under design-md/<brand>/DESIGN.md and make your corrections. For example, if updating Zapier's design tokens, you would edit design-md/zapier/DESIGN.md. Ensure your changes align with the actual brand guidelines and reference specific token names correctly.

4. Update Preview Files

If your modifications affect visual tokens such as colors, typography, or spacing, you must also update the corresponding preview HTML files. Edit design-md/<brand>/preview.html and/or design-md/<brand>/preview-dark.html to reflect the new values. These files render the token palette and must stay synchronized with the DESIGN.md content.

5. Create a Pull Request

Commit your changes with a descriptive message, push to your fork, and open a Pull Request via the GitHub UI:

git commit -am "Fix token colors for <brand>"
git push origin fix-brand-tokens

In your PR description, reference the issue you opened earlier and provide a clear before/after rationale for the changes.

Repository Structure and Key Files

Understanding the file organization helps ensure you edit the correct components:

• CONTRIBUTING.md: Contains the full contribution policy including the restriction on new DESIGN.md submissions.
• design-md/<brand>/DESIGN.md: The primary design specification file that contributors edit.
• design-md/<brand>/README.md: Provides contextual information about each brand's design system.
• design-md/<brand>/preview.html and preview-dark.html: HTML previews that render the token palette; must be updated when design tokens change.

Summary

• New DESIGN.md files are not accepted; only improvements to existing files are allowed.
• Always open an issue first to discuss changes with maintainers before editing.
• Update preview HTML files whenever you modify visual tokens in the DESIGN.md.
• Submit PRs with clear rationale linking back to the original issue.
• Follow the directory structure under design-md/<brand>/ for all edits.

Frequently Asked Questions

Can I submit a new DESIGN.md file for a brand not yet in the repository?

No. According to the CONTRIBUTING.md policy in the VoltAgent/awesome-design-md repository, the maintainers do not accept pull requests for new DESIGN.md files. New brands must be added by the repository owners first. Once a directory exists for a brand, you can contribute improvements to its existing files.

Do I need to update the preview HTML files when editing DESIGN.md?

Yes. If your changes affect visual tokens such as hex values, color palettes, or typography, you must update preview.html and/or preview-dark.html in the same directory. These files render the design tokens and must remain synchronized with the DESIGN.md specifications.

What should I include in my contribution issue?

Describe the specific inaccuracies or missing information you want to address, such as incorrect color values, outdated typography specifications, or missing design tokens. Include links to official brand guidelines if possible, and clearly state which files you intend to modify under design-md/<brand>/.

How do I format my commit messages and pull requests?

Use clear, descriptive commit messages that specify the brand and type of fix, such as "Fix token colors for <brand>". In your pull request, reference the issue number you opened initially and provide a detailed before/after rationale explaining why the changes improve the design documentation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}