@heyramzi/ui 2.0.1 → 2.2.0

package/src/tokens/craft.css

@@ -1,8 +1,6 @@
 /* ── Radius, by role not by size ─────────────────────────────
-   A chip inside a control inside a card has to read as nested, which needs
-   three radii that step, not one radius reused. The Tailwind names are the
-   home so `rounded-lg` on a button already resolves to the control radius and
-   no component has to learn a new class. */
+   These override Tailwind's own names, so `rounded-lg` on a button already
+   resolves to the control radius. */
 @theme {
   --radius-xs: 4px; /* tag, dot, inline code */
   --radius-sm: 6px; /* chip, badge, small pill */
@@ -14,30 +12,9 @@
 }
 
 /* ── Elevation ───────────────────────────────────────────────
-   Four steps of lift, plus the two edges that are not lift.
-
-   WHY the steps are shadow-only and the hairline is its own token: most boxes
-   in a kit already draw a border, and an elevation that bakes a `0 0 0 1px`
-   ring into every step gives those boxes two edges a pixel apart. Compose them
-   where a component drops its border:
-
-     box-shadow: var(--elev-hairline), var(--elev-card);
-
-   WHY each step is stacked rather than one blurred drop: a single shadow reads
-   as a sticker. Depth is several offsets falling off together, which is what
-   the eye reads as distance. They cost nothing extra because every stop is the
-   same colour at a different alpha.
-
-   WHY the blur radii are large and the alphas small: a 4px blur at 20% draws a
-   visible grey edge, which the eye reads as a second border. A 28px blur at 7%
-   is barely a colour anywhere and reads as height. Reach for more blur before
-   more alpha, every time.
-
-   `--elev-tint` is the one knob an app turns. Pure black greys a warm palette
-   out; the hue of the app's own darkest surface keeps the shadow in the
-   family. */
+   The steps carry no ring, since a bordered box would get two edges a pixel
+   apart; a borderless one adds `var(--elev-hairline)` in front. */
 :root {
-
   /* Resting on the page. A button, a chip, a row. */
   --elev-btn:
     0 1px 1px -0.5px color-mix(in oklab, var(--elev-tint) 7%, transparent),
@@ -61,9 +38,8 @@
     0 12px 26px -8px color-mix(in oklab, var(--elev-tint) 12%, transparent),
     0 40px 72px -20px color-mix(in oklab, var(--elev-tint) 20%, transparent);
 
-  /* The two edges. A hairline separates a surface from what is behind it; a rim
-     is the light catching its top edge, which is what makes a filled control
-     read as a physical key rather than a coloured rectangle. */
+  /* A hairline separates a surface from what's behind it; a rim is light on the
+     top edge, which makes a filled control read as a key. */
   --elev-hairline: 0 0 0 1px var(--color-border, var(--border));
   --elev-rim: inset 0 1px 0 color-mix(in oklab, white 16%, transparent);
 
@@ -71,10 +47,8 @@
   --elev-field: inset 0 1px 2px color-mix(in oklab, var(--elev-tint) 7%, transparent);
 }
 
-/* A dark surface cannot cast a darker shadow than the page it sits on, so the
-   hairline does the separating and the shadow only sinks what is behind it. On
-   dark the hairline is white at a low alpha, which is what reads as a lit edge
-   rather than as a drawn border. */
+/* A shadow can't get darker than a dark page, so on dark the low-alpha white
+   hairline does the separating. */
 .dark {
   --elev-btn: 0 1px 2px color-mix(in oklab, black 30%, transparent);
   --elev-card:
@@ -93,25 +67,19 @@
 }
 
 /* ── Focus ───────────────────────────────────────────────────
-   One ring, two parts: a solid edge that redraws the control's own outline in
-   the accent, and a soft halo that carries it off the surface. Written as a
-   variable so a component spends one line on it and every control focuses the
-   same way. */
+   One variable, so every control focuses the same way: a solid accent edge,
+   then a soft halo. */
 :root {
   --ring-color: var(--color-ring, var(--ring));
   --ring-halo: color-mix(in oklab, var(--ring-color) 16%, transparent);
-  /* A solid pixel redrawing the control's own edge, then a wide soft band. At a
-     higher alpha the band reads as a second border rather than as a glow, which
-     is why it is 16% over 4px and not 30% over 2px. */
+  /* The halo is 16% over 4px, not 30% over 2px, because a stronger band reads
+     as a second border instead of a glow. */
   --ring-focus: 0 0 0 1px var(--ring-color), 0 0 0 5px var(--ring-halo);
 }
 
 /* ── Motion ──────────────────────────────────────────────────
-   The transitions-dev scale, verbatim, so a snippet pasted from that skill and
-   a component written here read from the same names.
-
-   The doctrine in one line: an open is an invitation and a close should get out
-   of the way, so every close is shorter than its open and no close bounces. */
+   The transitions-dev scale, verbatim, so a pasted snippet reads the same
+   names. Every close is shorter than its open, and no close bounces. */
 :root {
   --duration-stagger: 40ms;
   --duration-micro: 80ms;
@@ -163,13 +131,9 @@
 
   --ease-smooth-out: var(--ease-smooth-out);
 
-  /* WHY the durations are re-declared under a second name: Tailwind's
-     `duration-*` utility reads `--transition-duration-*`, not `--duration-*`, so
-     the six names above generated no class at all. `duration-fast` therefore
-     compiled to nothing and the element ended up at `transition-duration: 0s`:
-     no error, no warning, and a component that simply does not animate. The
-     comment at the top of this block had claimed `duration-fast` was a class
-     since the block was written. Found 31 Aug 2026 by probing a live page. */
+  /* Tailwind's `duration-*` reads `--transition-duration-*`, so without these
+     `duration-fast` silently compiles to nothing and the element doesn't animate
+     (31 Aug 2026). */
   --transition-duration-micro: var(--duration-micro);
   --transition-duration-quick: var(--duration-quick);
   --transition-duration-fast: var(--duration-fast);

package/src/tokens/index.css

@@ -1,16 +1,6 @@
-/* tokens.css
- *
- * The shared style layer for @heyramzi/ui, imported once after Tailwind:
- *
- *   @import "tailwindcss";
- *   @import "@heyramzi/ui/tokens.css";
- *   @import "@heyramzi/ui/animations";
- *   @import "@heyramzi/ui/shadcn/utilities.css"; // only if you use Attachment or Message
- *
- * It carries three things: the color palette and semantic tokens, the craft
- * layer (radius, elevation, focus and motion), and the small set of motion
- * primitives the components share. Override any variable on :root to retheme.
- * The parts load in this order because later blocks read earlier variables.
+/* tokens.css: import once, right after `@import "tailwindcss"`. Override any
+ * variable on :root to retheme; the parts load in this order because later ones
+ * read earlier variables.
  */
 
 @import "./palette.css";

package/src/tokens/palette.css

@@ -22,9 +22,8 @@
   --gray-900: oklch(0.15 0 0); /* Near-black — headings, primary text */
 
   /* === Brand roles ===
-     The look of a product, named by what each colour does. These defaults are neutral, and a
-     brand replaces them through `@heyramzi/ui/brand` (typed colours, no build step). Every
-     other token below reads from these, so nothing else in the package names a hue. */
+     Neutral defaults a brand replaces through `@heyramzi/ui/brand`; every token below reads
+     from these, so nothing else in the package names a hue. */
   --brand: oklch(0.28 0 0); /* The signature colour: focus ring, links, active states, the mark */
   --brand-on-dark: oklch(0.92 0 0); /* The same colour lifted for a dark page */
   --brand-highlight: oklch(0.78 0 0); /* Warmth: badges, highlights, soft accents */
@@ -39,9 +38,9 @@
   --brand-surface-light: oklch(0.99 0 0); /* Cards on a light page */
   --brand-line-light: oklch(0.91 0 0); /* Borders on a light page */
 
-  /* === Tint scales, derived from the three hues so a brand types one colour each ===
-     WHY mixes and not typed steps: a brand that sets `--brand` gets a matching 100 to 800
-     with nothing else to maintain. 400 is the colour lifted for dark, 600 the colour itself. */
+  /* === Tint scales ===
+     Mixed from the three hues so `--brand` alone yields 100 to 800; 400 is the colour lifted
+     for dark, 600 the colour itself. */
   --brand-100: color-mix(in oklab, var(--brand) 12%, white);
   --brand-200: color-mix(in oklab, var(--brand) 28%, white);
   --brand-400: var(--brand-on-dark);
@@ -117,8 +116,7 @@
   --sidebar-ring: var(--brand);
 
   /* === Shadow tint ===
-     The one knob the design layer exposes. Pure black greys out warm surfaces,
-     so the shadow takes the darkest surface's hue. Radius, focus and motion live there. */
+     Pure black greys out warm surfaces, so the shadow takes the darkest surface's hue. */
   --elev-tint: var(--brand-ink);
 }
 
@@ -198,14 +196,18 @@
   --color-cat-indigo: var(--cat-indigo);
   --color-cat-purple: var(--cat-purple);
 
-  /* A hue as text or icon on its own tint: 40% toward the foreground clears AA in both themes.
-     A tone's 10% tint under plain destructive text is 3.6:1; the ink mix is not. */
+  /* A hue as text on its own tint mixes 40% toward the foreground to clear AA in both themes,
+     where plain destructive text on that tint is 3.6:1. */
   --color-cat-cyan-ink: color-mix(in oklab, var(--color-cat-cyan) 60%, var(--color-foreground));
   --color-cat-teal-ink: color-mix(in oklab, var(--color-cat-teal) 60%, var(--color-foreground));
   --color-cat-purple-ink: color-mix(in oklab, var(--color-cat-purple) 60%, var(--color-foreground));
   --color-cat-amber-ink: color-mix(in oklab, var(--color-cat-amber) 60%, var(--color-foreground));
   --color-success-ink: color-mix(in oklab, var(--color-success) 60%, var(--color-foreground));
-  --color-destructive-ink: color-mix(in oklab, var(--color-destructive) 60%, var(--color-foreground));
+  --color-destructive-ink: color-mix(
+    in oklab,
+    var(--color-destructive) 60%,
+    var(--color-foreground)
+  );
 
   /* Light theme color system: the light surfaces and lines of the brand roles */
   --color-background: var(--gray-50);

package/src/tokens/primitives.css

@@ -1,11 +1,5 @@
-/* The bits-ui state variants every primitive in `./shadcn` is written against.
- *
- * bits-ui v2 writes `data-checked` / `data-open` and v1 wrote
- * `data-state="checked"`, so each variant matches both and a component does not
- * have to know which it is talking to. They live here rather than in a
- * consumer's stylesheet because the classes that need them ship in this
- * package: an app that defines only the palette would render a switch that
- * never moves. */
+/* Each variant matches both bits-ui v2's `data-checked` and v1's `data-state="checked"`, and
+ * ships here because an app that defines only the palette gets a switch that never moves. */
 @custom-variant data-open {
   &:where([data-state="open"]),
   &:where([data-open]:not([data-open="false"])) {
@@ -80,9 +74,8 @@
     background: color-mix(in oklab, var(--ring-color) 24%, transparent);
   }
 
-  /* A default macOS overlay scrollbar paints a black bar on a dark panel. Track
-     transparent, thumb on the line token, so it belongs to whatever surface it
-     is over. The border is what insets the thumb without a second element. */
+  /* A default macOS overlay scrollbar paints a black bar on a dark panel, so the track stays
+     transparent and the thumb takes the line token. */
   :where(html) {
     scrollbar-color: var(--color-border, var(--border)) transparent;
   }
@@ -111,16 +104,11 @@
 }
 
 @layer components {
-  /* Three moves the kit repeats. They are classes rather than tokens because a
-     component wants one name, not four declarations, and because the reduced
-     motion guard then lives in one place instead of in every component.
+  /* Classes, not tokens, so a component takes one name and the reduced-motion guard lives in
+     one place; the `t-` prefix matches the transitions-dev snippets. */
 
-     Namespaced `t-` to match the transitions-dev snippets, which these sit
-     beside rather than duplicate. */
-
-  /* A control that reads as a key: it travels down a pixel under the finger.
-     The travel is what sells it, because a colour change alone reads as a hover
-     state, not as a press. */
+  /* A key-like control travels down a pixel under the finger, because a colour change alone
+     reads as a hover, not a press. */
   .t-press {
     transition:
       background-color var(--duration-quick) var(--ease-smooth-out),
@@ -134,9 +122,8 @@
     transform: translateY(1px);
   }
 
-  /* A card that answers the pointer. It rises by a pixel and gains the next
-     step of elevation, so the hover reads as the card coming forward rather
-     than as its border changing colour. */
+  /* A hover card rises a pixel and gains the next elevation step, so it reads as coming
+     forward, not as its border changing colour. */
   .t-lift {
     transition:
       box-shadow var(--duration-fast) var(--ease-smooth-out),

package/src/components/list-page/section-label.svelte

@@ -1,39 +0,0 @@
-<script lang="ts">
-// =========================
-// IMPORTS
-// =========================
-import type { Snippet } from "svelte";
-import { cn } from "../../lib/utils.js";
-import type { PhosphorIcon } from "../../lib/icon-types.js";
-
-// =========================
-// TYPES
-// =========================
-interface Props {
-	// The one label style for panel, rail group and sub-section headers. Retyped
-	// copies drifted to a different tracking value.
-	icon?: PhosphorIcon;
-	children: Snippet;
-	class?: string;
-};
-
-// =========================
-// PROPS
-// =========================
-let { icon: Icon, children, class: className }: Props = $props();
-</script>
-
-<!-- =========================== -->
-<!-- MARKUP -->
-<!-- =========================== -->
-<span
-	class={cn(
-		"flex items-center gap-2 text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground",
-		className,
-	)}
->
-	{#if Icon}
-		<Icon class="size-4 text-brand" aria-hidden="true" />
-	{/if}
-	{@render children()}
-</span>

package/src/tasks/define-statuses.ts

@@ -1,32 +0,0 @@
-import type { StatusDef, StatusId, StatusMap, Statuses } from "./status-types.js";
-
-/**
- * Build a status registry from a plain map. The registry keeps the map's keys as
- * a union, so `statuses.ids` and lookups stay typed.
- *
- * ```ts
- * const statuses = defineStatuses({
- *   draft: { label: "Draft", tone: "neutral" },
- *   sent: { label: "Sent", tone: "info" },
- * });
- * ```
- */
-export function defineStatuses<const M extends StatusMap>(
-	map: M,
-): Statuses & { ids: StatusId<M>[] } {
-	const lookup = map as Record<string, StatusDef | undefined>;
-	const find = (id: string): StatusDef | undefined => lookup[id];
-
-	return {
-		map,
-		ids: Object.keys(map) as StatusId<M>[],
-		has: (id) => find(id) !== undefined,
-		get: find,
-		label: (id) => find(id)?.label ?? id,
-		tone: (id) => find(id)?.tone ?? "neutral",
-		icon: (id) => find(id)?.icon,
-		variant: (id) => find(id)?.variant ?? "open",
-		progress: (id) => find(id)?.progress,
-		color: (id) => find(id)?.color,
-	};
-}

package/src/tasks/inbox/inbox.svelte

@@ -1,203 +0,0 @@
-<script lang="ts">
-	import { tick, type Snippet } from "svelte";
-	import { Badge } from "../../shadcn/badge/index.js";
-	import { Button } from "../../shadcn/button/index.js";
-	import * as Empty from "../../shadcn/empty/index.js";
-	import { Kbd, KbdGroup } from "../../shadcn/kbd/index.js";
-	import { Tabs, TabsList, TabsTrigger } from "../../shadcn/tabs/index.js";
-	import { ToggleGroup, ToggleGroupItem } from "../../shadcn/toggle-group/index.js";
-	import { cn } from "../../lib/utils.js";
-	import StatusDot from "../status-dot.svelte";
-	import InboxCard from "./inbox-card.svelte";
-	import { flatten, groupByProject, inLane, isTyping, laneOf } from "./inbox-logic.js";
-	import { inboxKinds, inboxStates } from "./inbox-statuses.js";
-	import type {
-		InboxItem,
-		InboxKindFilter,
-		InboxLane,
-		InboxProject,
-		InboxVerdict,
-	} from "./inbox-types.js";
-
-	interface Props {
-		items: InboxItem[];
-		/** The host applies the verdict and passes the updated items back. */
-		onverdict: (verdict: InboxVerdict) => void;
-		/** Replaces an item's summary lines. */
-		renderProposal?: Snippet<[InboxItem]>;
-		/** Trailing content in a project's header, such as a link to its timeline. */
-		renderGroupAction?: Snippet<[InboxProject]>;
-		class?: string;
-	};
-
-	let { items, onverdict, renderProposal, renderGroupAction, class: className }: Props = $props();
-
-	const LANES: { id: InboxLane; label: string }[] = [
-		{ id: "needs", label: "Needs you" },
-		{ id: "auto", label: "Done by the agent" },
-		{ id: "decided", label: "Decided" },
-	];
-
-	let lane = $state<InboxLane>("needs");
-	let kind = $state<InboxKindFilter>("all");
-	let cursor = $state(0);
-	let cards = $state<Record<string, ReturnType<typeof InboxCard> | null>>({});
-
-	let counts = $derived(
-		Object.fromEntries(LANES.map((l) => [l.id, items.filter((i) => laneOf(i) === l.id).length])) as Record<
-			InboxLane,
-			number
-		>,
-	);
-	let groups = $derived(groupByProject(inLane(items, lane, kind)));
-	let visible = $derived(flatten(groups));
-	// WHY an index and not an id: when a verdict removes the item under the cursor,
-	// the same index lands on the next one, so triage keeps moving down the queue.
-	let selected = $derived(visible[Math.min(cursor, visible.length - 1)]);
-
-	async function move(step: number) {
-		if (!visible.length) return;
-		cursor = Math.max(0, Math.min(visible.length - 1, cursor + step));
-		await tick();
-		document.querySelector<HTMLElement>(`[data-inbox-item="${CSS.escape(visible[cursor].id)}"]`)?.focus();
-	}
-
-	function onkeydown(event: KeyboardEvent) {
-		if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey) return;
-		if (isTyping(event.target)) return;
-		const card = selected ? cards[selected.id] : null;
-		const actions: Record<string, (() => void) | undefined> = {
-			j: () => move(1),
-			k: () => move(-1),
-			a: () => card?.approve(),
-			d: () => card?.decline(),
-			s: () => card?.steer(),
-			e: () => card?.edit(),
-			u: () => card?.undo(),
-		};
-		const run = actions[event.key];
-		if (!run) return;
-		event.preventDefault();
-		run();
-	}
-
-	function setLane(next: string) {
-		lane = next as InboxLane;
-		cursor = 0;
-	}
-
-	function setKind(next: string | undefined) {
-		kind = (next || "all") as InboxKindFilter;
-		cursor = 0;
-	}
-</script>
-
-<!-- WHY the key handler sits on the region: the shortcuts work wherever focus is inside the inbox and nowhere else on the page. -->
-<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
-<div
-	role="region"
-	aria-label="Inbox"
-	class={cn("flex h-full min-h-0 flex-col gap-3", className)}
-	{onkeydown}
->
-	<div class="flex flex-wrap items-center justify-between gap-2">
-		<Tabs value={lane} onValueChange={setLane}>
-			<TabsList>
-				{#each LANES as l (l.id)}
-					<TabsTrigger value={l.id} class="gap-2 px-3">
-						{l.label}
-						<span class="text-muted-foreground text-xs tabular-nums">{counts[l.id]}</span>
-					</TabsTrigger>
-				{/each}
-			</TabsList>
-		</Tabs>
-		<ToggleGroup
-			type="single"
-			variant="outline"
-			size="sm"
-			value={kind}
-			onValueChange={setKind}
-			aria-label="Filter by kind"
-		>
-			<ToggleGroupItem value="all">All</ToggleGroupItem>
-			{#each inboxKinds.ids as id (id)}
-				<ToggleGroupItem value={id}>{inboxKinds.label(id)}</ToggleGroupItem>
-			{/each}
-		</ToggleGroup>
-	</div>
-
-	<div class="-mx-1 min-h-0 flex-1 overflow-y-auto px-1 pb-1">
-		{#if !visible.length}
-			<Empty.Root class="h-full">
-				<Empty.Header>
-					<Empty.Media>
-						<StatusDot statuses={inboxStates} status="approved" size={28} />
-					</Empty.Media>
-					{#if kind !== "all"}
-						<Empty.Title>Nothing of this kind here</Empty.Title>
-						<Empty.Description>Show every kind to see the rest of this lane.</Empty.Description>
-					{:else if lane === "needs"}
-						<Empty.Title>Queue clear</Empty.Title>
-						<Empty.Description>The agent handled the rest, and nothing is waiting on you.</Empty.Description>
-					{:else if lane === "auto"}
-						<Empty.Title>The agent hasn't done anything on its own yet</Empty.Title>
-						<Empty.Description>Safe work it finishes by itself lands here, with an undo.</Empty.Description>
-					{:else}
-						<Empty.Title>No verdicts yet</Empty.Title>
-						<Empty.Description>What you approve or decline shows here and on the project timeline.</Empty.Description>
-					{/if}
-				</Empty.Header>
-				<Empty.Content>
-					{#if kind !== "all"}
-						<Button size="sm" variant="outline" onclick={() => setKind("all")}>Show every kind</Button>
-					{:else if lane === "needs" && counts.auto}
-						<Button size="sm" variant="outline" onclick={() => setLane("auto")}>See what the agent did</Button>
-					{:else if lane !== "needs" && counts.needs}
-						<Button size="sm" variant="outline" onclick={() => setLane("needs")}>Go to the queue</Button>
-					{/if}
-				</Empty.Content>
-			</Empty.Root>
-		{:else}
-			<div class="flex flex-col gap-5">
-				{#each groups as group (group.project.id)}
-					<section aria-label={group.project.name} class="flex flex-col gap-2">
-						<header class="flex items-center gap-2 px-1">
-							<h2 class="text-sm font-medium">{group.project.name}</h2>
-							{#if group.project.client}
-								<span class="text-muted-foreground text-sm">{group.project.client}</span>
-							{/if}
-							<Badge variant="outline" class="tabular-nums">{group.items.length}</Badge>
-							<div class="ml-auto flex items-center gap-1">
-								{#if group.project.href}
-									<Button size="sm" variant="ghost" href={group.project.href}>Timeline</Button>
-								{/if}
-								{@render renderGroupAction?.(group.project)}
-							</div>
-						</header>
-						<div class="flex flex-col gap-2">
-							{#each group.items as item (item.id)}
-								<InboxCard
-									bind:this={cards[item.id]}
-									{item}
-									selected={selected?.id === item.id}
-									onselect={() => (cursor = visible.findIndex((v) => v.id === item.id))}
-									{onverdict}
-									{renderProposal}
-								/>
-							{/each}
-						</div>
-					</section>
-				{/each}
-			</div>
-		{/if}
-	</div>
-
-	<footer class="text-muted-foreground flex flex-wrap items-center gap-x-4 gap-y-1 text-xs max-sm:hidden">
-		<span class="inline-flex items-center gap-1.5"><KbdGroup><Kbd>j</Kbd><Kbd>k</Kbd></KbdGroup> move</span>
-		<span class="inline-flex items-center gap-1.5"><Kbd>a</Kbd> approve</span>
-		<span class="inline-flex items-center gap-1.5"><Kbd>d</Kbd> decline</span>
-		<span class="inline-flex items-center gap-1.5"><Kbd>s</Kbd> steer</span>
-		<span class="inline-flex items-center gap-1.5"><Kbd>e</Kbd> edit draft</span>
-		<span class="inline-flex items-center gap-1.5"><Kbd>u</Kbd> undo</span>
-	</footer>
-</div>