# Insforge UI

> Use this skill when working in the InsForge/UI repository, which publishes @insforge/ui, the React primitives, design tokens, and Tailwind preset shared by InsForge apps. Covers package layout, working rules, validation, and where the release process lives.

- Skill: `insforge/insforge-ui` (Agent Skill)
- Install (CLI): `npx skillmds@latest add insforge/insforge-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/insforge/insforge-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: insforge (https://skillmd.com/u/insforge)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/insforge/insforge-ui

---


# InsForge UI

`@insforge/ui` is published to npm from this repository. Its main consumers are `packages/dashboard` in the InsForge monorepo (https://github.com/InsForge/InsForge) and the insforge-cloud app; both pin a version range and only see a change after a release.

Use the `release` child skill (`release/SKILL.md`) to publish a version or to diagnose a failed publish.

## Layout

- `src/components/**` — one file per primitive, Radix wrappers with typed exports
- `src/lib/**` — helpers such as `cn()`
- `src/index.ts` — the public surface; every public component is re-exported here
- `src/styles.css` — token layers, copied verbatim to `dist/styles.css` on build
- `tailwind-preset.js` — maps the tokens to Tailwind theme colors

## Working Rules

1. Only reusable primitives belong here. Anything tied to one dashboard workflow stays in the monorepo's `packages/dashboard`.
2. Use `class-variance-authority` for variants and `cn()` for class merging. Follow the existing Radix-wrapper pattern.
3. Export new public components from `src/index.ts`. Do not widen the surface with internal-only abstractions.
4. Never use the TypeScript `any` type. Keep props and exported helpers strictly typed.
5. Tests live next to the code: `*.test.ts` run in node (unit), `*.test.tsx` run in jsdom (component).
6. Relative imports carry an explicit extension (`./Button.js`, `./components/index.js`). `tsc` emits specifiers verbatim and Node ESM rejects extensionless or directory imports, so an extensionless import breaks every non-bundler consumer.
7. `src/styles.css` declares `@source './'` so a consumer's Tailwind scans this package's built files. Keep it: without it the utilities used inside the components are never generated in the consumer's CSS.

## Landing Changes

`main` is protected the same way as the other InsForge repositories: no direct pushes, every change arrives through a pull request with one approval and a green `CI` run. Force pushes and branch deletion are blocked, admins included.

## Validation

```bash
npm run lint
npm run typecheck
npm test
npm run build
```

Consumers only see published output, so after a behavior change also check the dashboard in the InsForge monorepo against the built package (`npm pack` here, install the tarball there) before releasing.

## Skill Maintenance

`.agents/skills/insforge-ui/` is the canonical copy. `.claude/skills/` and `.codex/skills/` are generated mirrors: edit the canonical tree, run `scripts/sync-skills.sh`, and commit all three. CI fails on drift.