Kiso Development

Guidelines for contributing to the Kiso component library.

Where to find what

Getting started with a new component

Use bin/rails generate kiso:framework_component name to scaffold the initial files, then fill in the theme and partial.

Project structure

lib/kiso/themes/              Ruby theme modules (ClassVariants definitions)
app/views/kiso/components/    ERB partials (rendered via kui() helper)
app/assets/tailwind/kiso/     engine.css — shipped with gem (fonts + all color tokens)
app/helpers/kiso/             kui(), kiso_prepare_options() helpers
app/javascript/controllers/kiso/  Stimulus controllers (namespaced kiso--)
app/javascript/kiso/utils/    Shared JS utilities (positioning, highlight, focusable)
test/components/previews/kiso/  Lookbook previews + templates
skills/kiso/                  AI skill (update when adding components)
project/                      Architecture docs, design system, decisions
docs/                         Bridgetown docs site (published documentation)
lookbook/                     Lookbook dev app (bin/dev → port 4001)

CSS architecture

app/assets/tailwind/kiso/engine.css is what the gem ships. It contains Geist fonts, all default color tokens (@theme), dark mode overrides (.dark {}), and @source directives for Kiso's views, helpers, and theme modules. Never put color tokens in the Lookbook's application.css — they belong in engine.css so host apps get them too.

The tailwindcss:engines Rake task (from tailwindcss-rails v4) automatically detects any Rails engine with app/assets/tailwind/{engine_name}/engine.css and generates app/assets/builds/tailwind/{engine_name}.css. Kiso's engine name is kiso, so the directory must be app/assets/tailwind/kiso/.

Lookbook setup: lookbook/app/assets/tailwind/application.css imports the auto-generated engine file and adds Lookbook-specific source paths:

css
1@import "tailwindcss";
2@import "../builds/tailwind/kiso.css";
3
4@source "../../views";
5@source "../../../../test/components/previews";

Pull request workflow

Always include Closes #N in the PR body so GitHub auto-closes the issue on merge. This is the most commonly missed step.

bash
1# Create branch
2git checkout -b feat/{name}-component
3
4# Stage specific files (never git add -A)
5git add lib/kiso/themes/{name}.rb app/views/kiso/components/...
6
7# Commit
8git commit -m "feat: ComponentName component (#N)"
9
10# Push and create PR
11git push -u origin feat/{name}-component
12gh pr create --title "feat: ComponentName component" --body "$(cat <<'EOF'
13## Summary
14- [what was built]
15
16Closes #N
17
18## Test plan
19- [x] All Lookbook previews render (200)
20- [x] standardrb passes
21- [x] rake test passes
22- [ ] Visual review in Lookbook
23EOF
24)"

Commands

bash
1bin/dev                         # All services via Overmind (Lookbook :4001 + docs :4000)
2bin/dev -- -l web,css           # Lookbook + Tailwind only (no docs)
3bin/worktree start              # Start on worktree-assigned port
4bin/worktree port               # Show port for current worktree
5overmind restart web            # Restart Lookbook server
6bundle exec rake test           # Run Ruby tests
7npm run test:unit               # Run JS unit tests (Vitest)
8npm run test:e2e                # Run Playwright E2E tests (needs bin/dev)
9npm run test:e2e:ui             # Open Playwright GUI
10bundle exec standardrb --fix    # Lint & auto-format Ruby
11npm run lint                    # Lint JS (oxlint)
12npm run fmt                     # Format JS (oxfmt)

Additional conventions

• i18n — all user-visible text and ARIA labels use t('kiso.component_name.key') with entries in config/locales/en.yml.
• Presets — if the component has border-radius, add entries to lib/kiso/presets/rounded.rb and sharp.rb.

Worktree workflow

See .claude/skills/worktree/SKILL.md for the full worktree lifecycle (create, start Lookbook, commit, push, PR, cleanup). Key command: bin/worktree start — starts Lookbook on a deterministic port (4101-4600).