Skip to content

Using with awesome design md

Jump to bottom
snoo edited this page Apr 7, 2026 · 1 revision

Using with awesome-design-md

awesome-design-md (23K+ stars) is a popular collection of DESIGN.md files that give AI coding tools context about design systems, frameworks, and coding conventions. StyleSeed is fully compatible and designed to complement it.

How They Relate

awesome-design-md StyleSeed
Focus General coding/design context for AI Complete design system seed with components
Format Single DESIGN.md file DESIGN-LANGUAGE.md + CLAUDE.md + components + tokens
Scope Guidelines and conventions Guidelines + runnable code + slash commands
Purpose Tell AI how to write code Tell AI how to write code AND provide the components to use

StyleSeed extends the awesome-design-md pattern by adding actual components, tokens, and skills on top of the markdown guidelines.

Setup: Using Both Together

Option 1: StyleSeed as Your Design System, awesome-design-md for Everything Else

project-root/
  DESIGN.md                    # From awesome-design-md (general conventions)
  seed/
    DESIGN-LANGUAGE.md         # StyleSeed visual rules (69 rules)
    CLAUDE.md                  # StyleSeed AI guide
    components/                # Actual components
    css/                       # Theme and tokens
    tokens/                    # JSON tokens

In this setup:

  • DESIGN.md handles general code style, architecture conventions, API patterns
  • DESIGN-LANGUAGE.md handles all visual/UI rules
  • CLAUDE.md tells Claude Code how to use the components

Option 2: Merge Into a Single DESIGN.md

If you prefer one file, append StyleSeed's rules to your existing DESIGN.md:

# DESIGN.md

## Code Conventions
... (your existing awesome-design-md content) ...

## UI Design System
... (paste from DESIGN-LANGUAGE.md) ...

## Component Usage
... (paste from CLAUDE.md) ...

Option 3: Reference StyleSeed from DESIGN.md

# DESIGN.md

## UI Design System
See `seed/DESIGN-LANGUAGE.md` for all 69 visual design rules.
See `seed/CLAUDE.md` for component usage guide.

Key rules:
- Single accent color (#721FE5), active/selected states only
- 5-level grayscale, no pure black
- Big number + small unit (2:1 ratio)
- 4 section types (Hero, Grid, Carousel, Full Card)
- All content inside cards

Which awesome-design-md Files Pair Well

Recommended Combinations

awesome-design-md file What it adds to StyleSeed
react.md React conventions, hooks patterns, state management
tailwindcss.md Tailwind best practices (StyleSeed already uses Tailwind v4)
typescript.md TS conventions, type patterns
accessibility.md WCAG guidelines (StyleSeed covers basics, this adds depth)
testing.md Component testing patterns

Potential Conflicts to Watch

awesome-design-md file Conflict Resolution
Files with custom color systems May contradict StyleSeed's 5-level grayscale StyleSeed colors take priority for UI
Files recommending MUI/Chakra StyleSeed uses Radix UI Use StyleSeed's component library
Files with different spacing scales May conflict with 6px-multiple spacing StyleSeed spacing takes priority

Writing Your Own DESIGN.md That References StyleSeed

If you want to create a custom DESIGN.md for your project that incorporates StyleSeed:

# Project DESIGN.md

## Design System
This project uses StyleSeed (toss seed) for UI components and visual design.

### Key References
- Visual rules: `seed/DESIGN-LANGUAGE.md` (69 rules)
- Component guide: `seed/CLAUDE.md` (31 primitives + 16 patterns)
- Skills: 10 slash commands (/ui-page, /ui-component, etc.)

### Project-Specific Overrides
- Brand color: #3B82F6 (blue, changed from default purple)
- Primary domain: E-commerce
- Language: English (default seed examples are Korean)

### Component Usage
When building UI:
1. Check if a seed component exists first
2. Use /ui-review to validate compliance
3. Follow the information pyramid for page layout
4. Never place content outside cards

### Code Conventions
- [Your project-specific code conventions here]
- [API patterns, state management, etc.]

How Claude Code Processes Multiple Files

When Claude Code sees both DESIGN.md and DESIGN-LANGUAGE.md in a project:

  1. It reads all markdown files in the project root
  2. CLAUDE.md is given highest priority (it's the AI instruction file)
  3. DESIGN-LANGUAGE.md provides detailed visual rules
  4. DESIGN.md provides general conventions

If rules conflict, the more specific file wins:

  • DESIGN-LANGUAGE.md (UI-specific) overrides DESIGN.md (general) for visual decisions
  • DESIGN.md wins for non-UI concerns (API design, architecture, etc.)

Contributing StyleSeed to awesome-design-md

StyleSeed's DESIGN-LANGUAGE.md follows the awesome-design-md format and can be submitted as a community contribution. The file is self-contained and doesn't require the component code to be useful -- the 69 rules alone are valuable context for any AI coding tool generating Tailwind CSS UI.

Clone this wiki locally