# How to Contribute a DESIGN.md File to the awesome-design-md Repository > Learn how to improve existing DESIGN.md files in the awesome-design-md repository. Discover the contribution guidelines and best practices for enhancing design specifications effectively. - Repository: [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) - Tags: how-to-guide - Published: 2026-07-10 --- **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`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/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//`, 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: ```bash git clone https://github.com//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//DESIGN.md` and make your corrections. For example, if updating Zapier's design tokens, you would edit [`design-md/zapier/DESIGN.md`](https://github.com/VoltAgent/awesome-design-md/blob/main/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//preview.html` and/or `design-md//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: ```bash git commit -am "Fix token colors for " 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`](https://github.com/VoltAgent/awesome-design-md/blob/main/CONTRIBUTING.md)**: Contains the full contribution policy including the restriction on new DESIGN.md submissions. - **`design-md//DESIGN.md`**: The primary design specification file that contributors edit. - **`design-md//README.md`**: Provides contextual information about each brand's design system. - **`design-md//preview.html`** and **[`preview-dark.html`](https://github.com/VoltAgent/awesome-design-md/blob/main/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//` 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`](https://github.com/VoltAgent/awesome-design-md/blob/main/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`](https://github.com/VoltAgent/awesome-design-md/blob/main/preview.html) and/or [`preview-dark.html`](https://github.com/VoltAgent/awesome-design-md/blob/main/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//`. ### 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 "`. 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.