Menu
Kiso component conventions and development workflow. Points to the right docs for building, reviewing, and shipping components.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
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)
| 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).