insforge-ui

name	insforge-ui
description	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.

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

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.