Contributing

Help improve the Everforth Design System. This guide covers how to contribute code, documentation, and design patterns.

Getting Started

Prerequisites

Before contributing, ensure you have:

• Node.js 18+ installed
• Git configured
• Familiarity with SCSS and CSS
• Basic understanding of design systems

Development Setup

# Clone the repository
git clone https://github.com/everforth/design-framework.git
cd design-framework

# Install dependencies
npm install

# Start development server
npm run dev

# Build CSS
npm run build:css

# Build documentation
npm run docs:build

Project Structure

design-framework/
├── src/
│   └── scss/
│       ├── base/           # Reset, typography, base styles
│       ├── components/     # Individual component styles
│       ├── layout/         # Grid, containers, spacing
│       ├── utilities/      # Helper classes
│       └── main.scss       # Main entry point
├── docs/
│   ├── .vitepress/         # VitePress configuration
│   ├── components/         # Component documentation
│   ├── foundations/        # Design tokens docs
│   └── guidelines/         # Usage guidelines
├── dist/                   # Built CSS output
└── package.json

Contribution Types

Bug Fixes

Found a bug? Here's how to report and fix it:

1. Check Existing Issues

Search the issue tracker to see if it's already reported.

2. Create an Issue

If not found, create a new issue with:

• Clear description of the bug
• Steps to reproduce
• Expected vs actual behavior
• Browser/device information
• Screenshots if applicable

3. Submit a Fix

Fork the repo, create a branch, fix the issue, and submit a PR.

New Components

Want to add a component? Follow these steps:

1

Proposal

Open an issue describing the component, its use cases, and how it fits the system.

2

Design Review

Work with maintainers to review the design and API before implementation.

3

Implementation

Build the component following our coding standards and patterns.

4

Documentation

Add complete documentation with examples, variants, and usage guidelines.

5

Review & Merge

Submit PR for review. Address feedback and get approval from maintainers.

Documentation Updates

Improving documentation is highly valuable:

• Fix typos and clarify confusing sections
• Add missing examples or use cases
• Improve code samples
• Add accessibility notes
• Translate content

Coding Standards

SCSS Guidelines

// ==========================================================================
// COMPONENT NAME
// ==========================================================================
// Brief description of the component and its purpose.
//
// USAGE:
// <div class="df-component">...</div>
// ==========================================================================

// --------------------------------------------------------------------------
// BASE COMPONENT
// --------------------------------------------------------------------------

.df-component {
  // Use design tokens, not raw values
  padding: var(--df-spacing-md);
  color: var(--df-color-text-primary);

  // Group related properties
  display: flex;
  align-items: center;
  gap: var(--df-spacing-sm);
}

// --------------------------------------------------------------------------
// VARIANTS
// --------------------------------------------------------------------------

// Size variants
.df-component--sm {
  padding: var(--df-spacing-sm);
  font-size: var(--df-font-size-sm);
}

.df-component--lg {
  padding: var(--df-spacing-lg);
  font-size: var(--df-font-size-lg);
}

// State variants
.df-component--disabled {
  opacity: 0.5;
  pointer-events: none;
}

Naming Conventions

We use BEM (Block Element Modifier) methodology:

Type	Pattern	Example
Block	.df-[component]	.df-button
Element	.df-[component]__[element]	.df-button__icon
Modifier	.df-[component]--[modifier]	.df-button--primary
State	.is-[state] or .[component]--[state]	.is-active, .df-button--disabled

Design Token Usage

Do

.component {
  color: var(--df-color-text-primary);
  padding: var(--df-spacing-md);
  border-radius: var(--df-radius-md);
  font-size: var(--df-font-size-base);
}

Don't

.component {
  color: #1e2832;
  padding: 16px;
  border-radius: 8px;
  font-size: 16px;
}

Accessibility Requirements

Every component must:

Include keyboard navigation support

Have visible focus states

Meet WCAG 2.1 AA color contrast

Include appropriate ARIA attributes

Document screen reader behavior

Pull Request Process

Before Submitting

1. Branch naming: Use feature/, fix/, or docs/ prefixes

   feature/add-accordion-component
   fix/button-focus-state
   docs/improve-color-examples

2. Commit messages: Write clear, descriptive commits

   feat(button): add loading state variant
   fix(modal): correct focus trap on close
   docs(colors): add accessibility notes

3. Self-review checklist:

   • Code follows our style guidelines
   • Changes are documented
   • No console.log or debug code
   • CSS builds without errors
   • Changes tested in multiple browsers

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Breaking change

## Testing
How was this tested?

## Screenshots
If applicable, add screenshots

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have added documentation
- [ ] My changes are accessible

Review Process

1. Automated checks - CI runs linting and build
2. Maintainer review - At least one approval required
3. Address feedback - Respond to comments and make changes
4. Merge - Squash and merge once approved

Documentation Guidelines

Component Documentation Structure

Every component page should include:

# Component Name

Brief description of what the component does.

## Usage

When and why to use this component.

## Examples

### Basic Example
[Live demo + code]

### Variants
[Show all variants with demos]

## Props/Classes

| Class | Description |
|-------|-------------|
| `.df-component` | Base class |
| `.df-component--variant` | Variant description |

## Accessibility

- Keyboard navigation details
- ARIA requirements
- Screen reader behavior

## Best Practices

### Do
- Guidance on correct usage

### Don't
- Common mistakes to avoid

Writing Style

• Use second person ("you") not first person ("we")
• Be concise and direct
• Include code examples for everything
• Test all code samples before committing

Getting Help

Resources

• GitHub Issues - Report bugs and request features
• Discussions - Ask questions and share ideas
• Documentation - This site has comprehensive guides

Contact

• Create an issue for bugs or features
• Open a discussion for questions
• Tag @maintainers for urgent items

Code of Conduct

We are committed to providing a welcoming and inclusive experience. All participants are expected to:

• Be respectful and considerate
• Welcome newcomers and help them learn
• Accept constructive criticism gracefully
• Focus on what is best for the community

Recognition

Contributors are recognized in:

• Release notes when their changes ship
• The contributors page on our site
• Monthly contributor highlights

Thank you for helping improve the Everforth Design System!