Skip to content

CLAUDE.md

Latest commit

 

History

History
61 lines (43 loc) · 3.39 KB

CLAUDE.md

File metadata and controls

61 lines (43 loc) · 3.39 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

A curated collection of DESIGN.md files extracted from real developer-focused websites. DESIGN.md is a Google Stitch concept: a plain markdown design system document that AI agents read to generate consistent UI. No build system, no tests, no package manager — this is a pure content repository.

Directory Structure

Each site entry lives under design-md/<site-name>/ and must contain exactly four files:

File Purpose
DESIGN.md The design system (9 required sections)
preview.html Self-contained visual catalog, light mode
preview-dark.html Self-contained visual catalog, dark mode
README.md Short description + preview screenshots

DESIGN.md Format

Every DESIGN.md must include all 9 sections in order:

  1. Visual Theme & Atmosphere — Evocative mood description, never generic ("clean and modern" is a failure). Explain why the design works, not just what it looks like.
  2. Color Palette & Roles — Every color: Semantic Name (#hex) + functional role. Organized by group (Primary, Secondary, Surface, Neutrals, Semantic).
  3. Typography Rules — Full hierarchy table with font family, size, weight, line-height, letter-spacing. Must cover headlines, body, code/mono, and small labels.
  4. Component Stylings — Buttons, cards, inputs, navigation. Must include hover/focus states and transition timing.
  5. Layout Principles — Spacing scale, grid system, whitespace philosophy.
  6. Depth & Elevation — Shadow system and surface hierarchy.
  7. Do's and Don'ts — Design guardrails and anti-patterns specific to this site's language.
  8. Responsive Behavior — Breakpoints, touch targets, mobile collapsing strategy.
  9. Agent Prompt Guide — Quick color reference + ready-to-use prompts for AI agents.

Preview HTML Standards

  • Self-contained: Inline CSS only. No external dependencies except Google Fonts.
  • Must display: color swatches, typography scale, button variants, card examples, form elements, spacing scale, border radius, elevation levels.
  • No logo icons, emoji icons, or Do's/Don'ts section in HTML.
  • Must render reasonably on mobile.

Adding a New Site

  1. Create design-md/<site-name>/ (use the site's domain name or common short name, lowercase).
  2. Add all four files (DESIGN.md, preview.html, preview-dark.html, README.md).
  3. Add the site to the correct category in README.md — entries are alphabetical within each category.
  4. Update the badge count in README.md: ![DESIGN.md Count](https://img.shields.io/badge/DESIGN.md%20count-XX-10b981...).

README.md Entry Format

- [**Site Name**](https://github.com/VoltAgent/awesome-design-md/tree/main/design-md/<dirname>/) - One-line description. Key aesthetic trait

Description should be factual and specific: name the accent color, the dominant mood, or the layout archetype. Avoid marketing language.

Quality Bar

  • Hex values must match the live site (inspect computed CSS, not design files).
  • Atmosphere descriptions must be specific to this brand — if the sentence could describe any other site, rewrite it.
  • Typography tables must include real values extracted from the site, not approximations.
  • Component states (hover, focus, active, disabled) must all be documented.