@webjsdev/cli 0.10.45 → 0.10.46

package/templates/gallery/app/robots.ts

@@ -1,6 +1,3 @@
-// (delete this file), then delete this marker line. webjs check fails while the
-// marker remains.
-//
 // app/robots.ts serves /robots.txt. The default export returns a string (served
 // as text/plain) or an object. This example allows all crawlers and points them
 // at the sitemap. Tighten the rules (Disallow paths) for a real app.

package/templates/gallery/app/sitemap.ts

@@ -1,6 +1,3 @@
-// routes, or prune it (delete this file), then delete this marker line. webjs
-// check fails while the marker remains.
-//
 // app/sitemap.ts serves /sitemap.xml. The default export is a (possibly async)
 // server function; `sitemap(entries)` from @webjsdev/server serializes a
 // spec-valid XML sitemap. In a real app, build the entries from your content

package/templates/gallery/app/twitter-image.ts

@@ -1,6 +1,3 @@
-// (delete this file), then delete this marker line. webjs check fails while the
-// marker remains.
-//
 // app/twitter-image.ts serves /twitter-image (the card image shown when the
 // site is shared on Twitter/X). Its own route so the Twitter card can differ
 // from the Open Graph image (opengraph-image.ts); when they are identical, drop
@@ -8,9 +5,9 @@
 // roughly 1200x630. Reference it via metadata `twitter: { images: [...] }`.
 export default function TwitterImage() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
-    <rect width="1200" height="630" fill="#1c1613"/>
-    <text x="80" y="330" font-family="system-ui, sans-serif" font-size="88" font-weight="700" fill="#f5f0eb">My App</text>
-    <text x="80" y="410" font-family="system-ui, sans-serif" font-size="36" fill="#ff8a3d">Build on the platform, not against it</text>
+    <rect width="1200" height="630" fill="#1e2226"/>
+    <text x="80" y="330" font-family="system-ui, sans-serif" font-size="88" font-weight="700" fill="#dee2e6">My App</text>
+    <text x="80" y="410" font-family="system-ui, sans-serif" font-size="36" fill="#94989c">Build on the platform, not against it</text>
   </svg>`;
   return new Response(svg, {
     headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=3600' },

package/templates/gallery/components/ui/badge.ts

@@ -0,0 +1,41 @@
+/**
+ * badgeClass: the gallery's badge/pill design token, built on @webjsdev/ui.
+ *
+ * A `@webjsdev/ui` tier-1 CLASS HELPER (like buttonClass): it returns a Tailwind
+ * class string you spread onto a NATIVE inline element, almost always a `<span>`
+ * (a static label) or an `<a>` (a linked tag). Native markup means no wrapper
+ * component and correct semantics for free:
+ *
+ *   <span class=${badgeClass()}>Signed in</span>
+ *   <span class=${badgeClass({ variant: 'outline' })}>Example app</span>
+ *
+ * OWN-AND-THEME: this is `@webjsdev/ui`'s badge THEMED to this scaffold's two
+ * real uses, NOT the fuller shadcn badge (solid primary, secondary, destructive,
+ * ghost, link). Keep only the variants you use, styled to your look. `default`
+ * is a soft primary pill (a status chip); `outline` is a quiet muted tag.
+ *
+ * A11y: a static badge is a plain non-focusable `<span>`. Make it an `<a>` only
+ * when it links somewhere.
+ *
+ * Design tokens used (app/layout.ts): --color-primary, --color-border,
+ * --color-muted-foreground.
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+// Shared by every variant: an inline pill that hugs its content and never wraps.
+const BASE = 'inline-flex w-fit shrink-0 items-center whitespace-nowrap';
+
+const VARIANTS = {
+  // A soft, tinted primary chip. Used for a status ("Signed in").
+  default: 'rounded-full bg-primary/15 text-primary px-2.5 py-1 text-xs font-medium',
+  // A tiny, quiet outline tag. Used to label a kind of thing ("Example app").
+  outline:
+    'rounded border border-border text-muted-foreground px-1.5 py-0.5 text-[0.6rem] font-semibold uppercase tracking-wider',
+} as const;
+
+export type BadgeVariant = keyof typeof VARIANTS;
+
+/** Compose the Tailwind classes for a badge/pill. Append your own layout as needed. */
+export function badgeClass(opts: { variant?: BadgeVariant } = {}): string {
+  return cn(BASE, VARIANTS[opts.variant ?? 'default']);
+}

package/templates/gallery/components/ui/button.ts

@@ -0,0 +1,86 @@
+/**
+ * buttonClass: the gallery's button design token, built on @webjsdev/ui.
+ *
+ * This is a `@webjsdev/ui` tier-1 CLASS HELPER (the shadcn model): instead of a
+ * `<ui-button>` wrapper element, it returns a Tailwind class string you spread
+ * onto a NATIVE `<button>` (or `<a>` for a link-styled button). Native markup
+ * means form submission, focus, keyboard activation, and screen-reader
+ * semantics all work with no extra wiring:
+ *
+ *   <button class=${buttonClass()} @click=${...}>Save</button>
+ *   <button class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Cancel</button>
+ *   <a      class=${buttonClass({ variant: 'link', size: 'none' })} href="/x">More</a>
+ *
+ * WHY a helper and not a component: the class helper adds NO indirection, so a
+ * demo's real markup (the `@click`, the `?disabled`, the concept it teaches)
+ * stays fully visible, while every button in the gallery shares one source of
+ * truth for its look. That is also why the #1057-style "one button forgot
+ * cursor-pointer" gap cannot happen: `cursor-pointer` lives on BASE.
+ *
+ * OWN-AND-THEME your copy: this file is `webjs ui add button` output THEMED to
+ * this scaffold's look (rounded-xl, the primary / card / muted-link styles the
+ * gallery uses). That is the intended `@webjsdev/ui` workflow: you own the
+ * component file and tune its class values to your brand. Run
+ * `webjs ui add button` (or edit here) to change the button system app-wide.
+ *
+ * A11y: an icon-only button has no visible text, so give it an `aria-label`.
+ * Native `<button>` focus + keyboard activation are already correct.
+ *
+ * Design tokens used (defined in app/layout.ts): --color-primary,
+ * --color-primary-foreground, --color-card, --color-border, --color-foreground,
+ * --color-muted-foreground, --color-accent, --color-ring.
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+// BASE: shared by every variant + size, so a fix here (e.g. the focus ring, or
+// cursor-pointer) applies to the whole button system at once.
+// Focus is handled ONCE by the design system's global :focus-visible ring (the
+// ui theme's @layer base in public/input.css), so buttons need no per-element
+// focus style here.
+const BASE =
+  'inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap text-sm transition-all disabled:pointer-events-none disabled:opacity-60';
+
+// VARIANTS carry COLOR + weight + hover (what the button IS). Add a variant here
+// and it is instantly available to every demo.
+const VARIANTS = {
+  // The filled call-to-action (Send, Upload, Stream tokens, Greet).
+  default: 'bg-primary text-primary-foreground font-semibold hover:bg-primary/90 active:scale-[0.97]',
+  // The quieter card-surfaced action (Reset, Read once, secondary controls).
+  secondary: 'bg-card border border-border text-foreground font-medium hover:border-border-strong',
+  // Transparent until hovered (a toolbar / menu action, e.g. Log out).
+  ghost: 'bg-transparent text-foreground font-medium hover:bg-accent',
+  // A button that reads as an inline text link (navigate, toggle, reveal).
+  link: 'text-muted-foreground font-medium underline decoration-dotted underline-offset-4 hover:text-foreground',
+  // A subtle destructive action (a delete icon / a remove control): transparent
+  // and muted at rest, turning red on hover. NOT a loud solid-red button; theme
+  // it to a filled `bg-destructive` variant if you want a prominent confirm.
+  destructive: 'bg-transparent text-muted-foreground font-medium hover:text-destructive hover:bg-destructive/10',
+} as const;
+
+// SIZES carry SHAPE (padding + radius). `none` is for the link variant, which
+// is inline text and takes no box padding.
+const SIZES = {
+  default: 'px-4 py-2 rounded-xl',
+  sm: 'px-3.5 py-1.5 rounded-xl',
+  xs: 'px-3 py-1 rounded-lg',
+  none: '',
+} as const;
+
+export type ButtonVariant = keyof typeof VARIANTS;
+export type ButtonSize = keyof typeof SIZES;
+
+export interface ButtonClassOptions {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+/**
+ * Compose the Tailwind classes for a button. Both options are optional
+ * (`buttonClass()` is the primary call-to-action). `cn` de-duplicates, so you
+ * can append your own layout classes: `class="${buttonClass()} w-full"`.
+ */
+export function buttonClass(opts: ButtonClassOptions = {}): string {
+  const variant = opts.variant ?? 'default';
+  const size = opts.size ?? 'default';
+  return cn(BASE, VARIANTS[variant], SIZES[size]);
+}

package/templates/gallery/components/ui/card.ts

@@ -0,0 +1,36 @@
+/**
+ * cardClass: the gallery's panel-surface design token, built on @webjsdev/ui.
+ *
+ * A `@webjsdev/ui` tier-1 CLASS HELPER for the "card" surface every demo panel
+ * sits on. It owns only the SURFACE (radius, border, background), NOT the
+ * padding or inner layout, because those genuinely differ per panel (a form
+ * grid, a centered card, a tight toolbar). So you compose:
+ *
+ *   <div class="${cardClass()} p-5 grid gap-4">...</div>
+ *   <div class="${cardClass()} p-2 flex items-center gap-2">...</div>
+ *
+ * WHY split surface from layout: the surface is the thing that MUST be identical
+ * everywhere (so all panels read as one system), while padding and layout are a
+ * per-panel decision. Centralizing only the surface gives consistency without
+ * flattening intentional layout differences. Contrast the fuller shadcn Card
+ * (header / title / content / footer subparts) that `webjs ui add card` ships:
+ * this scaffold's panels are simple containers, so it keeps only what it uses.
+ *
+ * OWN-AND-THEME: this is `@webjsdev/ui`'s card THEMED to this scaffold (a
+ * `rounded-2xl` panel on `bg-card` with a hairline border). Change the surface
+ * here and every panel updates at once. When you build a real app on
+ * `@webjsdev/ui`, do the same: pull the primitive, keep the parts you use, and
+ * theme it to your brand.
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+// The shared panel surface. Padding + inner layout stay on the call site.
+const SURFACE = 'rounded-2xl border border-border bg-card';
+
+/**
+ * Compose the Tailwind classes for a card/panel surface. Append the panel's own
+ * padding + layout: `class="${cardClass()} p-5 grid gap-4 max-w-[460px]"`.
+ */
+export function cardClass(extra?: string): string {
+  return cn(SURFACE, extra);
+}

package/templates/gallery/components/ui/input.ts

@@ -0,0 +1,50 @@
+/**
+ * inputClass: the gallery's text-field design token, built on @webjsdev/ui.
+ *
+ * Like buttonClass, this is a `@webjsdev/ui` tier-1 CLASS HELPER: it returns a
+ * Tailwind class string you spread onto a NATIVE `<input>` or `<textarea>`, so
+ * the browser's built-in form behaviour, validation, and accessibility all work
+ * with nothing extra:
+ *
+ *   <input class=${inputClass()} name="email" type="email" />
+ *   <textarea class=${inputClass()} name="message" rows="3"></textarea>
+ *
+ * The same helper styles inputs AND textareas here, because this app wants them
+ * to look identical. That is the point of a design token: one place decides how
+ * every field looks, so they cannot drift apart. If you later want a distinct
+ * textarea look, add a `textareaClass` alongside this and theme it separately
+ * (that is exactly how `webjs ui add textarea` would give you one).
+ *
+ * OWN-AND-THEME: this is `@webjsdev/ui`'s input, THEMED to this scaffold's look
+ * (a filled `bg-background` field, `rounded-xl`, a primary focus border). You
+ * own this file: change the class values here and every field in the app
+ * updates at once. This is the intended workflow when building on `@webjsdev/ui`
+ * for a real app: pull the primitive, then make it yours.
+ */
+import { cn } from '#lib/utils/cn.ts';
+
+// One surface for every text field. `focus:border-primary` is the whole focus
+// affordance (no ring), to match this app's quiet, token-driven chrome.
+const BASE =
+  'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-60';
+
+/**
+ * Compose the Tailwind classes for a text input or textarea. Append your own
+ * layout classes as needed: `class="${inputClass()} max-w-sm"`.
+ */
+export function inputClass(extra?: string): string {
+  return cn(BASE, extra);
+}
+
+// A BORDERLESS field for composing INSIDE a card/pill: a `cardClass()` form with a
+// button (a search-bar). The card is the bordered container, so the field is
+// seamless (transparent, no border), and it flexes to fill the row. Distinct from
+// inputClass (a standalone bordered field); a bordered input inside a bordered
+// card would be a box-in-a-box.
+const BARE =
+  'flex-1 min-w-0 bg-transparent border-0 outline-none py-1.5 text-[15px] text-foreground placeholder:text-muted-foreground';
+
+/** Compose the classes for a borderless text field composed inside a card pill. */
+export function bareInputClass(extra?: string): string {
+  return cn(BARE, extra);
+}

package/templates/gallery/lib/utils/ui.ts

@@ -0,0 +1,31 @@
+/**
+ * ui.ts: repeated MARKUP-chunk helpers (the `lib/utils/ui.ts` pattern).
+ *
+ * A design system has two kinds of helper. A repeated PRIMITIVE with variants
+ * (button, input, card, badge) is a CLASS helper in `components/ui/` returning a
+ * class string. A repeated markup CHUNK (a heading, a lede, a back link) is an
+ * `html`-fragment helper here in `lib/utils/ui.ts`: it returns SSR-time markup,
+ * so the output is byte-identical to writing the tags inline, with no client
+ * runtime. Use these for chunks that repeat across pages; keep genuinely one-off
+ * or trivial prose (a lone `<code>`, a single text link) inline for readability.
+ *
+ * OWN-AND-THEME: these fragments are THIS gallery's shared bits. Change a class
+ * here and every page updates at once. Build your own for your app.
+ */
+import { html } from '@webjsdev/core';
+
+/** A page's `<h1>` heading (the standard demo/page title). */
+export function pageHeading(title: unknown) {
+  return html`<h1 class="text-h2 font-bold mb-4">${title}</h1>`;
+}
+
+/** The muted intro paragraph under a heading. Pass a string OR an `html` fragment
+ *  (a lede often wraps an inline `<code>`). */
+export function lede(content: unknown) {
+  return html`<p class="text-muted-foreground mb-4">${content}</p>`;
+}
+
+/** A slim "back" link (used above each gallery demo to return to the index). */
+export function backLink(href: string, label: unknown) {
+  return html`<a href=${href} class="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline mb-6">${label}</a>`;
+}

package/templates/gallery/modules/broadcast/components/broadcast-feed.ts

@@ -4,6 +4,8 @@
 // closes in disconnectedCallback. At SSR it renders the disconnected state, so
 // the page still reads with JS off (a live feed has no no-JS equivalent).
 import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 
 export class BroadcastFeed extends WebComponent {
   private connected = signal(false);
@@ -45,9 +47,9 @@ export class BroadcastFeed extends WebComponent {
         </div>
         <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
           <input name="msg" autocomplete="off" placeholder="Message everyone"
-            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+            class=${inputClass('flex-1 min-w-0')} />
           <button type="submit"
-            class="px-3.5 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Send</button>
+            class=${buttonClass({ size: 'sm' })}>Send</button>
         </form>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.lines.get().map((line) => html`

package/templates/gallery/modules/caching/components/cache-buster.ts

@@ -3,6 +3,7 @@
 // button is inert (cache eviction there happens as a side effect of the write
 // action that changed the data).
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { bustCaches } from '#modules/caching/actions/bust-caches.server.ts';
 
 export class CacheBuster extends WebComponent {
@@ -21,7 +22,7 @@ export class CacheBuster extends WebComponent {
     return html`
       <div class="flex items-center gap-3 text-[15px]">
         <button @click=${() => this.bust()}
-          class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">revalidate this page</button>
+          class=${buttonClass({ variant: 'secondary', size: 'sm' })}>revalidate this page</button>
         <span class="text-muted-foreground">${this.status.get()}</span>
       </div>
     `;

package/templates/gallery/modules/client-router/components/router-controls.ts

@@ -12,6 +12,7 @@
 // home; a page/layout never hydrates. With JS off the plain link still works
 // (progressive enhancement), while the buttons are inert.
 import { WebComponent, html, signal, navigate, revalidate, disableClientRouter, enableClientRouter } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 export class RouterControls extends WebComponent {
   // Instance signal mirroring whether soft navigation is currently on.
@@ -30,13 +31,13 @@ export class RouterControls extends WebComponent {
         <div class="flex flex-wrap gap-3 items-center">
           <button
             @click=${() => navigate('/features/client-router/second')}
-            class="inline-flex items-center px-4 py-2 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">navigate() to page two</button>
+            class=${buttonClass({ variant: 'secondary' })}>navigate() to page two</button>
           <button
             @click=${() => revalidate()}
-            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">revalidate() the snapshot cache</button>
+            class=${buttonClass({ variant: 'link', size: 'none' })}>revalidate() the snapshot cache</button>
           <button
             @click=${() => this.toggleRouter()}
-            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">${soft ? 'disableClientRouter()' : 'enableClientRouter()'} (soft nav: ${soft ? 'on' : 'off'})</button>
+            class=${buttonClass({ variant: 'link', size: 'none' })}>${soft ? 'disableClientRouter()' : 'enableClientRouter()'} (soft nav: ${soft ? 'on' : 'off'})</button>
         </div>
         <p class="text-sm text-muted-foreground">
           Plain link:

package/templates/gallery/modules/components/components/counter-card.ts

@@ -4,6 +4,8 @@
 // component authoring shape. Styling is crafted Tailwind on the app's design
 // tokens so it stays visually coherent with the rest of the app.
 import { WebComponent, prop, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
 
 export class CounterCard extends WebComponent({
   // A reactive prop rides an HTML attribute / SSR hydration. Declared ONLY here
@@ -20,14 +22,14 @@ export class CounterCard extends WebComponent({
 
   render() {
     return html`
-      <div class="grid gap-4 p-5 rounded-2xl bg-card border border-border max-w-[320px]">
+      <div class="${cardClass()} grid gap-4 p-5 max-w-[320px]">
         <slot></slot>
         <div class="flex items-baseline gap-2">
           <span class="text-[2.5rem] font-bold tabular-nums leading-none text-foreground">${this.count.get()}</span>
           <span class="text-sm text-muted-foreground">${this.label}</span>
         </div>
         <button @click=${() => this.count.set(this.count.get() + 1)}
-          class="w-fit px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Increment</button>
+          class="${buttonClass()} w-fit">Increment</button>
       </div>
     `;
   }

package/templates/gallery/modules/components/components/reactive-meter.ts

@@ -10,9 +10,17 @@ export class ReactiveMeter extends WebComponent {
   static styles = css`
     .row { display: flex; align-items: center; gap: 8px; }
     button {
-      padding: 6px 12px; border-radius: 10px; border: 1px solid #8883;
+      padding: 6px 12px; border-radius: 10px; border: 1px solid var(--color-border);
       background: transparent; color: inherit; cursor: pointer; font: inherit;
     }
+    /* Tailwind's focus styles do NOT cross the shadow boundary, so a shadow-DOM
+       component styles its own focus, else the browser's default outline (thick,
+       shown on window-refocus) appears. Match the design system's global ring
+       EXACTLY: the --ring colour at 50% (the same as outline-ring/50). */
+    button:focus-visible {
+      outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent);
+      outline-offset: 2px;
+    }
     .val { font-variant-numeric: tabular-nums; font-weight: 600; }
     .muted { opacity: 0.6; font-size: 13px; }
   `;

package/templates/gallery/modules/components/components/task-loader.ts

@@ -6,6 +6,7 @@
 // `async render()` instead, which blocks SSR so the data is server-rendered;
 // a Task shows its PENDING state at SSR, so the value is not in the first paint.
 import { WebComponent, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { Task, TaskStatus } from '@webjsdev/core/task';
 
 export class TaskLoader extends WebComponent {
@@ -33,13 +34,13 @@ export class TaskLoader extends WebComponent {
     const t = this.task;
     const body =
       t.status === TaskStatus.PENDING ? html`<span class="text-muted-foreground">loading…</span>`
-      : t.status === TaskStatus.ERROR ? html`<span class="text-red-500">error: ${String((t.error as Error)?.message ?? t.error)}</span>`
+      : t.status === TaskStatus.ERROR ? html`<span class="text-destructive">error: ${String((t.error as Error)?.message ?? t.error)}</span>`
       : t.status === TaskStatus.COMPLETE ? html`<span class="text-foreground">${t.value}</span>`
       : html`<span class="text-muted-foreground">idle</span>`;
     return html`
       <div class="flex items-center gap-3 text-[15px]">
         <button @click=${() => this.reload()}
-          class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">reload</button>
+          class=${buttonClass({ variant: 'secondary', size: 'sm' })}>reload</button>
         ${body}
       </div>
     `;

package/templates/gallery/modules/components/components/theme-context.ts

@@ -7,6 +7,8 @@
 // controllers automate. All light DOM, so the provider's <slot> projects its
 // children normally.
 import { WebComponent, html, signal } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { cardClass } from '#components/ui/card.ts';
 import { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from '@webjsdev/core/context';
 
 type Theme = 'light' | 'dark';
@@ -26,9 +28,9 @@ export class ThemeProvider extends WebComponent {
 
   render() {
     return html`
-      <div class="grid gap-3 p-3 rounded-xl bg-card border border-border max-w-[420px]">
+      <div class=${cardClass('grid gap-3 p-3 max-w-[420px]')}>
         <button @click=${() => this.toggle()}
-          class="w-fit px-3.5 py-1.5 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">
+          class="${buttonClass({ size: 'sm' })} w-fit">
           provider theme: ${this.provider.value} (toggle)
         </button>
         <slot></slot>
@@ -58,7 +60,7 @@ export class ThemeConsumer extends WebComponent {
       <div class="flex items-center gap-3 text-[15px] text-foreground">
         <span>child sees: <strong>${theme}</strong></span>
         <button @click=${() => this.readOnce()}
-          class="px-3 py-1 rounded-lg text-sm bg-card border border-border text-foreground cursor-pointer transition-colors hover:border-border-strong">read once</button>
+          class=${buttonClass({ variant: 'secondary', size: 'xs' })}>read once</button>
         <span class="text-muted-foreground text-sm">last one-shot: ${this.lastRead.get()}</span>
       </div>
     `;

package/templates/gallery/modules/directives/components/directive-demo.ts

@@ -12,6 +12,9 @@
 // HTML), and `asyncAppend` / `asyncReplace` (stream values from an async
 // iterable, appending each or replacing with the latest).
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { cn } from '#lib/utils/cn.ts';
+import { inputClass } from '#components/ui/input.ts';
 import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef, guard, cache, templateContent, asyncAppend, asyncReplace } from '@webjsdev/core/directives';
 
 interface Item { id: number; label: string }
@@ -107,9 +110,9 @@ export class DirectiveDemo extends WebComponent {
         <div class="grid gap-4">
           <div class="flex gap-2">
             <button @click=${() => this.reverse()}
-              class="px-3.5 py-1.5 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Reverse</button>
+              class=${buttonClass({ size: 'sm' })}>Reverse</button>
             <button @click=${() => this.add()}
-              class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
+              class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Add</button>
           </div>
           <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
           <ul class="grid gap-2 list-none m-0 p-0">
@@ -121,7 +124,7 @@ export class DirectiveDemo extends WebComponent {
           </ul>
           <!-- watch(signal) swaps only this node when ticks changes. -->
           <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
-            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
+            class="${buttonClass({ variant: 'link', size: 'none' })} w-fit">ticks: ${watch(this.ticks)}</button>
         </div>
 
         <div class="grid gap-3 border-t border-border pt-4">
@@ -132,18 +135,18 @@ export class DirectiveDemo extends WebComponent {
             <input
               ${ref(this.inputRef)}
               aria-label="Editable text for the ref focus demo"
-              class="flex-1 px-3 py-1.5 rounded-xl bg-card border border-border text-[15px] text-foreground"
+              class=${inputClass('flex-1 min-w-0')}
               .value=${live(this.text.get())}
               @input=${(e: Event) => this.text.set((e.target as HTMLInputElement).value)}>
             <button @click=${() => this.focusInput()}
-              class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">Focus</button>
+              class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Focus</button>
           </div>
           <!-- until shows the fallback until the promise resolves. -->
           <p class="text-sm text-muted-foreground">async: ${until(this.asyncValue, 'loading...')}</p>
           <!-- keyed discards and rebuilds this subtree when the key changes;
                unsafeHTML injects trusted, author-written HTML (NEVER user input). -->
           <button @click=${() => this.variant.set(variant + 1)}
-            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">rekey</button>
+            class="${buttonClass({ variant: 'link', size: 'none' })} w-fit">rekey</button>
           ${keyed(variant, html`<div class="text-[15px] text-foreground">${unsafeHTML('<em>fresh subtree</em>')} #${variant}</div>`)}
         </div>
 
@@ -152,16 +155,20 @@ export class DirectiveDemo extends WebComponent {
                guard counter re-renders it; the OTHER counter (ticks above) does
                not, so the guarded value stays put. -->
           <button @click=${() => this.guardBumps.set(this.guardBumps.get() + 1)}
-            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">bump guard dep</button>
+            class="${buttonClass({ variant: 'link', size: 'none' })} w-fit">bump guard dep</button>
           <p class="text-sm text-foreground">guarded: ${guard([this.guardBumps.get()], () => html`computed at bump #${this.guardBumps.get()}`)}</p>
 
           <!-- cache(value) keeps the inactive tab's DOM alive while you toggle,
                so switching back is instant and preserves any element state. -->
+          <!-- A tab toggle must keep a CONSTANT size between states, or the row
+               reflows and the content below dances. So both tabs use ONE variant
+               (same weight, border, padding) and cn() overrides only the active
+               COLORS, never the box. -->
           <div class="flex gap-2">
             <button @click=${() => this.tab.set('a')}
-              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'a' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab A</button>
+              class=${cn(buttonClass({ variant: 'secondary', size: 'xs' }), this.tab.get() === 'a' && 'bg-primary text-primary-foreground border-primary hover:border-primary')}>Tab A</button>
             <button @click=${() => this.tab.set('b')}
-              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'b' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab B</button>
+              class=${cn(buttonClass({ variant: 'secondary', size: 'xs' }), this.tab.get() === 'b' && 'bg-primary text-primary-foreground border-primary hover:border-primary')}>Tab B</button>
           </div>
           <div class="text-[15px] text-foreground">${cache(
             this.tab.get() === 'a'
@@ -181,7 +188,7 @@ export class DirectiveDemo extends WebComponent {
                you can watch them replay. The run counter forces the re-render. -->
           <div class="flex items-center gap-3">
             <button @click=${() => this.restartStreams()}
-              class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">restart streams</button>
+              class="${buttonClass({ variant: 'secondary', size: 'sm' })} w-fit">restart streams</button>
             <span class="text-sm text-muted-foreground">run #${this.streamRun.get()}</span>
           </div>
           <div class="text-sm text-muted-foreground">log (asyncAppend, one row per value):</div>

package/templates/gallery/modules/gallery/components/gallery-nav.ts

@@ -0,0 +1,54 @@
+// The gallery's left sidebar: a grouped index of every demo, with the current
+// one highlighted (docs-site style). WHY a component and not plain layout markup:
+// the features layout is PRESERVED across a soft navigation (only the page
+// content swaps), so a server-rendered "active" highlight would go stale. This
+// component listens for the router's `webjs:navigate` event and re-derives the
+// active item from location.pathname, so the highlight follows soft-nav. SSR is
+// still correct: `render()` reads the `current` prop (the pathname the layout
+// passes) for the first paint, and the client takes over from location after.
+import { WebComponent, prop, html, signal } from '@webjsdev/core';
+import { FEATURE_GROUPS } from '#modules/gallery/nav.ts';
+
+// Module-scope so the value survives re-renders; set on the client only (SSR
+// reads the `current` prop instead, so it never touches location during render).
+const activePath = signal('');
+
+export class GalleryNav extends WebComponent({ current: prop(String) }) {
+  #onNav = () => activePath.set(location.pathname);
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#onNav(); // seed from the real URL on hydrate
+    document.addEventListener('webjs:navigate', this.#onNav); // soft-nav (link + navigate())
+    window.addEventListener('popstate', this.#onNav); // back / forward
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('webjs:navigate', this.#onNav);
+    window.removeEventListener('popstate', this.#onNav);
+  }
+
+  render() {
+    // activePath is '' at SSR (and before hydrate), so fall back to the prop.
+    const active = activePath.get() || this.current;
+    const link = (href: string, title: string) => {
+      // Highlight the demo whose route we are on, INCLUDING its subroutes
+      // (/features/auth/dashboard highlights Auth). The trailing slash keeps
+      // /features/stream from matching /features/streaming.
+      const on = active === href || active.startsWith(href + '/');
+      const cls = 'block px-3 py-1.5 rounded-lg no-underline transition-colors ' +
+        (on ? 'bg-accent text-foreground font-medium' : 'text-muted-foreground hover:bg-accent hover:text-foreground');
+      return html`<a href=${href} aria-current=${on ? 'page' : 'false'} class=${cls}>${title}</a>`;
+    };
+    return html`
+      ${FEATURE_GROUPS.map((g) => html`
+        <div class="mb-5">
+          <div class="px-3 mb-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">${g.label}</div>
+          <nav class="flex flex-col gap-0.5">${g.items.map((i) => link(i.href, i.title))}</nav>
+        </div>
+      `)}
+    `;
+  }
+}
+GalleryNav.register('gallery-nav');