Contributing

ARC UI is open source and we welcome contributions. Here's how to get involved.

Getting Started

Prerequisites:

Node.js 24+ (LTS)
pnpm 10+
Git

Clone the repository and install dependencies:

Development

The docs site is the primary development environment. Start it with:

After modifying any web component source in packages/web-components/src/, regenerate all framework wrappers and CSS:

Never hand-edit files in packages/react/, packages/vue/, or packages/html/css/. These are generated by Prism and will be overwritten.

Architecture

ARC UI is a monorepo with Lit web components as the single source of truth. Prism, a custom code generator, reads the WC source and produces idiomatic wrappers for each framework.

Components are organized into seven tiers:

Layout — Page scaffolding (AppShell, Container, PageLayout)
Navigation — Menus, links, tabs, breadcrumbs
Content — Cards, avatars, icons, carousels
Data — Tables, lists, badges, meters, stats, timelines
Typography — Code blocks, markdown, text, kbd
Input — Buttons, forms, selects, sliders
Feedback — Modals, dialogs, toasts, tooltips

Design tokens live in shared/tokens.js (JS) and shared/base.css (CSS). Both files must be kept in sync. Compound tokens must use var() references so consumers can override just the base tokens.

Pull Requests

Fork the repository and create a feature branch from main
Make your changes to the WC source
Run pnpm prism to regenerate framework wrappers
Run pnpm lint and pnpm format:check
Test your changes in the docs site (pnpm dev)
Submit a pull request with a clear description of the change

Reporting Issues

Found a bug or have a feature request? Open an issue on GitHub. Please include:

A clear description of the issue or request
Steps to reproduce (for bugs)
Expected vs. actual behavior
Browser and OS version
A minimal reproduction if possible

Code Style

Web components are plain JavaScript (no TypeScript build step)
Use static properties instead of decorators
Follow existing naming: arc-component-name for tags, ArcComponentName for classes
All components import tokenStyles from ../shared-styles.js
Use var(--token-name) for all colors, spacing, and typography
Clean up event listeners in disconnectedCallback()
Support keyboard navigation and ARIA attributes for interactive components
Run pnpm format before committing