How the awesome-design-md Repository is Organized by Industry and Use Case

The VoltAgent/awesome-design-md repository structures its collection of DESIGN.md files into ten distinct industry categories defined in the top-level README.md, with each design system stored under the design-md/ directory.

The VoltAgent/awesome-design-md repository serves as a curated catalogue of DESIGN.md files representing the visual design systems of real-world products. Understanding how this awesome-design-md repository is organized by industry and use case helps developers quickly locate relevant design systems for their specific domain, whether building AI platforms, fintech applications, or automotive interfaces.

Industry Categories Defined in README.md

The repository’s top-level README.md acts as the primary index, grouping entries by industry and typical use case starting at line 88. As implemented in VoltAgent/awesome-design-md, the taxonomy includes ten major classifications:

Category	Use Case Focus	Notable Examples
AI & LLM Platforms	AI assistants and model providers	Claude, Cohere, Ollama
Developer Tools & IDEs	Code editors and developer-focused SaaS	Cursor, Expo, Superhuman, Vercel, Warp
Backend, Database & DevOps	Infrastructure and analytics products	ClickHouse, HashiCorp, MongoDB, PostHog, Supabase
Productivity & SaaS	Scheduling and project management	Cal.com, Linear, Notion, Zapier
Design & Creative Tools	Visual design platforms	Figma, Framer, Miro, Webflow
Fintech & Crypto	Financial services and cryptocurrency	Binance, Coinbase, Stripe, Revolut
E-commerce & Retail	Marketplaces and retail brands	Airbnb, Shopify, Nike
Media & Consumer Tech	Consumer hardware and media	Apple, Spotify, Uber, NVIDIA
Automotive	Car manufacturer branding	BMW, Tesla, Ferrari, Lamborghini
Retro Web · DESIGN.md Nostalgia	Historic web designs	Dell 1996, Nintendo 2001

Each category header in the README uses H3 markdown headings (prefixed with ###) followed by the industry name, often including descriptive subtitles separated by the middle dot (·) character. This structure allows users browsing the repository to quickly surface design systems relevant to their project's domain.

Directory Structure Under design-md

Individual design systems reside in subdirectories under design-md/, following a consistent three-file pattern that separates metadata from implementation:

• README.md: Contains a brief description of the source product and external links.
• DESIGN.md: The actual design system specification consumed by AI agents.
• Preview HTML files: Visual references rendering the design guidelines.

For example, the Apple design system lives at design-md/apple/DESIGN.md, accompanied by design-md/apple/README.md describing the source material. This structure applies uniformly across all entries—from design-md/claude/ for AI platforms to design-md/stripe/ for fintech applications.

Programmatically Accessing Industry Categories

Developers can parse the categorical organization programmatically using Node.js. The following script reads the top-level README.md to extract category headings via regex, then scans the design-md/ folder to map directories to their respective industries:

// list-designs.js
import { readdirSync, readFileSync } from 'fs';
import path from 'path';

// Load the README and extract the category headings
const readme = readFileSync('README.md', 'utf8');
const categoryRegex = /###\s+([^·\n]+)(?:\s*·\s*[^·\n]*)?/g;
const categories = [...readme.matchAll(categoryRegex)].map(m => m[1].trim());

// Scan design-md sub-folders
const designRoot = path.resolve('design-md');
const dirs = readdirSync(designRoot, { withFileTypes: true })
               .filter(d => d.isDirectory())
               .map(d => d.name);

console.log('Design systems grouped by industry/use-case:');
for (const cat of categories) {
  console.log(`\n${cat}:`);
  // Find entries whose README contains the category name (simple heuristic)
  const matches = dirs.filter(d => {
    const rd = readFileSync(path.join(designRoot, d, 'README.md'), 'utf8');
    return rd.toLowerCase().includes(cat.toLowerCase());
  });
  for (const m of matches) console.log(`  - ${m}`);
}

Running node list-designs.js outputs design systems grouped by their industry classification, mirroring the manual organization in the README. This approach leverages the consistent structure defined in the repository’s source code to enable dynamic menu generation in CLI tools or documentation generators.

Summary

• The awesome-design-md repository organizes hundreds of DESIGN.md files into ten industry categories defined in the top-level README.md (lines 88-186).
• Categories range from AI & LLM Platforms to Automotive, with each entry linking to a subdirectory under design-md/.
• Each design system resides in its own folder containing a README.md (metadata) and DESIGN.md (specification), plus preview HTML files.
• The repository structure supports programmatic parsing, allowing developers to extract industry classifications using regex patterns against the README headers.

Frequently Asked Questions

Where are the actual DESIGN.md files located in the awesome-design-md repository?

The actual DESIGN.md files reside in subdirectories under design-md/. For example, Apple's design system is located at design-md/apple/DESIGN.md, while Stripe's lives at design-md/stripe/DESIGN.md. Each subdirectory also contains a README.md describing the source product and linking to external resources.

How does the README.md categorize the different design systems?

The README.md uses H3 headings (prefixed with ###) to group entries by industry and use case, starting at line 88 with "AI & LLM Platforms" and continuing through "Retro Web · DESIGN.md Nostalgia" at line 186. This taxonomy allows users to browse by domain such as fintech, developer tools, or e-commerce without searching individual file names.

Can I contribute a new design system to a specific industry category?

Yes. According to CONTRIBUTING.md, you can add new design systems by creating a subdirectory under design-md/ with your DESIGN.md file and a descriptive README.md. The maintainers categorize new submissions appropriately in the top-level README.md based on the industry or use case your design system represents, following the existing organizational pattern.

What is the difference between the README.md in the root and those in the design-md subdirectories?

The root README.md serves as the master index that catalogs all design systems by industry category and provides links to each subdirectory. In contrast, design-md/*/README.md files contain specific descriptions of individual products (like Apple or HashiCorp), explaining the source material and linking to the actual DESIGN.md file for that particular design system.

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