@webjsdev/cli 0.10.44 → 0.10.46

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/auth/actions/signup.server.ts

@@ -0,0 +1,19 @@
+'use server';
+
+import { db } from '#db/connection.server.ts';
+import { users } from '#db/schema.server.ts';
+import { hash } from '../password.server.ts';
+import { signIn } from '../auth.server.ts';
+
+// Creates the account, then signs the new user in and lands on the dashboard.
+// signIn returns a 302 Response carrying the session cookie; the signup page
+// action returns that Response as-is (a page action may return a Response).
+// signIn lives in the server-only auth module, imported here server-to-server,
+// so it never reaches the browser (the signup page only imports this action's
+// RPC stub).
+export async function signup(input: { name: string; email: string; password: string }) {
+  const exists = await db.query.users.findFirst({ where: { email: input.email }, columns: { id: true } });
+  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };
+  await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) });
+  return signIn('credentials', { email: input.email, password: input.password }, { redirectTo: '/features/auth/dashboard' });
+}

package/templates/gallery/modules/auth/auth.server.ts

@@ -0,0 +1,53 @@
+// The auth configuration. A server-only utility (a .server.ts with NO
+// 'use server'), so it runs server-side and its browser import is a throw-at-load
+// stub. Pages and route handlers import the pieces they need server-to-server;
+// the client only ever reaches auth through a 'use server' action's RPC stub.
+//
+// createAuth returns { auth, signIn, signOut, handlers }. `handlers` mounts at
+// app/api/auth/[...path]/route.ts (createAuth hardcodes the /api/auth/signin/*
+// and /api/auth/callback/* paths, which is why that route stays at the app root
+// even though the rest of this card lives under app/features/auth/).
+import { createAuth, Credentials, GitHub, Google } from '@webjsdev/server';
+import { db } from '#db/connection.server.ts';
+import { compare } from './password.server.ts';
+
+// AUTH_SECRET signs session tokens. Set a strong value in .env for any real
+// deployment. The dev fallback keeps a fresh scaffold booting, but is NOT safe
+// for production, so we fail fast if it is missing or blank there.
+const trimmedSecret = process.env.AUTH_SECRET?.trim();
+if (process.env.NODE_ENV === 'production' && !trimmedSecret) {
+  throw new Error('AUTH_SECRET must be set in production');
+}
+const authSecret = trimmedSecret || 'dev-insecure-secret-change-me';
+
+export const { auth, signIn, signOut, handlers } = createAuth({
+  providers: [
+    Credentials({
+      async authorize(credentials: { email: string; password: string }) {
+        const user = await db.query.users.findFirst({ where: { email: credentials.email } });
+        if (!user?.passwordHash || !await compare(credentials.password, user.passwordHash)) return null;
+        return { id: String(user.id), name: user.name, email: user.email };
+      },
+    }),
+    // OAuth providers: add GitHub / Google sign-in by setting the matching env
+    // vars. Each preset (GitHub(), Google()) reads AUTH_<PROVIDER>_ID / _SECRET,
+    // so they only activate once configured and a fresh scaffold still boots with
+    // just Credentials.
+    ...(process.env.AUTH_GITHUB_ID ? [GitHub({ clientId: process.env.AUTH_GITHUB_ID, clientSecret: process.env.AUTH_GITHUB_SECRET })] : []),
+    ...(process.env.AUTH_GOOGLE_ID ? [Google({ clientId: process.env.AUTH_GOOGLE_ID, clientSecret: process.env.AUTH_GOOGLE_SECRET })] : []),
+  ],
+  secret: authSecret,
+  // A failed credentials sign-in 302s to `${pages.error}?error=CredentialsSignin`.
+  // Point it at the login page so it reads searchParams.error and shows a message,
+  // instead of the createAuth default (the home page) swallowing the error.
+  pages: { error: '/features/auth/login' },
+});
+
+// Read the signed-in user off a request. auth(req) reads the session cookie
+// (falling back to the ambient request when called with no argument), so this
+// works from a page/layout, a segment middleware, or an action middleware that
+// holds the request (the greet demo's require-auth reads it this way).
+export async function getCurrentUser(req?: Request) {
+  const session = await auth(req);
+  return session?.user ?? null;
+}

package/templates/gallery/modules/auth/password.server.ts

@@ -0,0 +1,20 @@
+// Password hashing with scrypt from node:crypto (built into Node AND Bun, no
+// dependency). A server-only utility: hashes live server-side and never reach
+// the browser. Swap in argon2/bcrypt here if you prefer; the call sites only use
+// hash() and compare().
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scryptAsync = promisify(scrypt);
+
+export async function hash(password: string): Promise<string> {
+  const salt = randomBytes(16).toString('hex');
+  const buf = (await scryptAsync(password, salt, 64)) as Buffer;
+  return salt + ':' + buf.toString('hex');
+}
+
+export async function compare(password: string, stored: string): Promise<boolean> {
+  const [salt, key] = stored.split(':');
+  const buf = (await scryptAsync(password, salt, 64)) as Buffer;
+  return timingSafeEqual(buf, Buffer.from(key, 'hex'));
+}

package/templates/gallery/modules/auth/queries/current-user.server.ts

@@ -0,0 +1,12 @@
+'use server';
+
+import { getCurrentUser } from '../auth.server.ts';
+
+// This read deliberately stays POST-default (no 'method' export). A GET server
+// action (a cacheable, SSR-seeded read) is wrong for a per-session lookup: the
+// result differs per user and changes on sign-in / sign-out, so it must never be
+// browser-cached or shared. Reserve GET + cache + tags for data identical for
+// every visitor.
+export async function currentUser() {
+  return getCurrentUser();
+}

package/templates/gallery/modules/auth/types.ts

@@ -0,0 +1,9 @@
+export interface User {
+  id: number;
+  name: string | null;
+  email: string;
+}
+
+export type ActionResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string; status: number };

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>