CONTRIBUTING.md

📖 Contributing to Helvetia Design System

Thank you for your interest in contributing! This document covers the contribution workflow — git, PRs, and community guidelines.

For setup, architecture, and code standards, see the dedicated documentation files linked at the bottom.

Table of Contents

• Code of Conduct
• Getting Started
• Git Workflow
• Reporting Issues
• Fixing a Bug
• Creating a Feature
• Adding a New Component
• Adding Icons
• Code Standards
• Testing
• Security
• Further Reading
• License

Code of Conduct

Please read and follow our Code of Conduct. We are committed to providing a welcoming and inclusive environment for all contributors.

Getting Started

Prerequisites

• Node.js: >=24 <25
• pnpm: 11.x

Setup

git clone https://github.com/baloise/design-system.git
cd design-system
nvm use
corepack enable
pnpm install --frozen-lockfile

For full setup instructions, troubleshooting, and dev server details, see DEVELOPMENT.md.

Git Workflow

Branch Naming

Use descriptive prefixes for branch names:

• feat/<name> — new features or components
• fix/<name> — bug fixes
• chore/<name> — maintenance tasks
• docs/<name> — documentation updates

Commit Messages

Write clear, descriptive commit messages:

feat: add button component with primary and secondary variants
fix: resolve focus state contrast issue on tag component
docs: update contribution guidelines

Creating a Pull Request

1. Create a changeset if your changes affect end users:

   pnpm changeset

   • patch — bug fixes, non-breaking style tweaks
   • minor — new features, new components
   • major — breaking changes (prop renames, removed elements, behavior changes)

   See ARCHITECTURE.md — Changesets and Versioning for how changesets flow into the release pipeline.

2. Open a PR against the next branch

   • Include a descriptive title
   • Reference related issues if applicable
   • Ensure all checks pass (pnpm lint && pnpm format)

3. Address review feedback before merging

Bot Commands

Post these as a PR comment to trigger automation:

Command	Effect
/update-screenshots	Regenerates visual regression snapshots and commits them to your branch. Use after intentional visual changes.
/snapshot	Publishes a snapshot npm version from your branch so you can test it in a real project before merging. See Snapshot Versions for details.
/cib	Post on an issue to auto-create a correctly named branch. The issue must have a type label (✨ feature, 🐛 bug, 🔧 chore, …); other labels such as ready-for-agent are skipped.

/cib is an issue comment, not a PR comment. The type label chooses the branch prefix: ✨ feature → feat/…, 🐛 bug → fix/…, 🔧 chore → chore/… (also ♻️ refactor, 🧪 test, 💥 breaking change, ⚡️ perf, 🚀 release, 🛡️ lts). Without one of those labels the workflow runs but creates nothing.

Reporting Issues

Start any contribution (bug fix or feature) by creating a GitHub issue:

1. Go to github.com/baloise/design-system/issues
2. Click New Issue
3. Choose Bug Report or Feature Request
4. Provide a clear title and description
5. Add labels and assign to a milestone if applicable

Once the issue is created, add a type label (✨ feature, 🐛 bug, 🔧 chore, ♻️ refactor, 🧪 test, 💥 breaking change, ⚡️ perf, 🚀 release, or 🛡️ lts) and comment /cib on that issue to auto-generate a branch:

/cib

This creates a properly named branch (e.g., feat/button-hover-state) and opens a PR automatically. Without a type label the workflow runs but skips the issue.

Fixing a Bug

1. Create an issue describing the bug (see Reporting Issues)

2. Create a branch via the /cib comment on the issue

3. Write a failing test that reproduces the bug:

   • Add a test case in the component's test file
   • Verify it fails with the current code

4. Fix the bug to make the test pass

5. Add a changeset:

   pnpm changeset

   • Choose patch for this bug fix

6. Finalize your PR:

   • Ensure all checks pass: pnpm lint && pnpm format && pnpm test
   • Get approval from a core team member
   • Merge to next

Creating a Feature

1. Create an issue describing the feature (see Reporting Issues)

2. Create a branch via the /cib comment on the issue

3. Implement the feature following STYLE_GUIDE.md

4. Add visual tests:

   • Identify which parts of the UI your feature affects
   • Create or update visual regression tests in the component's .visual.play.ts file
   • These automated screenshots verify the feature looks correct

5. Add component tests:

   • Write tests covering all critical functionality
   • Include both positive scenarios (expected use) and negative scenarios (edge cases, error handling)
   • Use Page Objects for component interactions
   • See ARCHITECTURE.md — Testing Strategy for patterns

6. Add a changeset:

   pnpm changeset

   • Choose minor for new features or major for breaking changes

7. Finalize your PR:

   • Ensure all checks pass: pnpm lint && pnpm format && pnpm test
   • Get approval from a core team member
   • Merge to next

Adding a New Component

See ARCHITECTURE.md — New Component Checklist for the full step-by-step checklist.

Key requirements:

• Use ds- prefix and Shadow DOM
• Implement ComponentInterface and Loggable
• Write unit, interaction, visual, and accessibility tests
• Add Storybook documentation

Adding Icons

Icons are stored in two packages depending on their source and usage:

UI Icons

Source: Streamline Icons (16×16 SVG)

Location: packages/icons/src/assets

Brand Icons

Source: Baloise Brand Portal (all colors, all sizes)

Location: packages/brand-icons/src/assets

Adding a New Icon

1. Download the icon(s) from the appropriate source

2. Place the SVG file(s) in the correct src/assets directory

3. Optimize SVG files for web:

   pnpm optimize

4. Create a changeset documenting the icon addition:

   pnpm changeset

5. Open a PR with a descriptive title (e.g., feat: add copy and download UI icons)

Code Standards

See STYLE_GUIDE.md for naming conventions, prop patterns, CSS variable cascade, and what to avoid.

Run these before every PR:

pnpm lint      # Check for violations
pnpm format    # Auto-fix formatting
pnpm spell     # Spell check

Testing

See ARCHITECTURE.md — Testing Strategy for required test types, Page Object patterns, and test file locations.

pnpm test                         # Unit tests
pnpm play                     # Playwright UI explorer
pnpm play -- --grep="<name>"  # Single test

Security

Please review our Security Policy before reporting vulnerabilities. Do not open public issues for security bugs — use the private advisory process described there.

Further Reading

• DEVELOPMENT.md — Setup, dev servers, building, testing commands
• ARCHITECTURE.md — Workspace structure, component patterns, CSS variables, testing strategy
• STYLE_GUIDE.md — Code standards and naming conventions
• SECURITY.md — Security policy and vulnerability reporting
• CODE_OF_CONDUCT.md — Community standards

License

By contributing, you agree that your contributions will be licensed under the same license as this project.