@tollerud/ui 4.0.3 → 4.0.5

package/AGENTS.md

@@ -39,10 +39,10 @@ npm install @tollerud/footer
 ```css
 /* app/globals.css */
 @import "@tollerud/ui/globals.css";
-@source "../node_modules/@tollerud/ui/dist";
+@import "@tollerud/ui/source.css";
 ```
 
-Adjust `@source` relative to your CSS file. Without it, classes used only inside `@tollerud/ui` dist may be purged.
+`source.css` resolves `@source` inside the installed package (npm, pnpm, workspaces, Bun). Without it, classes used only inside `@tollerud/ui` dist may be purged.
 
 **Optional preset shim** — extra utilities from `@tollerud/ui/preset`:
 

package/CHANGELOG.md

@@ -7,6 +7,55 @@
      • 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.
+
+### Added
+
+- `@tollerud/ui/source.css` — package-owned `@source` for `dist` scanning (npm, pnpm, workspaces, Bun)
+- `test:subpath` now checks all 70 manifest entries (`dist/{name}.js` + `.d.ts`)
+- `test:package` runs attw against every public subpath export
+
+### Changed
+
+- Recommended Tailwind v4 setup: `@import "@tollerud/ui/source.css"` after `globals.css`
+- `GETTING_STARTED.md` — monorepo `@source` path table, footer-only minimal install
+- `tailwind.css` re-exports `source.css` for one-import convenience
+- Docs site getting-started page updated for `source.css`
+
+### Migration
+
+Replace manual `@source "../node_modules/@tollerud/ui/dist"` with:
+
+```css
+@import "@tollerud/ui/globals.css";
+@import "@tollerud/ui/source.css";
+```
+
+---
+
 ## 4.0.3 — 2026-06-09 — Publish pipeline hardening
 
 Patch release: aligns npm publish with `validate`, fixes preset export shape, enables provenance via OIDC, and fixes `@tollerud/footer` CI build.

package/GETTING_STARTED.md

@@ -2,6 +2,10 @@
 
 ## Install
 
+### Full design system
+
+Copy-paste — installs `@tollerud/ui` and all required peers:
+
 ```bash
 npm install @tollerud/ui clsx tailwind-merge tailwindcss@4 \
   @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-progress \
@@ -17,17 +21,64 @@ As of **v2.0.0**, Radix, Lucide, Framer Motion, and Sonner are **required peer d
 npm install @paper-design/shaders-react
 ```
 
+### Footer only (minimal)
+
+If you only need the branded footer — no Tailwind, Radix, or other design-system peers:
+
+```bash
+npm install @tollerud/footer
+```
+
+```tsx
+import { Footer } from '@tollerud/footer'
+
+<Footer />
+```
+
+`@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
+```
+
 ---
 
 ## Tailwind Setup (v4)
 
+**Recommended** — package-owned `@source` (works with npm, pnpm, Yarn workspaces, and Bun):
+
 ```css
 /* app/globals.css */
 @import "@tollerud/ui/globals.css";
+@import "@tollerud/ui/source.css";
+```
+
+`globals.css` bundles Tailwind v4, design tokens, and all component layer styles. `source.css` points Tailwind at the installed package `dist` folder so component utility classes are not purged — no fragile `../node_modules` paths.
+
+### Manual `@source` path (monorepos / custom layouts)
+
+If you prefer an explicit path, resolve it **relative to your CSS file** to `node_modules/@tollerud/ui/dist`:
+
+| Layout | Example CSS file | `@source` path |
+|--------|------------------|----------------|
+| Next.js App Router (default) | `app/globals.css` | `../node_modules/@tollerud/ui/dist` |
+| `src/` app dir | `src/app/globals.css` | `../../node_modules/@tollerud/ui/dist` |
+| Turborepo / npm workspace app | `apps/web/app/globals.css` | `../../../node_modules/@tollerud/ui/dist` |
+| pnpm (package in workspace) | `app/globals.css` | Prefer `@import "@tollerud/ui/source.css"` — hoisting varies |
+| Bun | `app/globals.css` | Prefer `@import "@tollerud/ui/source.css"` |
+
+```css
+@import "@tollerud/ui/globals.css";
 @source "../node_modules/@tollerud/ui/dist";
 ```
 
-`globals.css` bundles Tailwind v4, design tokens, and all component layer styles. Point `@source` at the package `dist` folder relative to your CSS file so component utility classes are not purged.
+If styles disappear in production, the `@source` path is wrong — switch to `@tollerud/ui/source.css` or fix the relative path.
 
 **Optional preset shim** — for extra theme tokens from `@tollerud/ui/preset` (`tollerud-preset.cjs`):
 
@@ -42,7 +93,7 @@ export default { presets: [tollerudPreset] }
 @config "./tailwind.config.ts";
 @import "@tollerud/ui/tokens.css";
 @import "@tollerud/ui/globals-layers.css";
-@source "../node_modules/@tollerud/ui/dist";
+@import "@tollerud/ui/source.css";
 ```
 
 ### Tailwind v3 (legacy)
@@ -94,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
@@ -42,14 +44,14 @@ As of **v2.0.0**, Radix primitives, Lucide, Framer Motion, and Sonner are **peer
 npm install @paper-design/shaders-react
 ```
 
-**CSS** — one import in `app/globals.css` (Tailwind v4 + tokens + component classes):
+**CSS** — two imports in `app/globals.css` (Tailwind v4 + tokens + component class scanning):
 
 ```css
 @import '@tollerud/ui/globals.css';
-@source '../node_modules/@tollerud/ui/dist';
+@import '@tollerud/ui/source.css';
 ```
 
-Adjust the `@source` path relative to your CSS file so it resolves to `node_modules/@tollerud/ui/dist`.
+`source.css` resolves `@source` inside the installed package — works with npm, pnpm, Yarn workspaces, and Bun. See [GETTING_STARTED.md](GETTING_STARTED.md) for manual `@source` paths in monorepos.
 
 **Optional preset shim** — if you need utilities from `@tollerud/ui/preset` beyond what `tokens.css` provides:
 
@@ -64,7 +66,7 @@ export default { presets: [tollerudPreset] }
 @config './tailwind.config.ts';
 @import '@tollerud/ui/tokens.css';
 @import '@tollerud/ui/globals-layers.css';
-@source '../node_modules/@tollerud/ui/dist';
+@import '@tollerud/ui/source.css';
 ```
 
 **Tailwind v3 (legacy)** — preset in `tailwind.config.ts` plus `@tollerud/ui/globals-v3.css`:

package/SKILL.md

@@ -27,7 +27,7 @@ Apply the Tailwind preset when you need extra utilities from `@tollerud/ui/prese
 ```css
 /* app/globals.css — Tailwind v4 (default) */
 @import "@tollerud/ui/globals.css";
-@source "../node_modules/@tollerud/ui/dist";
+@import "@tollerud/ui/source.css";
 ```
 
 As of **v1.4.0**, charts (`BarChart`, `AreaChart`, `Donut`, `Sparkline`) and marketing blocks (`HeroBlock`, `FeatureCard`, `CTABand`) ship in the package. As of **v1.3.0**, `@tollerud/ui/globals.css` is the Tailwind v4 entry. Tailwind colors are under `tollerud.*` only (`text-tollerud-yellow`, `bg-tollerud-surface-raised`, etc.) — not `tia-*`.

package/globals.css

@@ -4,7 +4,7 @@
    Usage in app/globals.css:
 
      @import '@tollerud/ui/globals.css';
-     @source '../node_modules/@tollerud/ui/dist';
+     @import '@tollerud/ui/source.css';
 
    Optional preset shim (extra theme tokens from tollerud-preset.cjs):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollerud/ui",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "Tollerud User Interface — dark, monochrome + yellow accent. Noir aesthetic meets modern utility.",
   "private": false,
   "type": "module",
@@ -32,6 +32,7 @@
     "./globals-v3.css": "./globals-v3.css",
     "./globals-layers.css": "./globals-layers.css",
     "./tailwind.css": "./tailwind.css",
+    "./source.css": "./source.css",
     "./tokens.css": "./tokens.css",
     "./preset": "./tollerud-preset.cjs",
     "./brand/tollerud-logo.svg": "./brand/tollerud-logo.svg",
@@ -52,6 +53,7 @@
     "globals-v3.css",
     "globals-layers.css",
     "tailwind.css",
+    "source.css",
     "tokens.css",
     "tollerud-preset.cjs",
     "GETTING_STARTED.md",

package/source.css

@@ -0,0 +1,12 @@
+/**
+ * Tailwind v4 — scan @tollerud/ui dist for component utility classes.
+ *
+ * Import in app/globals.css after globals.css:
+ *
+ *   @import "@tollerud/ui/globals.css";
+ *   @import "@tollerud/ui/source.css";
+ *
+ * Paths resolve inside the installed package — works with npm, pnpm, Yarn
+ * workspaces, and Bun without fragile ../node_modules relative paths.
+ */
+@source "./dist";

package/tailwind.css

@@ -1,9 +1,6 @@
 /**
  * Convenience entry for Tailwind v4 consumers.
- * Re-exports globals + documents the @source path for class scanning.
+ * Re-exports globals + source scanning in one import.
  */
 @import "./globals.css";
-
-/* In your app globals.css, add after this import:
-@source "../node_modules/@tollerud/ui/dist";
-*/
+@import "./source.css";