Before You Start

For a non-trivial API change, align on scope and compatibility first. The Solid port aims to preserve the original Kumo API and visual behavior unless Solid’s reactivity model requires a documented difference.

1. Set Up the Repository

git clone https://github.com/photon-hq/kumo-solidjs.git
cd kumo-solidjs
pnpm install

Requirements:

• Node ^24.12.0
• pnpm >=10.21.0

The local base-ui-solid project is the reference for primitive behavior and Solid render-prop conventions.

2. Pick the Right Location

• Solid component: packages/kumo-solid/src/components/
• Solid code utilities: packages/kumo-solid/src/code/
• Solid block: packages/kumo-docs-astro/src/components/kumo/
• Demo: packages/kumo-docs-astro/src/components/demos/
• Documentation: packages/kumo-docs-astro/src/pages/

Keep the component name, variants, semantic tokens, and accessibility behavior aligned with the corresponding implementation under packages/kumo/.

3. Start the Development Server

pnpm --filter @cloudflare/kumo-docs-astro dev

The Astro development configuration resolves @photon-ai/kumo-solid imports directly to source, so component changes hot-reload without rebuilding the package.

To validate the same distribution files a consumer will use:

pnpm --filter @photon-ai/kumo-solid build
pnpm --filter @cloudflare/kumo-docs-astro build

4. Implement Compatibility Changes

When porting or fixing a component:

1. Compare its public API and styling with packages/kumo/src/.
2. Use the matching primitive from @photon-ai/base-ui-solid when available.
3. Model local state with Solid signals, memos, effects, and cleanup.
4. Preserve semantic HTML, ARIA attributes, focus behavior, and keyboard interactions.
5. Add or update a Solid demo and focused tests.

Use Kumo semantic tokens such as bg-kumo-base, text-kumo-default, and border-kumo-line. Do not add raw palette colors or Tailwind dark: variants.

5. Validate Before a PR

pnpm --filter @photon-ai/kumo-solid typecheck
pnpm --filter @photon-ai/kumo-solid lint
pnpm --filter @photon-ai/kumo-solid test
pnpm --filter @photon-ai/kumo-solid build

pnpm --filter @cloudflare/kumo-docs-astro typecheck
pnpm --filter @cloudflare/kumo-docs-astro lint
pnpm --filter @cloudflare/kumo-docs-astro test
pnpm --filter @cloudflare/kumo-docs-astro build

Also exercise the affected demo in the browser at desktop and mobile widths. For interactive primitives, verify pointer, keyboard, focus-return, controlled, and uncontrolled behavior.

6. Changesets

@photon-ai/kumo-solid is currently private and versioned as workspace development software, so it does not yet participate in the public release flow. Do not run version or publish commands. Add release tooling only when the package is intentionally prepared for publication.

7. Pull Requests

• Branch from the repository’s current mainline branch.
• Keep changes focused on one compatibility area.
• Describe intentional differences from React Kumo.
• Include the exact commands and browser interactions used for validation.
• Avoid editing generated registry and theme files directly.