Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
147 lines (114 loc) · 5.94 KB

CONTRIBUTING.md

File metadata and controls

147 lines (114 loc) · 5.94 KB
Raw

Contributing to Mado UI

Thanks for helping improve Mado UI. The project is intentionally an open-code registry and a zero-dependency Node CLI, not a browser runtime library. Applications own every installed component, style, block and template.

Welcome contributions

  • Bug fixes with a focused regression test.
  • Accessibility, browser behavior and responsive-layout fixes.
  • Documentation and catalog improvements.
  • Small improvements to existing registry items or CLI behavior.

Please open an issue before investing in a new public item, changing the CLI or lock contract, or incrementing the registry compatibility generation. Describe the problem and the platform behavior first; an implementation proposal can follow.

Local setup

Mado UI requires Node 22.12 or newer and the npm version declared in package.json#packageManager.

npm ci
npm run catalog:dev

The browser suites require Chromium or Chrome. They use the chrome channel by default. Set MADO_UI_BROWSER_CHANNEL or MADO_UI_BROWSER_PATH when the browser is installed elsewhere.

Repository map

  • src/cli/ contains the source installer.
  • registry/registry.json is the only source of installable item metadata.
  • registry/ contains the readable source copied into applications.
  • schema/ defines the public config, lock and registry formats.
  • catalog/sections/ contains one visual showcase per registry item.
  • catalog/showcase.manifest.ts connects those showcases to the catalog.
  • docs/ records architecture and public contracts.
  • test/ contains Node tests; test/browser/ is auto-discovered browser coverage.
  • scripts/package-smoke.mjs validates the exact npm tarball.

Project boundaries

  • Keep dependencies and peerDependencies absent.
  • Do not add a root runtime export. Applications do not import @madojs/ui.
  • Registry source may import only public @madojs/mado APIs and browser platform APIs.
  • Prefer native HTML. Add custom behavior only with tested semantic, keyboard, focus, form and fallback parity.
  • Keep installed source application-owned. Plan and validate a complete CLI operation before its first write.
  • Prefix public elements and classes with mado-ui-, public CSS properties with --mado-ui-, and private CSS properties with --_mado-ui-.
  • Author design colors in OKLCH. Use browser system colors for forced-colors overrides.
  • Keep dependencies acyclic and layered: foundation → primitive → block → template.

The complete maintainer contract lives in AGENTS.md.

Adding a registry item

  1. Add readable source under the matching registry/ kind.
  2. Register its metadata, Mado range, dependencies and targets in registry/registry.json.
  3. Add one isolated catalog/sections/*.section.ts showcase and register it in catalog/showcase.manifest.ts.
  4. Update the relevant public contract in docs/.
  5. Add focused Node and real-browser coverage where applicable.
  6. Add every published source file to the required-file contract in scripts/package-smoke.mjs, including its exact entry count.
  7. Record the user-visible change in CHANGELOG.md.

Catalog metadata must continue to come from the registry rather than being duplicated in showcase modules. Exercise native semantics, keyboard and focus behavior, narrow layouts, 200% text zoom, light and dark color schemes, forced-colors and reduced-motion whenever they apply.

Code and commits

The repository uses ESM, strict TypeScript, two-space indentation, double quotes and semicolons. There is intentionally no formatter dependency. Comments should explain constraints and decisions rather than restating code.

Keep a pull request to one logical change. Prefer clear English commit messages such as feat(scope): ..., fix(scope): ... or test(scope): .... Update tests and documentation in the same change as the behavior they describe.

Before opening a pull request

npm run verify
npm audit --audit-level=high

verify validates the registry and schemas, typechecks source, runs Node and browser tests, builds the catalog and inspects the packed npm artifact.

Maintainer releases

Package versions and Mado versions evolve independently. A release tag must point to a commit on main and exactly match package.json:

  1. Run npm version <version> --no-git-tag-version to update package.json and package-lock.json.
  2. Finish the matching CHANGELOG.md section with its release date.
  3. Run the pull-request gates above and npm run release:check -- v<version>.
  4. Commit and push main.
  5. Create and push an annotated v<version> tag.

.github/workflows/release.yml validates the tag again, verifies the package, publishes it to npm and creates the GitHub release. Stable versions move latest, -canary.* versions use canary, and every other SemVer prerelease uses next.

If npm publication succeeds but GitHub release creation fails, rerun only the failed release job. Never move or reuse a published tag, and do not rerun the immutable npm version as a new full release.

The release workflow publishes only through npm Trusted Publishing and GitHub OIDC. Do not add a write-capable npm token to the repository.

A brand-new npm package must be bootstrapped once by a maintainer from the exact release tag with normal interactive 2FA:

npm publish --ignore-scripts --access public --tag latest --provenance=false

After that first publish, configure npm Trusted Publishing for organization madojs, repository ui, workflow release.yml, no environment, and the npm publish action. Under Publishing access, select “Require two-factor authentication and disallow tokens”. Trusted Publishing continues to work because it uses the workflow's short-lived OIDC identity rather than a traditional npm access token. The one local bootstrap release has no provenance attestation; later GitHub OIDC releases generate provenance automatically.

License

By contributing to Mado UI, you agree that your contribution is licensed under the MIT License.