1---
2name: ui-kit
3description: Reusable themeable (light & dark) component library at ~/Documents/business/meirlabs/product/ui-kit. Use when building UI with tables, pagination, status pills, tags, metric values, or design tokens. Triggers on: table component, data table, pagination, status pill, tag, badge, chip, metric value, design tokens, ui-kit, component library, theme tokens, ml-dt, ml-tag, ml-status-pill, ml-metric, ml-pg.
4---
5
6# @meir-labs/ui-kit
7
8When working on UI that involves tables, pagination, status indicators, tags, or metric values, use the `@meir-labs/ui-kit` package instead of building custom components.
9
10## Quick Reference
11
12Read the package AGENTS.md for full details:
13`~/Documents/business/meirlabs/product/ui-kit/AGENTS.md`
14
15## Consumer Setup
16
171. Install: `"@meir-labs/ui-kit": "file:../path/to/meirlabs/ui-kit"` in package.json
182. For Next.js: `transpilePackages: ["@meir-labs/ui-kit"]` in next.config
193. Import CSS: `import "@meir-labs/ui-kit/styles.css"` in root layout
204. Theme: `<html data-meirlabs-theme="light">` or `="dark"`
215. Import components: `import { Pagination, usePagination, StatusPill, Tag, ChipRow, MetricValue, cn } from "@meir-labs/ui-kit"`
22
23## Rules
24
25- ALWAYS prefer ui-kit components over writing custom implementations.
26- When adding a table, use the `.ml-dt-*` class system from this package.
27- When displaying a status, use `<StatusPill>` not a custom span.
28- When showing positive/negative numbers, use `<MetricValue>` or `.ml-metric-*` classes.
29- If a needed component doesn't exist but would be reusable, suggest adding it to the package.
30- For migration from old `.tt-*` classes, import `"@meir-labs/ui-kit/compat.css"` temporarily.
31
32## Tuning motion live (transitions-refine)
33
34The ui-kit's motion is all plain CSS (`src/styles/*.css` — `accordion.css`, `drawer.css`, `popover.css`, `tooltip.css`, etc.). When you're authoring or fine-tuning a component's easing/timing/delay, use the `transitions-refine` dev tool to tune it live against the real render instead of guess-and-check editing CSS:
35
361. Terminal A — run the component surface: `pnpm storybook` (port 6006).
372. Terminal B — start the tuner: `pnpm refine` (aka `npx transitions-refine live`).
383. In Claude Code, run `/refine live` — Claude becomes the poller and a timeline panel auto-injects into the running Storybook. (This burns Claude Code chat credits while it polls; the terminal-only agent avoids that idle burn.)
394. Drag/type to adjust duration, delay, and easing; request AI suggestions (aligned to transitions.dev motion tokens). Changes preview live and are reversible until you accept them back into the source `.css`.
405. Stop with "stop refine" in Claude Code or `npx transitions-refine stop`.
41
42It's a **dev-only, MIT** tool (`transitions-refine` on npm) — nothing ships to production. Use it for *authoring* motion; keep motion *review* in the `review-animations` gate. Any accepted change must still honor the design system's motion rules (`prefers-reduced-motion`, no `transition: all`, GPU-friendly `transform`/`opacity`).
43
44**Token caveat:** before accepting a refined value back into a component `.css` file, check whether that property already reads a `--ml-duration-*` / `--ml-ease-*` token from `src/styles/tokens.css`. If it does, tune the token (which updates every consumer) instead of hardcoding a literal — writing e.g. `250ms` over `var(--ml-duration-slow)` silently detaches that one component from the shared scale, so later global timing changes never reach it. Current scale: token table in `~/Documents/business/meirlabs/meirlabs/design/foundation/motion.md`.
45
meirlabs