← Home Gallery Getting Started Components Tokens Templates Contributing Brand

Contributing

Help improve the Valley Solar Design System. Whether you're adding a new component, fixing a bug, or improving documentation, here's how to contribute.

Before You Start

The design system is maintained in two places:

Claude Design — Where changes are authored and tested with live preview
GitHub Repository — The canonical source code and home for pull requests

Changes are authored in Claude Design, then exported and committed to GitHub.

Adding a New Component

1. Design the component

Create a new design file in Claude Design to explore the component's states and variants. Test with real content.

2. Build the component

Create a .jsx or .tsx file with a .d.ts TypeScript definition. Use design tokens for all styling.

// Button.jsx
export function Button({ children, variant = 'primary' }) {
  return (
    <button className={`btn btn--${variant}`}>
      {children}
    </button>
  );
}

3. Create a design card

Add an HTML preview file with the @dsCard tag so the component appears in the design system gallery.

<!-- @dsCard group="02_Components" name="Button" -->

4. Test and iterate

Use the live preview in Claude Design to test interactive states, responsive behavior, and edge cases.

Modifying Tokens

Design tokens live in colors_and_type.css:

Edit the CSS file to add or update tokens
Update the documentation in docs-tokens.html
Test all components to ensure they work with the new tokens
Commit with a clear message: Update: Add new color token --vs-teal

Creating a New Template

Templates are full-page layouts ready to use or customize.

Create a new folder: templates/[template-slug]/
Add index.html with the template markup

Include a @template comment at the top:

<!-- @template name="Page — My Template" description="Brief description" group="04_Templates" -->

Update templates-manifest.json to register the template
Add the template to docs-templates.html

Fixing a Bug

Identify the issue and locate the affected component or token
Fix the code in Claude Design or the source file
Test thoroughly before committing
Commit with a clear message: Fix: Button hover state not visible on dark backgrounds

Commit Message Guidelines

Use clear, descriptive commit messages:

Add: New Badge component for status labels
Update: Improve heading type scale and contrast
Fix: Mobile nav dropdown alignment issue
Docs: Add Getting Started guide
Refactor: Consolidate button variants

Before Committing

Test in multiple browsers — Chrome, Firefox, Safari
Check accessibility — Keyboard navigation, screen readers, color contrast
Verify responsive design — Mobile, tablet, desktop
Update documentation — Add or update component docs and design log
Update changelog — Add entry to design-system-log.md

Design System Maintenance

Keep the design system healthy by:

Removing deprecated components after a transition period
Consolidating similar patterns into one canonical version
Keeping documentation current with code changes
Soliciting feedback from teams using the system

Questions?

Open an issue on GitHub to ask questions or propose changes.