Reference for how the monorepo is put together. The root AGENTS.md holds the commands and the rules.
ui-components/
├── packages/
│ ├── ui-components/ # Core StencilJS web components
│ └── react-ui-components/ # React bindings (auto-generated)
└── apps/
└── react-storybook/ # Storybook documentation app
- Core: StencilJS (web components compiler)
- Testing: Core: Stencil spec (Jest) + Puppeteer e2e. React: Vitest, with jsdom unit tests and browser tests on Playwright Chromium
- Styling: SASS
- Design Tokens: Style Dictionary v5 + Tokens Studio transforms
- Build: Rollup (for React), Stencil CLI (for core)
- Monorepo: Lerna v9 + pnpm workspaces
- Documentation: Storybook v10 (webpack5 builder)
- Commit Conventions: Conventional Commits (with commitlint)
- Source:
packages/ui-components/ - Build outputs:
- ESM (
dist/esm/) - CJS (
dist/cjs/) - Custom Elements (
components/) - TypeScript types (
dist/types/) - Loader (
loader/) - Collection manifest (
dist/collection/)
- ESM (
- Source:
packages/react-ui-components/ - Auto-generated from core components via Stencil React Output Target
- Proxies file:
src/stencil-generated/index.ts - Builds with Rollup
- Multiple entry points for different environments:
client- Client-side rendering (CSR)server- Server-side rendering (SSR)shared- Shared utilities- Import example:
import { KvBadge } from '@kelvininc/react-ui-components/client'
- Source:
apps/react-storybook/ - Private package (not published)
- Uses custom Stencil addon:
@pxtrn/storybook-addon-docs-stencil(patched)
Key Concepts:
- Shadow DOM: All components use
shadow: truefor style encapsulation - Host Element: Use
:hostselector in SCSS to style the component's host element - Slots: Support content projection using
<slot />elements - Props: Use
@Prop()decorator for component properties - Events: Use
@Event()decorator to emit custom events - Methods: Use
@Method()decorator to expose public methods - State: Use
@State()decorator for internal component state
Theme System:
- Components support dual themes:
lightandnight(dark) - Theme is set via
modeattribute on<body>:<body mode="light">or<body mode="night"> - CSS custom properties cascade:
:root(core primitives) →body[mode](semantic) → component styles - Theming is handled entirely through design tokens — no per-theme SCSS files needed
- Configure via
styleUrlsin component decorator
Global Configuration:
- Initialize via
initialize()function from package - Set base assets URL for icons and symbols
- Configuration stored in
window.KvUiComponents.config
lerna.json- Lerna configuration (version management, publish settings)pnpm-workspace.yaml- Workspace package definitionspackage.json- Root scripts and shared devDependenciescommitlint.config.js- Conventional commit enforcement
stencil.config.ts- StencilJS configuration- Output targets (dist, custom-elements, React output)
- Testing configuration
- SASS plugin
tsconfig.json- TypeScript configuration
rollup.config.js- Rollup bundler configurationtsconfig.json- TypeScript configuration
.storybook/directory - Storybook configurationproject.json- Nx project configuration (if using Nx)
packages/ui-components/src/components/- Core component implementationspackages/ui-components/src/types.ts- Shared TypeScript types (per-component types live in[component-name].types.ts)packages/ui-components/src/utils/- Utility functionspackages/react-ui-components/src/stencil-generated/- React bindings, generated by the core build (gitignored)apps/react-storybook/src/components/- Storybook stories
packages/ui-components/dist/- Built core componentspackages/ui-components/components/- Custom elements buildpackages/ui-components/loader/- Lazy loading utilitiespackages/react-ui-components/dist/- Built React componentsapps/react-storybook/storybook-static/- Built Storybook
packages/ui-components/src/components/*/readme.md- Component-specific docs
- Managed by Lerna
- Uses conventional commits to determine version bumps:
feat:→ Minor version bump (0.x.0)fix:→ Patch version bump (0.0.x)BREAKING CHANGE→ Major version bump (x.0.0)
- The version is derived from the latest
vX.Y.Ztag at release time; no version or changelog commit is pushed tomaster, so the manifests in git are not the source of truth - Release notes are generated from commit messages on each GitHub Release
The storybook job in publish-dev.yml and publish-master.yml deploys both storybooks to GitHub Pages after every push to dev or master: master at the root, dev under /alpha. See .github/workflows/README.md.
# Build without deploying. Flags go after exactly one `--`
pnpm storybook:deploy -- --out=./gp --dry-run
# Build and deploy: replaces the whole site, /alpha included, with this branch's storybook
pnpm storybook:deploy- Packages are published to npm with
@kelvinincscope - Public access (specified in publishConfig)
- Managed via Lerna publish workflow
- Uses OIDC trusted publishing (no npm tokens required)
- CI workflow:
.github/workflows/publish-master.yml