@4sh/ui Kit

Angular Starter

Angular 22 starter (standalone, signals, zoneless) for building a fully in-house design system, with no dependency on a proprietary UI library. Headless components (Angular CDK + native signals) styled exclusively through design tokens.

This is the Starter Angular side of the Dual-Engine strategy:

• The logic depends on the stack: Angular CDK here (Radix UI on the React side).
• The layer shared across stacks = the design tokens (CSS variables).
• The component styling is co-located (Angular scoped .scss) and consumes these tokens.

This repo holds the @4sh/ui-kit package (54 ui-* components on 53 entry points, plus 5 cross-cutting ones) and the demo application that consumes it.

Both sites are redeployed on every push to main (deploy-pages.yml).

This page is for whoever works on the design system itself — adding a ui-* component, editing the tokens, cutting a release. To use the kit in an application you do not need this repo: everything is in the README shipped with the package, projects/ui-kit/README.md · Français.

Stack

Stylesheets are SCSS (Sass), not the plain CSS Angular scaffolds by default. schematics.@schematics/angular:component.style is set to scss in angular.json, and every component ships a .scss file — never .css. ng generate component in this repo therefore already generates the right extension; do not switch it back to css.

Using the kit in an application

The kit is published on the public npm registry, in one of two modes:

pnpm add @4sh/ui-kit            # dependency — compiled components, updated by version bump
ng add @4sh/ui-kit-schematics   # starter — component sources copied into your project, yours to edit

Which one to pick, the entry points, the stylesheet to load, the required providers, building your own field: projects/ui-kit/README.md · Français — documented once, and that page is the npmjs one. Each component's API is in the Storybook.

Working in this repo

Node v24.15.0 (.nvmrc). Four commands cover the work itself:

pnpm install       # install + postinstall: tokens:build, ui-kit:build, docs:config
pnpm start         # Storybook          → http://localhost:6006
pnpm serve         # demo application   → http://localhost:4200
pnpm tokens:build  # regenerate the token CSS variables

Under IntelliJ, a pnpm start run configuration ships with the repo (.idea/runConfigurations/).

pnpm start, pnpm serve and the builds all run ui-kit:build first: the demo app consumes the kit through its built output (dist/ui-kit, mapped by the @4sh/ui-kit/* paths of tsconfig.json), exactly like an external consumer would.

projects/ui-kit/styles/generated/ and storybook/generated/ are generated (gitignored), rebuilt by tokens:build and docs:config.

Verifying

pr-checks.yml runs lint, types, unit tests, the doc guardrail and a Storybook build on every pull request — you do not have to replay them locally. Two are worth the detour anyway, because they save a round-trip:

pnpm lint               # ESLint --fix — repairs instead of reporting
pnpm docs:config:check  # the hand-written doc vs the code

docs:config:check is the guardrail on everything this repo states by hand: six places claim to describe projects/ui-kit/, and nothing in the code forces them to follow when a component lands. Full list of what it rejects: AGENTS.md.

Contributing

Conventions to follow before writing code — repo layout, naming, CSS/SCSS rules (no BEM), component creation recipe, Storybook file organization, token workflow — are all in AGENTS.md. It is the single source of truth for them, for humans as much as for AI agents.

Details: .claude/rules/git-conventions.md for git, docs/VERSIONING.md for the release flow.

Releasing a new version

Once all your changes are on main (⚠️ never push directly to main), here's how to publish a new version of the @4sh/ui-kit and @4sh/ui-kit-schematics npm packages (same version, same job).

1. Prepare the release, on main: move [Unreleased] to a new [X.Y.Z] - YYYY-MM-DD section in CHANGELOG.md, bump the version in projects/ui-kit/package.json, commit.
2. Publish: Actions → Publish @4sh/ui-kit to npm → Run workflow with dry_run: true first, then dry_run: false — this waits for reviewer approval on the npm-publish environment before actually publishing.
3. Tag & release: created by the CI after a successful publish — never tag or release by hand.

Full detail: docs/VERSIONING.md (when to bump what) · docs/PUBLISHING.md (full publish workflow, npm auth).

Going further