Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
78 lines (59 loc) · 2.63 KB

CONTRIBUTING.md

File metadata and controls

78 lines (59 loc) · 2.63 KB

Contributing to Weft

Thanks for your interest in contributing! This project is about crafting professional-grade design systems that AI agents can read and apply — not just extracting tokens from websites.

Ground Rules

  1. Quality over quantity. One excellent DESIGN.md is worth more than ten mediocre ones.
  2. Opinionated is good. Each system should make strong design decisions. "It depends" is not a design guideline.
  3. Test with agents. Before submitting, test your DESIGN.md with at least one AI coding agent (Claude Code, Cursor, or Copilot) and include screenshots of generated output.
  4. Accessibility is non-negotiable. Every system must meet WCAG 2.1 AA at minimum.

What We're Looking For

New Design System Archetypes

Before creating a new system, open an issue to propose it. Include:

  • Archetype name and target use case
  • Why existing systems don't cover it
  • 3-5 reference products that embody this archetype
  • Key design decisions that differentiate it

Improvements to Existing Systems

  • Fix incorrect token values
  • Add missing component patterns
  • Improve edge case coverage
  • Better agent instructions
  • Accessibility improvements

Agent Compatibility Testing

  • Test systems with different AI agents and report results
  • Document agent-specific quirks or workarounds

DESIGN.md Format

Every file must include all 12 sections. Use the template as your starting point.

Writing Guidelines

Be precise, not verbose.

# Bad
"Use a nice blue color for primary actions"

# Good
"Primary actions: #0052CC. Use for CTAs, submit buttons, and primary links. 
Minimum contrast ratio against white: 4.6:1 (AA)."

Include agent-ready prompts.

# Bad
"Cards should look clean"

# Good
"Create a card: white bg, 1px solid #E5E7EB border, 8px radius, 
24px padding. Title 16px/600 Inter, body 14px/400 #6B7280. 
Hover: translateY(-2px) + shadow 0 4px 12px rgba(0,0,0,0.08)."

Specify anti-patterns.

# Don't
- Don't use shadows heavier than 0.12 opacity on cards
- Don't mix rounded (8px) and sharp (0px) corners in the same view
- Don't use the primary blue for decorative elements — it's reserved for actions

Pull Request Process

  1. Fork the repo
  2. Create a branch: git checkout -b add-{archetype-name}
  3. Add your DESIGN.md following the template
  4. Test with at least one AI agent
  5. Include agent-generated screenshots in your PR description
  6. Submit PR with a clear description of the archetype and design decisions

Code of Conduct

Be respectful. Design is subjective — defend your decisions with rationale, not volume.