Contributing Guide

Clear instructions for contributing to the Evo ShadCN Component Registry, ensuring all components meet quality, documentation, and accessibility standards.

Quick Start for Contributors

Repository Setup

# Clone from Azure DevOps
git clone https://dev.azure.com/access-devops/Access%20Tag%20Components/_git/access-evo-shadcn-registry
cd access-evo-shadcn-registry

# Install dependencies
pnpm install

# Create feature branch
git checkout -b firstname.lastname/your-branch-name

Scaffolding New Components

Required Script Usage

All new UI deliverables can be created via the scaffolding script. It is suggested (not strictly required) to avoid hand-creating files because the script ensures correct folder placement, metadata, demo tabs, owner attribution, and overall registry consistency.

Commands:

Use the script below (recommended). Copy commands individually.

Experimental Block (prompts for owner & team)

npm run scaffold -- my-experimental-block --type=experimental-block

Stable Block (requires owner email)

npm run scaffold -- file-uploader --type=block

Base Component (Prometheus Squad only)

npm run scaffold button

Accepted Contribution Types

Not Accepted

❌ShadCN base components

Maintained by Prometheus Squad

❌Server-side code, backend logic

Accepted

✅Blocks

✅Experimental blocks

✅Demo content updates

Quality Gates

All contributions must pass these quality gates before review

Linting & Formatting (ESLint/Prettier)

WhiteSource (Mend) Security Check

SonarQube Validation (no tests)

Accessibility Validation

AI Compatibility Requirements

Experimental Blocks Must Include:

AI Compatibility Badge

Low 🔴Mid 🟡High 🟢

Testing Philosophy

TL;DR: Registry contains no unit tests. Contributors don't add tests. Consumers are responsible for testing in their own repositories.

Why no tests in the registry?

• Registry provides ShadCN-style primitives and reference components
• Components are meant to be consumed and adapted
• Tests are meaningful only in the context of each product's usage

Area	ShadCN Base	Experimental blocks
Unit tests in registry	None	None
SonarQube coverage	Not enforced	Not enforced
SonarQube issues	Prometheus Squad resolves	Contributor resolves
Tests in consumer repos	Consumer team (~80% coverage)	Consumer team (~80% coverage)

Review Process & SLA

P1 - Critical

Blocking bug, critical vulnerability

1 business day

P2 - High

New component PR, minor regression

3 business days

P3 - Normal

Styling/documentation PR

7 business days

Escalation Path

1. Follow up in Evo React Components Forum if no response in 3 business days

2. If still no progress, escalate to the Team Lead

Component Lifecycle

Add

Contributor + Prometheus Squad

Validate compliance and usefulness

Update

Component Owner

Submit PR for review

Deprecate

Prometheus Squad

Announce in changelog and provide alternatives

Remove

Prometheus Squad

Minimum 1-month notice or 2 release cycles

Getting Help

Support Channels

Azure DevOps Work Items

Create work items for bugs, feature requests, or questions

Access Evo Platform Support

Evo React Components Forum for discussions

Documentation

Refer to /docs/ pages in the running application

Responsibility Matrix

Experimental Blocks

Maintained by their owner

ShadCN/Evo React Components

Maintained by Prometheus Squad

Issues & Support

Tracked via support board

Ready to Contribute?

Follow the guidelines above and start building amazing components for the Evo Design System!

Read CONTRIBUTING.mdRun npm run pre-submitCreate ADO PR

Teams Channel

Getting Started