Skip to content
LoomiUI LoomiUI LoomiUI

Contributing

LoomiUI is open source and contributions are welcome. This page is a quick orientation; the full, in-depth contributor guide lives in the repository:

→ Full contributor guide on GitHub

What contributions are welcome

Section titled “What contributions are welcome”
  • Bug fixes — corrections to component behavior, accessibility, or styling.
  • New components — see Adding a new component in the full guide.
  • Accessibility improvements — keyboard support, ARIA roles, focus management.
  • Documentation — clearer explanations, examples, and fixes to these docs.
  • Translations — adding or improving a built-in language.

If you are unsure whether something is in scope, open an issue first and ask.

Reporting bugs and requesting components

Section titled “Reporting bugs and requesting components”

Use the GitHub issue tracker — pick the matching template:

→ Open an issue (bug report or feature/component request)

A good bug report includes the component, what you expected, what happened, and a minimal reproduction. A component request should describe the use case and any similar prior art.

Local development setup

Section titled “Local development setup”

LoomiUI is a monorepo managed with pnpm. You need Node 20 or later.

Terminal window
git clone https://github.com/loomidev/loomiui.git
cd loomiui
corepack enable      # turns on pnpm (bundled with Node 16.9+)
pnpm install         # install deps + link workspace packages
pnpm build           # compile every package into its dist/

pnpm dev rebuilds packages on change. See the full setup section for the corepack fallback and why the project uses pnpm.

Repository and package structure

Section titled “Repository and package structure”

Everything lives in one repository. Each component is its own npm package under packages/:

  • Component packages — one folder per component (packages/button, packages/input, …), published as @loomidev/<name>.
  • Foundation packages — @loomidev/core, @loomidev/theme, and @loomidev/icons; every component depends on these.
  • Bundle packages — @loomidev/forms, @loomidev/content, and @loomidev/navigation group related components; @loomidev/components is the “install everything” umbrella.

For how a single package is laid out and how theming works, see Anatomy of a package and The theming model.

Testing, linting, and build requirements

Section titled “Testing, linting, and build requirements”

Before opening a pull request, make sure these pass from the repository root:

Terminal window
pnpm build        # compile all packages (tests run against dist/)
pnpm typecheck    # TypeScript type-checking
pnpm test         # smoke tests via @web/test-runner (real headless Chromium)
pnpm lint         # ESLint
pnpm format       # Prettier (or `pnpm format:check` to verify without writing)

Continuous integration runs build, typecheck, and test on every push and pull request, so a PR that fails any of them cannot merge. New components should ship with at least one smoke test.

Pull request expectations

Section titled “Pull request expectations”
  • Branch off main and keep each PR focused on a single change.
  • Green checks — build, typecheck, and test must pass locally and in CI.
  • Add a changeset for any user-facing change: run pnpm changeset and commit the generated file so your change lands in the changelog and version bump.
  • Follow the PR template and link the issue your PR addresses.
  • For a new component, follow the step-by-step checklist in the full guide.

Code of conduct and templates

Section titled “Code of conduct and templates”