Contributing

Getting Started

Prerequisites:

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

The repo pins its package manager via the packageManager field — use pnpm for all repository commands.

Development

The docs site is the primary development environment:

After editing Web Component source in packages/web-components/src/ or tokens in shared/tokens.js, regenerate everything — framework wrappers, HTML examples, and CSS:

Version bumps go through a script that updates every package at once — never edit package.json versions by hand:

Architecture

ARC UI is a monorepo with Lit Web Components as the single source of truth. Prism, a custom code generator, reads the Web Component 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 — the single source of truth. shared/base.css is generated from it by pnpm generate. Compound tokens must use var() references so consumers can override just the base tokens.

Pull Requests

1. Fork the repository and create a feature branch from main
2. Make your changes to the Web Component source
3. Run pnpm generate to regenerate wrappers and CSS
4. Run pnpm lint and pnpm format:check
5. Test your changes in the docs site (pnpm dev)
6. Open a pull request describing the change

Reporting Issues

Open an issue on GitHub with:

• 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