@tollerud/ui 1.1.2 → 1.1.4

package/AGENTS.md

@@ -394,15 +394,52 @@ npx tsup                                   # verify the bundle builds
 Edit `package.json` version, then update these to match:
 - `COMPLETENESS_ROADMAP.md` — header line `### npm package (components/*.tsx) — vX.X.X`
 - `registry.json` — top-level `"version"` field
+- `ds/app.jsx` — sidebar brand line `user interface · vX.X.X`
 
 ### 4. Always update these files in the same commit
 
-- `CHANGELOG.md` — add an entry at the top following the existing style (date · version · summary + bullet points)
+- `CHANGELOG.md` — add an entry at the top following the **exact format rules below**
 - `COMPLETENESS_ROADMAP.md` — move completed items to the done list, strike through fixed quality items
 - `SKILL.md` — add new components to the catalog, update version notes
 - `AGENTS.md` (this file) — update the component import blocks if new exports were added
 
-### 5. Commit and push
+### 5. CHANGELOG.md format rules
+
+The docs site parses `CHANGELOG.md` at runtime. Wrong formatting causes entries to render as a wall of text or missing content. Follow these rules exactly:
+
+**Entry heading** — always `## version — YYYY-MM-DD — Title`:
+```
+## 1.2.0 — 2026-07-01 — Add DataGrid component
+```
+
+**Blank lines are mandatory** between every distinct block (paragraph, heading, list, code fence). The parser breaks sections at blank lines — without them everything merges into one paragraph.
+
+**Section headings inside an entry** — use `###` or a `**Bold line**` on its own line preceded by a blank line:
+```
+## 1.2.0 — 2026-07-01 — Add DataGrid component
+
+Short summary of what changed.
+
+### New components
+
+- `DataGrid` — sortable, filterable data grid with ...
+
+### Migration
+
+Nothing breaking. Drop-in replacement for `DataTable` where needed.
+```
+
+**Never do this** — bold inline mid-paragraph acting as a heading with no blank line before it:
+```
+## 1.2.0 — bad example
+Summary text. **New components** - DataGrid does X. **Migration** nothing breaking.
+```
+
+**Lists** — standard markdown `- item`. One blank line before the first item if preceded by a paragraph.
+
+**Code blocks** — standard triple-backtick fences. Always close the fence, always a blank line before and after.
+
+### 6. Commit and push
 
 ```bash
 git add <changed files>

package/SKILL.md

@@ -46,7 +46,33 @@ Import base styles/tokens from `@tollerud/ui/globals.css` (or `@tollerud/ui/toke
 `@tollerud/ui` ships as a single bundled file marked `'use client'`. As of **v1.0.8**, importing anything from it — components, hooks, or plain helpers like `buttonVariants` and `cn` — works fine from a Server Component file; the import itself doesn't force your file to become a Client Component, since you're just pulling in already-client-bundled code or plain functions.
 - **If you're on `< 1.0.8`, upgrade first** — older versions crash on any import from a Server Component (the bundle wasn't marked `'use client'`, despite containing hook-based components).
 
-### 2. `<Button>` only renders a native `<button>` — use `asChild` for links (≥ 1.0.7)
+### 2. Tailwind v4 — Alert tone colors missing (`@source` path issue)
+
+`Alert` uses raw Tailwind color classes (`bg-red-500/5`, `border-red-500/30`, `text-red-400`, etc.) for its `error`, `info`, and `success` tones. In Tailwind v4, if your `@source` path doesn't correctly resolve to `node_modules/@tollerud/ui/dist`, these classes are never scanned and the colors silently don't apply.
+
+**Fix (≥ 1.1.4):** `globals.css` now ships these classes in `@layer utilities` so they're always present regardless of your `@source` config. Just make sure you're importing `globals.css`:
+
+```css
+@import "@tollerud/ui/globals.css";
+```
+
+If you're on `< 1.1.4`, add this to your own CSS as a workaround:
+
+```css
+@layer utilities {
+  .bg-red-500\/5   { background-color: rgb(239 68 68 / 0.05); }
+  .bg-blue-500\/5  { background-color: rgb(59 130 246 / 0.05); }
+  .bg-green-500\/5 { background-color: rgb(34 197 94 / 0.05); }
+  .border-red-500\/30   { border-color: rgb(239 68 68 / 0.3); }
+  .border-blue-500\/30  { border-color: rgb(59 130 246 / 0.3); }
+  .border-green-500\/30 { border-color: rgb(34 197 94 / 0.3); }
+  .text-red-400   { color: rgb(248 113 113); }
+  .text-blue-400  { color: rgb(96 165 250); }
+  .text-green-400 { color: rgb(74 222 128); }
+}
+```
+
+### 3. `<Button>` only renders a native `<button>` — use `asChild` for links (≥ 1.0.7)
 `Button` extends `ButtonHTMLAttributes<HTMLButtonElement>` and has no `href`. **Never nest `<a>` inside `<button>` or vice versa** — it's invalid HTML and breaks accessibility. Two ways to style a `<Link>`/`<a>` like a Button:
 
 ```tsx
@@ -71,7 +97,7 @@ import Link from 'next/link'
 
 For a real `<button>` (form submit, logout, toggle, dialog/menu trigger), just use `<Button>` directly — no `asChild` needed.
 
-### 3. `cn` is exported — use it, don't reimplement
+### 4. `cn` is exported — use it, don't reimplement
 `@tollerud/ui` exports `cn` (clsx + tailwind-merge). Use it for conditional/merged class names instead of template strings or writing your own helper.
 
 ---
@@ -450,3 +476,33 @@ Shadow scale: `--shadow-sm` `--shadow-md` `--shadow-lg` `--shadow-xl` `--shadow-
 - **19 new components (`Divider`, `Pill`, `Avatar`/`AvatarGroup`, `Breadcrumb`, `Pagination`, `Segmented`, `Stepper`, `Panel`, `Meter`, `FormRow`, `Accordion`, `Slider`, `PasswordInput`, `Combobox`, `DatePicker`, `FileUpload`, `TagInput`, `PricingCard`) require `>= 1.0.9`**
 - **`Combobox` + `DatePicker` close on window resize (≥ 1.1.0)** — earlier versions left the popover open and misaligned after viewport changes
 - Always pin to the latest patch and check `CHANGELOG.md` in the design-system repo for breaking changes (e.g. the 1.0.5 yellow token rename: `tollerud-yellow-bright` → `tollerud-yellow`, old `tollerud-yellow` `#E8D500` → `tollerud-yellow-warm`)
+
+---
+
+## CHANGELOG.md format rules
+
+The docs site at `design.tollerud.dev` parses `CHANGELOG.md` at runtime. Wrong formatting causes entries to render as a wall of text. Follow these rules whenever you write a changelog entry:
+
+**Entry heading:** `## version — YYYY-MM-DD — Title`
+```
+## 1.2.0 — 2026-07-01 — Add DataGrid component
+```
+
+**Blank lines are required** between every distinct block. The parser splits sections at blank lines — missing blank lines cause everything to merge into one paragraph.
+
+**Section headings inside an entry:** `###` heading or a `**Bold line**` on its own line, preceded by a blank line:
+```
+## 1.2.0 — 2026-07-01 — Add DataGrid component
+
+Short summary.
+
+### New components
+
+- `DataGrid` — sortable, filterable grid ...
+
+### Migration
+
+Nothing breaking.
+```
+
+**Never** write bold inline mid-paragraph as a heading substitute with no blank line before it — it will merge with surrounding text into one unreadable block.