This guide holds the commands and the rules for working in the Kelvin UI Components monorepo. Step-by-step procedures are skills, and reference material is in docs/:
design-tokensskill — the token pipeline, naming, using tokens in component SCSS, legacy helpers to replacetokens-syncskill — regenerate the token JSON files from the Figma variables table via the Figma MCP, no plugin run neededreact-testsskill — the React package's Vitest projects, Stencil mocks, browser-test helpers and where tests liveprimitives-and-schema-formskill — rules for changing components others render, focus and accessible names, built-in labels, and SchemaForm- Package map — public entries, catalog links and internal workspace responsibilities
- Component patterns — read before creating, changing or reviewing Stencil structure, naming, exports or stories
- docs/architecture.md — packages and build outputs, StencilJS concepts, configuration files, key directories, versioning and deployment
- docs/troubleshooting.md — fixes for module-not-found, Storybook, type, test and pnpm problems
The skills live in .agents/skills/, linked from .claude/skills/ and .codex/skills/, so Claude Code and Codex both find them.
The frontend-plugins plugin from the Kelvin marketplace adds two React skills from Vercel: vercel-react-best-practices for performance work in react-ui-components, and vercel-composition-patterns for component APIs. Skip the composition skill's React 19 section (react19-no-forwardref) while react-ui-components still supports React 18. .claude/settings.json turns the plugin on for Claude Code; in Codex, run codex plugin marketplace add kelvininc/agents, then codex plugin add frontend-plugins@kelvin-plugins-official.
Before choosing or changing a shared control, read API discovery. Build Stencil metadata, then run pnpm docs:generate; never hand-edit API.md or manifest.json.
Before implementing, refactoring or reviewing authored React code, use frontend-plugins:react-code-quality and read React compatibility. The shared package must support React 18.3.1 even when Storybook uses React 19. Look up library APIs in Context7 at the supported consumer version and verify the returned source version.
Before adding or changing named code units, read code quality and documentation.
Repository: Kelvin UI Components (public) Type: Monorepo (Lerna + pnpm workspaces) Purpose: Framework-agnostic UI component library built with StencilJS, with React bindings Public Storybook: https://kelvininc.github.io/ui-components/
packages/ui-components/—@kelvininc/ui-components, the core StencilJS web componentspackages/react-ui-components/—@kelvininc/react-ui-components, React bindings generated from the core components, withclient,serverandsharedentry pointsapps/react-storybook/— the Storybook documentation app (private)
- Node.js: >= 24 (specified in engines)
- pnpm: v10.33.4 (exact version, specified in packageManager)
pnpm install # Install dependencies (pnpm workspace)
pnpm build:packages # Build all packages (before apps)
pnpm build # Build the entire monorepo
pnpm storybook # Run Storybook on http://localhost:6006
pnpm build:apps # Build the Storybook app only
pnpm test:unit # Core and React unit tests (build packages first)
pnpm lint # Lint all packages
pnpm lint:fix # Fix linting issues
pnpm clean # Clean everything (also clean:packages, clean:apps)Package-specific:
cd packages/ui-components && pnpm build # also: pnpm test, pnpm test:watch, pnpm test -- kv-button, pnpm lint
cd packages/ui-components && pnpm tokens:build # after any change under tokens/
cd packages/ui-components && pnpm typecheck # after a build, which generates src/components.d.ts
cd packages/react-ui-components && pnpm build # also: pnpm build:watch, pnpm test, pnpm test:browser (react-tests skill)
cd apps/react-storybook && pnpm dev # also: pnpm build- Styling uses design tokens, preferring component semantic tokens, then semantic tokens, then core primitives. The legacy
kv-color(),@include kv-font-*and$spacing-*helpers still compile but are being phased out. Follow thedesign-tokensskill. - Storybook MCP.
pnpm storybookalso serves an MCP server athttp://localhost:6006/mcp, which.mcp.json(Claude Code) and.codex/config.toml(Codex) register asstorybook. Start Storybook before a task that needs it; while it is stopped, the server shows as failed. Its props come from the built packages' types, so runpnpm build:packagesfirst. - Patches:
patches/holds the pnpm patch for@pxtrn/storybook-addon-docs-stencil@8.0.0. Don't delete it: install needs it. - Post-install: React components copy icon assets in a post-install script; Storybook runs it with
CUSTOM_INST=true. - Versions are exact between packages (no semver ranges) and use
workspace:*internally.
- PRs target
dev;masteris the release branch. - Releases derive the version from the latest
vX.Y.Ztag. No version or changelog commit is pushed tomaster, so the manifests in git aren't the source of truth. Details: docs/architecture.md.
This project follows the Conventional Commits specification. All commits are validated by commitlint.
Format: <type>(<scope>): <subject>
Common Types:
feat- New features or enhancementsfix- Bug fixesdocs- Documentation changeschore- Maintenance tasks (releases, dependencies)refactor- Code refactoring without feature changesperf- Performance improvementstest- Test additions or updatesstyle- Code style/formatting changesbuild- Build system changesci- CI/CD changesrevert- Revert previous commits
Scope (optional but recommended):
- Component name (e.g.,
badge,dropdown,text-field) - Area of change (e.g.,
icons,storybook,schema-form) - Omit scope for global changes
Breaking Changes:
- Use
!after type/scope or addBREAKING CHANGE:in commit body - Example:
refactor(icon)!: remove legacy icons
Optional Elements:
- Issue reference:
[KFE-2506]at the end of subject - Skip CI:
[skip ci]for the pre-release version commits onalpha/beta
Commit Body (optional):
- Add detailed description after a blank line
- Explain what changed and why
- List breaking changes with
BREAKING CHANGE:prefix