Skip to main content

​
Overview

The Conty Design System is built in public with small, frequent contributions. This guide will help you contribute effectively to the project.

​
Prerequisites

Before you start, ensure you have the following installed:
  • Node.js >= 20
  • npm

​
Local Setup

1

Clone the repository

Clone the Conty Design System monorepo to your local machine.
2

Install dependencies

npm install
This will install all dependencies for all packages in the monorepo.
3

Start Storybook

npm run storybook
Storybook will open at http://localhost:6006 - this is your development environment.
The @storybook/addon-mcp is enabled. Validate the MCP endpoint at http://localhost:6006/mcp during local setup.

​
Available Scripts

The monorepo provides several useful scripts:
ScriptDescription
npm run storybookStart the Storybook development server
npm run build-storybookBuild Storybook for production
npm run buildBuild all packages in the monorepo
npm run lintRun ESLint across all packages
npm run typecheckValidate TypeScript types across all packages

​
Contribution Workflow

1

Create a feature branch

Create a new branch for your changes. Keep the scope small and focused.
git checkout -b feature/your-feature-name
2

Make your changes

Develop your component or feature in Storybook. Follow the Definition of Done criteria.
3

Run quality checks

Before committing, ensure all checks pass:
npm run lint
npm run typecheck
npm run build
4

Create a changeset

Document your changes using Changesets:
npm run changeset
This command will prompt you to:
  • Select which packages were affected
  • Choose the version bump type (major, minor, patch)
  • Write a summary of the changes
5

Commit your changes

Commit your changes with a clear, descriptive message:
git add .
git commit -m "feat: add new Button component"
6

Open a Pull Request

Push your branch and open a PR with:
  • Context: why this change is needed
  • What changed: summary of modifications
  • How to test: instructions for reviewers

​
Changesets Workflow

We use Changesets to manage versioning and releases.

​
Creating a Changeset

When you make a change that affects package consumers: 
npm run changeset
The CLI will guide you through:
  1. Package selection: Choose which packages are affected by your change
  2. Version bump: Select the type of version bump:
    • Patch: Bug fixes and minor updates
    • Minor: New features (backwards compatible)
    • Major: Breaking changes
  3. Summary: Write a brief description of the change
Changesets are stored in .changeset/ as markdown files. These files are committed with your changes and used during release.

​
Release Process

The release process is managed by maintainers:
1

Version packages

npm run version-packages
This applies all pending changesets and updates package versions.
2

Publish packages

npm run release
This publishes updated packages to npm.
Only maintainers with publish permissions should run the release commands.

​
Monorepo Structure

The Conty Design System is organized as a monorepo with the following packages:
The main entry point package for external consumption. Import this package in your applications.
Design tokens and theme definitions. Contains the canonical tokens.json file with all visual values.
Reusable React components. This is where most component development happens.
Visual catalog and development environment. The official place to develop and validate UI components.
Shared ESLint configurations for consistent code style.
TypeScript presets and configurations.

​
Principles

When contributing, keep these principles in mind:

​
Storybook-First

Every component is born and evolves in Storybook. Stories are not just documentation - they are also test cases covering rendering, interaction, accessibility, and visual regression.

​
Token-First

No visual values (colors, spacing, radius, typography, shadows, motion) should be hardcoded in components. Values must exist in tokens.json and be referenced in components.
Components that hardcode visual values instead of using tokens will not be accepted.

​
Incremental Without Stopping Product

Migration happens in waves, by domain. Use feature flags and fallbacks for sensitive flows.

​
Stable Semantic Contract

Token names define intention, not implementation. Use the same semantic names between TypeScript and Dart. Avoid renaming tokens in use - prefer deprecation with a migration window.

​
Getting Help

If you need help:

Build docs developers (and LLMs) love

Get started for freeTalk to us