Skip to content

Latest commit

 

History

History
148 lines (119 loc) · 5.95 KB

architecture.md

File metadata and controls

148 lines (119 loc) · 5.95 KB

Architecture

Reference for how the monorepo is put together. The root AGENTS.md holds the commands and the rules.

Monorepo structure

ui-components/
├── packages/
│   ├── ui-components/           # Core StencilJS web components
│   └── react-ui-components/     # React bindings (auto-generated)
└── apps/
    └── react-storybook/         # Storybook documentation app

Key technologies

  • 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)

Packages

Core Package (@kelvininc/ui-components)

  • 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/)

React Package (@kelvininc/react-ui-components)

  • 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'

Storybook App (@kelvininc/react-storybook)

  • Source: apps/react-storybook/
  • Private package (not published)
  • Uses custom Stencil addon: @pxtrn/storybook-addon-docs-stencil (patched)

StencilJS components

Key Concepts:

  • Shadow DOM: All components use shadow: true for style encapsulation
  • Host Element: Use :host selector 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: light and night (dark)
  • Theme is set via mode attribute 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 styleUrls in component decorator

Global Configuration:

  • Initialize via initialize() function from package
  • Set base assets URL for icons and symbols
  • Configuration stored in window.KvUiComponents.config

Configuration files

Root Level

  • lerna.json - Lerna configuration (version management, publish settings)
  • pnpm-workspace.yaml - Workspace package definitions
  • package.json - Root scripts and shared devDependencies
  • commitlint.config.js - Conventional commit enforcement

Core Package (packages/ui-components/)

  • stencil.config.ts - StencilJS configuration
    • Output targets (dist, custom-elements, React output)
    • Testing configuration
    • SASS plugin
  • tsconfig.json - TypeScript configuration

React Package (packages/react-ui-components/)

  • rollup.config.js - Rollup bundler configuration
  • tsconfig.json - TypeScript configuration

Storybook (apps/react-storybook/)

  • .storybook/ directory - Storybook configuration
  • project.json - Nx project configuration (if using Nx)

Key directories

Source Code

  • packages/ui-components/src/components/ - Core component implementations
  • packages/ui-components/src/types.ts - Shared TypeScript types (per-component types live in [component-name].types.ts)
  • packages/ui-components/src/utils/ - Utility functions
  • packages/react-ui-components/src/stencil-generated/ - React bindings, generated by the core build (gitignored)
  • apps/react-storybook/src/components/ - Storybook stories

Build Outputs

  • packages/ui-components/dist/ - Built core components
  • packages/ui-components/components/ - Custom elements build
  • packages/ui-components/loader/ - Lazy loading utilities
  • packages/react-ui-components/dist/ - Built React components
  • apps/react-storybook/storybook-static/ - Built Storybook

Documentation

  • packages/ui-components/src/components/*/readme.md - Component-specific docs

Versioning

  • 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.Z tag at release time; no version or changelog commit is pushed to master, so the manifests in git are not the source of truth
  • Release notes are generated from commit messages on each GitHub Release

Deployment

Storybook Deployment

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

Package Publishing

  • Packages are published to npm with @kelvininc scope
  • 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