Contributing

Puzzle is developed as a Bun workspace monorepo. Contributions should be focused, tested, accessible, and consistent with the existing component and package conventions.

Puzzle is not production-ready. Public APIs and package boundaries may change while the project evolves.

PrerequisitesCopy Anchor Link

• Git.
• Bun 1.4.4 or a compatible newer version.
• Node.js 20.19 or later for the project generator and related tooling.
• Docker with Compose for MongoDB integration tests.

Clone the repositoryCopy Anchor Link

git clone https://github.com/senorprogramador/puzzle.git
cd puzzle
bun install

Repository structureCopy Anchor Link

Start developingCopy Anchor Link

Start the documentation site:

bun run site

Start the component playground:

bun run dev

Start Storybook:

bun run storybook

Project conventionsCopy Anchor Link

Before changing a package, inspect its existing implementation and the closest related example. Prefer established patterns over introducing new abstractions.

ComponentsCopy Anchor Link

• Use functional React components and arrow functions.
• Use named exports.
• Keep components generic and router-independent.
• Prefer semantic HTML and native browser behavior.
• Keep public APIs small and composable.
• Preserve existing behavior unless a breaking change is intentional.

Styling and themesCopy Anchor Link

• Use existing --puzzle-* CSS variables.
• Prefer semantic theme tokens over hardcoded values.
• Keep component styles scoped to the component.
• Respect light and dark themes.
• Respect reduced-motion preferences.
• Avoid adding dependencies for small styling or interaction requirements.

AccessibilityCopy Anchor Link

Interactive components should cover:

• Keyboard navigation.
• Focus management and visible focus.
• Screen-reader support.
• Correct ARIA roles and relationships.
• Touch and pointer interactions.
• High-contrast environments.
• Reduced-motion preferences.

Use native HTML semantics where possible. Do not add ARIA attributes that duplicate native browser behavior.

TestsCopy Anchor Link

Add tests for meaningful behavior and regressions. Follow the test organization used by the package.

Use unit tests for isolated logic, component tests for rendered behavior, and browser tests for interactions that depend on a real browser.

See Testing for the available commands.

DocumentationCopy Anchor Link

The documentation site lives in apps/site.

UI component pages are organized by category under:

apps/site/content/docs/ui/

Theme documentation lives under:

apps/site/content/docs/theme/

Developer guides live under:

apps/site/content/docs/developer/

When adding a documentation page:

1. Add the MDX page in the appropriate category.
2. Include a title and description in its frontmatter.
3. Include installation or import instructions where relevant.
4. Document the public API and important behavior.
5. Include practical examples.
6. Explain accessibility behavior where relevant.
7. Add the page to the corresponding sidebar configuration.
8. Verify that all documented imports exist.

Use the existing Fumadocs and Puzzle documentation components. Stateful examples should be reusable components rather than duplicated inline implementations.

Validate your changesCopy Anchor Link

Run the narrowest relevant checks first.

For a full repository validation:

bun run typecheck
bun run build
bun run vitest

For documentation changes:

bun run --filter "@puzzle-ui/site" typecheck
bun run --filter "@puzzle-ui/site" build

See Testing for package-specific test commands and requirements.

Pull requestsCopy Anchor Link

Keep pull requests focused and explain:

• What changed.
• Why the change is needed.
• Which packages or public APIs are affected.
• Which tests and checks were run.
• Any known limitations or follow-up work.

Include screenshots or short recordings when a visual or interaction change is difficult to understand from code alone.