@tollerud/ui 4.0.4 → 4.0.5

package/CHANGELOG.md

@@ -7,6 +7,27 @@
      • Never write bold mid-paragraph as a heading substitute — it merges into surrounding text
 -->
 
+## 4.0.5 — 2026-06-10 — Starter template and DX docs
+
+Patch release: human-facing Next.js starter, migration guide, and footer package tooling alignment. No breaking API changes.
+
+### Added
+
+- `examples/next-starter/` — copy-paste Next.js 16 + Tailwind v4 reference app (`source.css`, `Toaster`, sample page)
+- `GETTING_STARTED.md` — “Migrating from copied components” section (grep recipe, prop drift checklist, link to `SKILL.md`)
+
+### Changed
+
+- `@tollerud/footer` — TypeScript 6.x in devDependencies; `sync-footer-package.mjs` preserves `tsup.config.ts` build and `publishConfig`
+- `GETTING_STARTED.md` / `README.md` — footer self-contained dependency model documented; starter template linked
+- `packages/footer/tsconfig.json` — `ignoreDeprecations: "6.0"` for DTS emit under TS 6
+
+### Migration
+
+Nothing breaking. New apps can copy `examples/next-starter/` instead of wiring from scratch.
+
+---
+
 ## 4.0.4 — 2026-06-10 — Export verification and source.css
 
 Patch release: verifies all subpath exports in CI, adds package-owned Tailwind scanning, and expands install docs.

package/GETTING_STARTED.md

@@ -35,7 +35,17 @@ import { Footer } from '@tollerud/footer'
 <Footer />
 ```
 
-`@tollerud/footer` bundles `clsx` and `tailwind-merge` as dependencies. Use `@tollerud/ui` when you need the full component set.
+`@tollerud/footer` is **self-contained by design** — it bundles `clsx` and `tailwind-merge` so footer-only apps avoid extra peer installs. You still need Tailwind with Tollerud tokens (`@tollerud/ui/globals.css` or equivalent) for `text-tollerud-*` / `bg-tollerud-*` classes to resolve.
+
+Use `@tollerud/ui` (or `@tollerud/ui/footer`) when you need the full component set. Apps using both packages may install duplicate `clsx` / `tailwind-merge` versions — harmless in practice; npm dedupes when ranges align.
+
+### Next.js starter
+
+Copy [`examples/next-starter/`](../examples/next-starter/) from this repo — minimal App Router app with `globals.css`, `source.css`, sample page, and `Toaster` mounted.
+
+```bash
+cp -R examples/next-starter my-app && cd my-app && npm install && npm run dev
+```
 
 ---
 
@@ -135,6 +145,37 @@ Use subpath imports (`@tollerud/ui/button`) for smaller client boundaries when s
 
 ---
 
+## Migrating from copied components
+
+Older projects sometimes copied `Button.tsx`, `lib/utils.ts`, or whole `components/ui/` trees from this design system. Replace them with package imports.
+
+### Detect copied files
+
+```bash
+grep -rl "tollerud-yellow\|tollerud-noir\|tollerud-surface" src --include="*.tsx" --include="*.ts"
+```
+
+Also look for `components/ui/index.ts` re-exporting relative paths instead of `@tollerud/ui`.
+
+### Fix checklist
+
+1. Install the package and peers (see [Install](#install) above).
+2. Replace local imports — `import { Button } from '@/components/ui/Button'` → `import { Button } from '@tollerud/ui'` (or `@tollerud/ui/button`).
+3. Replace hand-rolled `cn()` — `import { cn } from '@tollerud/ui'` or `@tollerud/ui/utils`.
+4. Delete copied files after imports compile.
+5. Check **prop drift** against [SKILL.md](SKILL.md) — copied files may use outdated prop names (`onChange` vs `onValueChange`, etc.).
+6. Replace hardcoded hex (`#FFFF00`, `#0A0A0A`) with tokens (`text-tollerud-yellow`, `bg-tollerud-noir-950`).
+7. Add `<Toaster />` near the app root if you use Sonner toasts.
+8. Run `npx tsc --noEmit` and fix type errors from signature changes.
+
+| Copied pattern | Fix |
+|----------------|-----|
+| `src/components/ui/Button.tsx` | Delete; import from `@tollerud/ui` |
+| Local `lib/utils.ts` with `cn()` | Delete; `import { cn } from '@tollerud/ui/utils'` |
+| `components/ui.ts` re-exporting relatives | Direct `@tollerud/ui` imports |
+
+---
+
 ## AI agents
 
 If you're using Claude Code or Cursor, sync [SKILL.md](SKILL.md) into your project skills folder — it reflects the actual current exports and known gotchas.

package/README.md

@@ -15,7 +15,7 @@ A complete, browsable UI library built around **monochrome + yellow accent**. No
 | [`@tollerud/ui`](https://www.npmjs.com/package/@tollerud/ui) | `npm install @tollerud/ui` | You want the full design system — components, tokens, Tailwind preset |
 | [`@tollerud/footer`](https://www.npmjs.com/package/@tollerud/footer) | `npm install @tollerud/footer` | You only need the branded footer, with no other design system dependency |
 
-**Footer maintenance:** `@tollerud/ui` re-exports `Footer` from the same source as `@tollerud/footer`. Use the standalone `@tollerud/footer` package only when you want the footer without pulling in the full design system (and its peer deps). Both packages are maintained in this monorepo; version them together when the footer changes.
+**Footer maintenance:** `@tollerud/ui` exports `Footer` from the same source as `@tollerud/footer` (`npm run sync:footer` keeps them lockstep). Use the standalone package when you want the branded footer without Radix, Lucide, Framer Motion, Sonner, or other `@tollerud/ui` peers — `@tollerud/footer` bundles `clsx` and `tailwind-merge` as dependencies **on purpose** for that path. You still need Tailwind + Tollerud tokens for footer styles. Deprecation of `@tollerud/footer` is not planned for now.
 
 ## Philosophy
 
@@ -25,6 +25,8 @@ Tollerud UI is minimal but not cold. It uses a near-black foundation with warm y
 
 ## Quick Start
 
+**Starter template:** [`examples/next-starter/`](examples/next-starter/) — copy into a new project, `npm install`, `npm run dev`. See [GETTING_STARTED.md](GETTING_STARTED.md) for the full guide and migration from copied components.
+
 ### npm package (recommended)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollerud/ui",
-  "version": "4.0.4",
+  "version": "4.0.5",
   "description": "Tollerud User Interface — dark, monochrome + yellow accent. Noir aesthetic meets modern utility.",
   "private": false,
   "type": "module",