Contributing to Aural UI

We welcome contributions from the community. Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Ways to Contribute

Getting Started

  1. Fork and Clone 
    git clone https://github.com/your-username/aural-ui.git
cd aural-ui
git checkout -b feature/my-new-feature
  2. Make Your Changes

    Follow our coding standards and design principles when making changes.

  3. Test Thoroughly
    • Test your changes in all supported browsers
    • Verify all themes work correctly
    • Check accessibility with screen readers
    • Ensure responsive behavior on mobile devices
  4. Submit a Pull Request

    Open a pull request with a clear description of your changes and why they're needed.

Code Contribution Guidelines

CSS Standards
  • Use CSS Custom Properties: All colors, spacing, and typography should use design tokens
  • Mobile-First: Write mobile styles first, then add desktop overrides with media queries
  • BEM Naming: Follow BEM methodology for class names (e.g., .btn__icon--primary)
  • Consistent Spacing: Use the spacing scale (--space-*) for all padding and margins
  • Semantic Classes: Class names should describe purpose, not appearance
Accessibility Requirements
  • Ensure all color combinations meet WCAG AA contrast ratios (4.5:1 for text)
  • Provide clear focus states for all interactive elements
  • Use semantic HTML when adding component examples
  • Include ARIA attributes in documentation examples
  • Test with keyboard navigation
Browser Support
  • Chrome/Edge (last 2 versions)
  • Firefox (last 2 versions)
  • Safari (last 2 versions)
  • Mobile Safari (iOS 14+)
  • Chrome Android (last 2 versions)

Adding New Components

When contributing a new component, follow this structure:

Component File Structure

/* Component: Button Group
 * Description: Groups related buttons together
 * Category: Forms & Inputs
 * Accessibility: Requires role="toolbar" or role="group"
 */

.btn-group {
    display: flex;
    gap: var(--space-2);
    align-items: center;
}

/* Variants */
.btn-group--vertical {
    flex-direction: column;
}

/* States */
.btn-group .btn:focus {
    z-index: 1;
}

Documentation Requirements

  • Create a component page in /docs/components/
  • Include usage examples with HTML
  • Document all variants and modifiers
  • Provide accessibility guidance
  • Show the component in all themes
Tip: Look at existing components like buttons.html or cards.html for examples of well-documented components.
Working with CLAUDE.md and specs/: Every component has a spec at specs/components/<name>.md (anatomy, tokens, variants, states) and must use tokens from tokens/core//tokens/semantic/ rather than hardcoded values — checked automatically by npm run audit:tokens, which is blocking in CI. This applies whether you're editing by hand or pointing an AI coding assistant at the repo. See AI-Assisted Development for the full picture.

Creating New Themes

Themes in Aural UI are created by defining CSS custom properties. Here's the structure: 

/* Theme: My Custom Theme */
:root {
    /* Colors */
    --color-primary: #your-color;
    --color-secondary: #your-color;
    --color-success: #your-color;
    --color-warning: #your-color;
    --color-error: #your-color;
    --color-info: #your-color;

    /* Backgrounds */
    --color-bg-primary: #your-color;
    --color-bg-secondary: #your-color;
    --color-bg-tertiary: #your-color;

    /* Text */
    --color-text-primary: #your-color;
    --color-text-secondary: #your-color;
    --color-text-tertiary: #your-color;

    /* Borders */
    --color-border-subtle: #your-color;
    --color-border-medium: #your-color;
    --color-border-strong: #your-color;
}

Theme Requirements

  • All color tokens must be defined
  • Text colors must meet WCAG AA contrast ratios against backgrounds
  • Provide both light and dark variants if possible
  • Test with all components to ensure visual coherence
  • Update demo.js to include your theme in the selector
Accessibility: Always check color contrast ratios. Use tools like WebAIM Contrast Checker to verify your colors meet WCAG standards.

Reporting Issues

When reporting bugs or requesting features, please include:

Bug Reports

  • Description: Clear description of the issue
  • Steps to Reproduce: Exact steps to recreate the bug
  • Expected Behavior: What you expected to happen
  • Actual Behavior: What actually happened
  • Environment: Browser, OS, screen size
  • Screenshots: Visual evidence if applicable
  • Theme: Which theme was active when the issue occurred

Feature Requests

  • Use Case: Describe the problem you're trying to solve
  • Proposed Solution: Your idea for how to solve it
  • Alternatives: Other approaches you've considered
  • Examples: Links to similar implementations elsewhere

Pull Request Process

  1. Create an Issue: Before starting work, create an issue to discuss your proposed changes
  2. Branch Naming: Use descriptive names like feature/add-toast-component or fix/button-hover-state
  3. Commit Messages: Write clear commit messages describing what and why, not just what changed
  4. Documentation: Update documentation to reflect your changes
  5. Changelog: Add an entry to CHANGELOG.md under "Unreleased"
  6. Review: Address feedback from maintainers promptly

Example Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Theme addition/modification

## Checklist
- [ ] Tested in all supported browsers
- [ ] Tested with keyboard navigation
- [ ] Checked color contrast ratios
- [ ] Updated documentation
- [ ] Added changelog entry
- [ ] All themes work correctly

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

  • Be respectful and considerate of others
  • Welcome newcomers and help them learn
  • Focus on constructive feedback
  • Respect differing viewpoints and experiences
  • Accept responsibility for mistakes
Questions? Don't hesitate to ask for help. We're here to support contributors at all skill levels.

License

By contributing to Aural UI, you agree that your contributions will be licensed under the same license as the project (MIT License).