feat: initial @jason/ui-kit — tokens, preset, components, motion, blocks, Impeccable

2026-07-16 00:36:53 -05:00
commit b75012525d
36 changed files with 1324 additions and 0 deletions
@@ -0,0 +1,92 @@
+# @jason/ui-kit
+
+Shared design foundation for all my apps. One brand system, reused everywhere — so
+new apps start polished and existing apps have a clear upgrade path.
+
+Built on the stack I already use (**React + Vite + Tailwind + TypeScript**) and
+guarded by [Impeccable](https://impeccable.style) so nothing ships looking like a
+generic AI-generated template.
+
+## What's inside
+
+- **Design tokens + Tailwind preset** — warm gold/dark brand, radius/shadow/motion scales, CSS-variable theming (dark default, `.light` opt-in), Montserrat / Open Sans / JetBrains Mono.
+- **`cn()`** helper (clsx + tailwind-merge) — the standard everywhere.
+- **Primitives** — Button, Card, Input, Badge, Dialog, DropdownMenu, Table, Toaster (sonner). Radix-backed, accessible, pre-themed.
+- **Motion** — `FadeIn`, `Stagger` (framer/`motion`, reduced-motion aware).
+- **Animated** — `AnimatedNumber` (count-up stats), `SpotlightCard` (cursor glow).
+- **Blocks** — `AppShell` (sidebar + topbar), `CommandPalette` (⌘K), `Hero`, `FeatureGrid`, `Pricing`.
+- **Impeccable** wired in — `DESIGN.md` / `PRODUCT.md` design context, config, and a CI anti-slop detector.
+
+## Install (in a consuming app)
+
+This package publishes to the Gitea npm registry. Add an `.npmrc` (see `.npmrc.example`):
+
+```
+@jason:registry=https://git.alwisp.com/api/packages/jason/npm/
+//git.alwisp.com/api/packages/jason/npm/:_authToken=${GITEA_NPM_TOKEN}
+```
+
+Then:
+
+```bash
+npm install @jason/ui-kit
+```
+
+### Wire up Tailwind
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require("@jason/ui-kit/preset")],
+  content: [
+    "./index.html",
+    "./src/**/*.{ts,tsx}",
+    "./node_modules/@jason/ui-kit/dist/**/*.js", // so kit classes aren't purged
+  ],
+};
+```
+
+```ts
+// app entry (main.tsx)
+import "@jason/ui-kit/styles.css";
+```
+
+### Use it
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, Hero, AnimatedNumber, Toaster, toast } from "@jason/ui-kit";
+
+<Hero
+  eyebrow="New"
+  title="Ship tools that look designed"
+  subtitle="One brand system across every app."
+  primaryCta={{ label: "Get started", href: "/signup" }}
+  secondaryCta={{ label: "Docs", href: "/docs" }}
+/>
+```
+
+## Develop
+
+```bash
+npm install
+npm run dev          # tsup watch build
+npm run typecheck
+npm run design:detect   # run the Impeccable anti-slop detector on src/
+```
+
+## Publish a new version
+
+```bash
+npm version patch      # or minor / major
+npm publish            # builds via prepublishOnly, pushes to Gitea registry
+```
+
+## Extending with 21st.dev
+
+This kit is the base layer. For richer one-off blocks, pull
+[21st.dev](https://21st.dev) components (shadcn-registry compatible) into an app,
+then re-theme them with these tokens and, if broadly useful, promote them into
+`src/blocks/` here. Run `/impeccable polish` on anything new before it ships.
+
+See **DESIGN.md** for the full system spec and **MIGRATION.md** for adopting the
+kit in apps that already exist.