// Kiso component conventions and development workflow. Points to the right docs for building, reviewing, and shipping components.
| name | contributing |
| description | Kiso component conventions and development workflow. Points to the right docs for building, reviewing, and shipping components. |
Guidelines for contributing to the Kiso component library.
| Topic | File |
|---|---|
| Building a component | project/component-creation.md — full workflow, templates, checklist |
| Reviewing a component | project/component-review.md — 12-point checklist, common mistakes |
| Design system rules | project/design-system.md — compound variants, tokens, spatial system |
| Architecture patterns | project/component-strategy.md — ClassVariants, override system |
Per-slot ui: overrides | project/decisions/004-per-slot-ui-prop.md — ADR for ui: prop |
| Testing strategy | project/testing-strategy.md — tier system, E2E requirements |
| Docs page template | project/component-doc-template.md — structure and guidelines |
| All conventions | CLAUDE.md — framework mindset, naming, code rules |
Use bin/rails generate kiso:framework_component name to scaffold the initial files,
then fill in the theme and partial.
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)
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:
@import "tailwindcss";
@import "../builds/tailwind/kiso.css";
@source "../../views";
@source "../../../../test/components/previews";
Always include Closes #N in the PR body so GitHub auto-closes the issue
on merge. This is the most commonly missed step.
# Create branch
git checkout -b feat/{name}-component
# Stage specific files (never git add -A)
git add lib/kiso/themes/{name}.rb app/views/kiso/components/...
# Commit
git commit -m "feat: ComponentName component (#N)"
# Push and create PR
git push -u origin feat/{name}-component
gh pr create --title "feat: ComponentName component" --body "$(cat <<'EOF'
## Summary
- [what was built]
Closes #N
## Test plan
- [x] All Lookbook previews render (200)
- [x] standardrb passes
- [x] rake test passes
- [ ] Visual review in Lookbook
EOF
)"
bin/dev # All services via Foreman (Lookbook :4001 + docs :4000)
bin/dev -m web=1,css=1,docs=0 # Lookbook + Tailwind only (no docs)
bin/worktree start # Start on worktree-assigned port
bin/worktree port # Show port for current worktree
bundle exec rake test # Run Ruby tests
npm run test:unit # Run JS unit tests (Vitest)
npm run test:e2e # Run Playwright E2E tests (needs bin/dev)
npm run test:e2e:ui # Open Playwright GUI
bundle exec standardrb --fix # Lint & auto-format Ruby
npm run lint # Lint JS (oxlint)
npm run fmt # Format JS (oxfmt)
t('kiso.component_name.key') with entries in config/locales/en.yml.border-radius, add entries to
lib/kiso/presets/rounded.rb and sharp.rb.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).
Build UIs with Kiso — accessible Rails UI components with Tailwind CSS theming. Use when creating interfaces, customizing themes, building forms, or composing page layouts in Rails + Hotwire apps.
Audit all documentation for staleness after code changes. Checks docs site, CLAUDE.md, skills references, contributing skill, agents, and project/ files. Use after completing a feature, merging a PR, or when asked to check docs.
Guide through releasing a new version of kiso. Use when cutting a release, publishing a new version, or running bin/release.
Build a Kiso component from scratch. Reads shadcn/Nuxt UI sources, creates theme module, ERB partials, Lookbook previews, docs, E2E tests. Use when building a new component or picking up where a previous attempt left off.
Review a Kiso component for quality and consistency. Runs the 12-point checklist against shadcn source, design system rules, and deliverables. Use on a PR, branch, or working directory.
Agentic Component Factory — build multiple Kiso components in parallel using builder and reviewer agents in isolated worktrees. Usage: /factory #47 #48 or /factory #47 #48 #49 (pass issue numbers)