Contributing Guide

Checklist-driven guide for making pull requests

Before You Start

Clone the repository

git clone https://github.com/shalomormsby/sage-design-engine.git cd ecosystem

Enable Corepack and install dependencies

corepack enable pnpm install

This project uses pnpm as the package manager. Corepack ensures you're using the correct version.

Verify setup

pnpm --filter @thesage/ui build pnpm --filter web dev

This builds the design system and starts the studio app at localhost:3001

Making Changes

1
Create a new branch
```
git checkout -b feature/component-name
```
Use descriptive branch names: feature/, fix/, or docs/
2
Make your changes
Follow the patterns in the "Adding Components" guide inside packages/ui.
3
Test locally in studio app
```
pnpm --filter @thesage/ui build pnpm --filter web dev
```
Verify your changes work across all three themes (Studio, Sage, Volt)

Pre-PR Checklist

Before submitting your pull request, ensure all of these items are complete:

Build succeeds

pnpm --filter @thesage/ui build

No TypeScript errors

Check for type errors in your IDE or run the build command

Component works in all three themes

Test Studio, Sage, and Volt themes in the studio app

Motion respects prefers-reduced-motion

If you added animations, ensure they're disabled when motion is reduced

Component added to studio showcase

Add your component to ComponentsSection under the appropriate functional category

Exports updated in index.ts

Ensure your component is exported from packages/design-system/src/components/index.ts

Submitting a Pull Request

Commit your changes

git add . git commit -m "feat: add NewComponent to design system"

Use conventional commit format: feat:, fix:, docs:, etc.

Push to your fork

git push origin feature/component-name

Create PR on GitHub

Go to the repository and click "Create Pull Request". Use this template:

## Summary
- Added NewComponent to the design system
- Organized functionally by primary purpose
- Supports all three themes

## Changes
- Created NewComponent.tsx in components/[category]/
- Added exports to category index and main barrel
- Updated ComponentsSection to showcase component
- Built and tested in studio app

## Design Philosophy
This component embodies [principle from DESIGN-PHILOSOPHY.md]

## Screenshots
[Add screenshots showing the component in Studio, Sage, and Volt themes]

## Checklist
- [x] Build succeeds
- [x] No TypeScript errors
- [x] Works in all three themes
- [x] Motion respects prefers-reduced-motion
- [x] Added to studio showcase
- [x] Exports updated

Link to Design Philosophy

Reference specific principles from DESIGN-PHILOSOPHY.md that your contribution addresses. This helps reviewers understand your design decisions.

Code Review Process

What to expect

→Maintainers will review your code for quality, consistency, and adherence to design principles
Feedback may include requests for changes or improvements
Be responsive to feedback and iterate on your changes
Once approved, your PR will be merged into the main branch

Thank you for contributing! Your work helps make this design system better for everyone.