@kahitsan/ksui 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "ksui is a set of shared SolidJS UI components plus the @kserp/host-ui type contract for KahitSan/Hilinga plugins. Published to the public npm registry and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with solid-js + @kserp/host-ui externalized to the host runtime.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/base/Button.tsx

@@ -0,0 +1,400 @@
+// Source: kahitsan-web src/components/ui/Button/Button.tsx (+ assets/css/button.css).
+// Extracted into ksui as a DOMAIN-FREE base primitive: an intent/variant button
+// with HUD scanline, clip-corner, ripple, glow, and pulse effects. It depends
+// only on solid-js (Dynamic) — no host kit, no kahitsan imports, no marketing
+// copy. The intent palette (amber/red/slate rgba maps) ships as the generic
+// default tone set; callers pass intent + variant and their own children.
+//
+// The monolith shipped these effects as global CSS (button.css). ksui publishes
+// no sidecar .css (the package exports only ./src under the `solid` condition),
+// so — like ProgressBar / LiveTimer — the keyframes + helper classes are
+// injected once per page via a runtime <style> tag and referenced with plain,
+// unscoped class names so the bundle stays self-contained.
+
+import {
+  splitProps,
+  createSignal,
+  onCleanup,
+  createMemo,
+  mergeProps,
+  Show,
+  For,
+  type JSX,
+  type Component,
+} from "solid-js";
+import { Dynamic } from "solid-js/web";
+
+const BUTTON_STYLE_ID = "ks-button-inline-style";
+const BUTTON_CSS = `
+.ks-hud-scan-line { position: relative; overflow: hidden; }
+.ks-hud-scan-line::before { content: ''; position: absolute; top: 0; left: -100%; width: 100%; height: 100%; opacity: 0; pointer-events: none; z-index: 1; transition: opacity 0.2s ease; background: linear-gradient(90deg, transparent, var(--ks-effect-color, rgba(201, 169, 97, 0.4)), transparent); }
+.ks-hud-scan-line:hover::before { left: 100%; opacity: 1; transition: all 0.8s ease; }
+.ks-hud-clip-top-left-bottom-right { clip-path: polygon(6px 0, 100% 0, 100% calc(100% - 6px), calc(100% - 6px) 100%, 0 100%, 0 6px); border: none !important; border-radius: 0 !important; }
+.ks-hud-clip-top-right-bottom-left { clip-path: polygon(0 0, calc(100% - 6px) 0, 100% 6px, 100% 100%, 6px 100%, 0 calc(100% - 6px)); border: none !important; border-radius: 0 !important; }
+.ks-hud-clip-minimal-top-left-bottom-right { clip-path: polygon(4px 0, 100% 0, 100% calc(100% - 4px), calc(100% - 4px) 100%, 0 100%, 0 4px); border: none !important; border-radius: 0 !important; }
+.ks-hud-clip-minimal-top-right-bottom-left { clip-path: polygon(0 0, calc(100% - 4px) 0, 100% 4px, 100% 100%, 4px 100%, 0 calc(100% - 4px)); border: none !important; border-radius: 0 !important; }
+.ks-hud-glow { transition: box-shadow 0.2s ease; box-shadow: 0 0 8px var(--ks-effect-glow, rgba(201, 169, 97, 0.3)); }
+.ks-hud-glow:hover:not(:disabled) { box-shadow: 0 0 15px var(--ks-effect-glow-hover, rgba(201, 169, 97, 0.5)); }
+.ks-hud-pulse { animation: ksHudPulse 2s infinite ease-in-out; }
+@keyframes ksHudPulse { 0%, 100% { background-color: var(--ks-effect-pulse-bg, rgba(201, 169, 97, 0.1)); box-shadow: 0 0 5px var(--ks-effect-pulse-glow, rgba(201, 169, 97, 0.2)); } 50% { background-color: var(--ks-effect-pulse-bg-mid, rgba(201, 169, 97, 0.2)); box-shadow: 0 0 10px var(--ks-effect-pulse-glow-mid, rgba(201, 169, 97, 0.4)); } }
+.ks-btn-ripple { position: relative; overflow: hidden; }
+.ks-btn-ripple-effect { position: absolute; border-radius: 50%; transform: scale(0.1); opacity: 0.8; animation: ksButtonRippleExpand 0.4s ease-out forwards; pointer-events: none; z-index: 0; background-color: var(--ks-ripple-color, rgba(255, 255, 255, 0.3)); }
+.ks-btn-ripple-fade { animation: ksButtonRippleFadeOnly 0.3s ease-out forwards; }
+@keyframes ksButtonRippleExpand { 0% { transform: scale(0.1); opacity: 0.5; } 100% { transform: scale(1); opacity: 0.25; } }
+@keyframes ksButtonRippleFadeOnly { 0% { opacity: 0.3; transform: scale(1); } 100% { opacity: 0; transform: scale(1.1); } }
+.ks-btn-ripple > *:not(.ks-btn-ripple-effect) { position: relative; z-index: 2; }
+.ks-interactive { transition: all 0.15s ease; }
+.ks-interactive:active:not(:disabled) { transform: scale(0.97); opacity: 0.8; }
+.ks-interactive:hover:not(:disabled) { transform: scale(1.02); }
+`;
+
+function ensureButtonStyle() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(BUTTON_STYLE_ID)) return;
+  const el = document.createElement("style");
+  el.id = BUTTON_STYLE_ID;
+  el.textContent = BUTTON_CSS;
+  document.head.appendChild(el);
+}
+
+const styles: Record<string, string> = {
+  "ks-hud-scan-line": "ks-hud-scan-line",
+  "ks-hud-clip-top-left-bottom-right": "ks-hud-clip-top-left-bottom-right",
+  "ks-hud-clip-top-right-bottom-left": "ks-hud-clip-top-right-bottom-left",
+  "ks-hud-clip-minimal-top-left-bottom-right": "ks-hud-clip-minimal-top-left-bottom-right",
+  "ks-hud-clip-minimal-top-right-bottom-left": "ks-hud-clip-minimal-top-right-bottom-left",
+  "ks-hud-glow": "ks-hud-glow",
+  "ks-hud-pulse": "ks-hud-pulse",
+  "ks-btn-ripple": "ks-btn-ripple",
+  "ks-btn-ripple-effect": "ks-btn-ripple-effect",
+  "ks-btn-ripple-fade": "ks-btn-ripple-fade",
+  "ks-interactive": "ks-interactive",
+};
+
+export type ButtonIntent = "primary" | "danger" | "secondary";
+export type ButtonVariant = "clip1" | "clip2" | "ghost" | "link";
+
+export interface ButtonProps {
+  /** Element / component to render as (defaults to "button"). */
+  as?: string | Component<Record<string, unknown>>;
+  intent?: ButtonIntent;
+  variant?: ButtonVariant;
+  noRipple?: boolean;
+  noScanline?: boolean;
+  noGlow?: boolean;
+  noPulse?: boolean;
+  icon?: (props: { size?: number; class?: string }) => JSX.Element;
+  iconPosition?: "left" | "right";
+  class?: string;
+  disabled?: boolean;
+  children?: JSX.Element;
+  type?: string;
+  onClick?: (event: MouseEvent) => void;
+  [key: string]: unknown;
+}
+
+function cn(...classes: Array<string | undefined | null | false>): string {
+  return classes.filter(Boolean).join(" ");
+}
+
+interface IntentColors {
+  ripple: string;
+  effect: string;
+  effectBg: string;
+  effectBorder: string;
+  effectGlow: string;
+}
+
+interface IntentConfig {
+  textColor: string;
+  background: string;
+  hover: string;
+  colors: IntentColors;
+}
+
+const buttonIntentConfig: Record<ButtonIntent, IntentConfig> = {
+  primary: {
+    textColor: "text-amber-400",
+    background: "bg-amber-600/20 border-amber-600/60",
+    hover: "hover:bg-amber-600/30 hover:border-amber-500",
+    colors: {
+      ripple: "rgba(255, 255, 255, 0.3)",
+      effect: "rgba(201, 169, 97, 0.4)",
+      effectBg: "rgba(201, 169, 97, 0.1)",
+      effectBorder: "rgba(201, 169, 97, 0.4)",
+      effectGlow: "rgba(201, 169, 97, 0.3)",
+    },
+  },
+  danger: {
+    textColor: "text-red-400",
+    background: "bg-red-600/20 border-red-600/60",
+    hover: "hover:bg-red-600/30 hover:border-red-500",
+    colors: {
+      ripple: "rgba(255, 255, 255, 0.3)",
+      effect: "rgba(255, 68, 68, 0.4)",
+      effectBg: "rgba(255, 68, 68, 0.1)",
+      effectBorder: "rgba(255, 68, 68, 0.4)",
+      effectGlow: "rgba(255, 68, 68, 0.3)",
+    },
+  },
+  secondary: {
+    textColor: "text-slate-400",
+    background: "bg-slate-600/20 border-slate-600/60",
+    hover: "hover:bg-slate-600/30 hover:border-slate-500",
+    colors: {
+      ripple: "rgba(255, 255, 255, 0.3)",
+      effect: "rgba(148, 163, 184, 0.4)",
+      effectBg: "rgba(148, 163, 184, 0.1)",
+      effectBorder: "rgba(148, 163, 184, 0.4)",
+      effectGlow: "rgba(148, 163, 184, 0.3)",
+    },
+  },
+};
+
+interface VariantConfig {
+  effects: string[];
+  baseClasses: string;
+  overrideType: boolean;
+}
+
+const buttonVariantConfig: Record<ButtonVariant, VariantConfig> = {
+  clip1: {
+    effects: ["clip-top-left-bottom-right"],
+    baseClasses: "px-4 py-2 border",
+    overrideType: false,
+  },
+  clip2: {
+    effects: ["clip-top-right-bottom-left"],
+    baseClasses: "px-4 py-2 border",
+    overrideType: false,
+  },
+  ghost: {
+    effects: [],
+    baseClasses: "px-4 py-2 bg-transparent border-transparent hover:bg-current/10 hover:border-transparent",
+    overrideType: true,
+  },
+  link: {
+    effects: [],
+    baseClasses:
+      "px-0 py-0 bg-transparent border-transparent underline-offset-4 hover:underline hover:bg-transparent hover:border-transparent",
+    overrideType: true,
+  },
+};
+
+interface Ripple {
+  id: number;
+  x: number;
+  y: number;
+  size: number;
+  isFading: boolean;
+}
+
+const Button = (props: ButtonProps): JSX.Element => {
+  ensureButtonStyle();
+
+  const merged = mergeProps(
+    {
+      as: "button" as ButtonProps["as"],
+      intent: "primary" as ButtonIntent,
+      variant: "clip1" as ButtonVariant,
+      noRipple: false,
+      noScanline: false,
+      noGlow: false,
+      noPulse: false,
+      iconPosition: "left" as const,
+    },
+    props,
+  );
+
+  const [local, others] = splitProps(merged, [
+    "as",
+    "intent",
+    "variant",
+    "noRipple",
+    "noScanline",
+    "noGlow",
+    "noPulse",
+    "icon",
+    "iconPosition",
+    "class",
+    "children",
+    "onClick",
+    "disabled",
+  ]);
+
+  const [ripples, setRipples] = createSignal<Ripple[]>([]);
+
+  let elementRef: HTMLElement | undefined;
+  let mouseDownTime = 0;
+
+  const isIconOnly = createMemo(() => !local.children && local.icon);
+  const intentConfig = createMemo(
+    () => buttonIntentConfig[local.intent as ButtonIntent] || buttonIntentConfig.primary,
+  );
+  const variantConfig = createMemo(
+    () => buttonVariantConfig[local.variant as ButtonVariant] || buttonVariantConfig.clip1,
+  );
+
+  const hasRipple = createMemo(() => {
+    if (local.noRipple) return false;
+    if (local.variant === "link") return false;
+    return true;
+  });
+
+  const activeEffects = createMemo(() => {
+    const effects: string[] = [...variantConfig().effects];
+    if (!local.noScanline) effects.push("scanline");
+    return effects;
+  });
+
+  const effectClasses = createMemo(() =>
+    activeEffects()
+      .map((effect) => {
+        const effectMap: Record<string, string> = {
+          scanline: styles["ks-hud-scan-line"],
+          "clip-top-left-bottom-right": styles["ks-hud-clip-top-left-bottom-right"],
+          "clip-top-right-bottom-left": styles["ks-hud-clip-top-right-bottom-left"],
+          "clip-minimal-top-left-bottom-right": styles["ks-hud-clip-minimal-top-left-bottom-right"],
+          "clip-minimal-top-right-bottom-left": styles["ks-hud-clip-minimal-top-right-bottom-left"],
+          glow: styles["ks-hud-glow"],
+          pulse: styles["ks-hud-pulse"],
+        };
+        return effectMap[effect];
+      })
+      .filter(Boolean),
+  );
+
+  const customProperties = createMemo(() => {
+    const colors = intentConfig().colors;
+    return {
+      "--ks-effect-color": colors.effect,
+      "--ks-effect-bg": colors.effectBg,
+      "--ks-effect-border": colors.effectBorder,
+      "--ks-effect-bg-hover": colors.effect.replace("0.1", "0.2"),
+      "--ks-effect-border-hover": colors.effect.replace("0.4", "0.6"),
+      "--ks-effect-glow": colors.effectGlow,
+      "--ks-effect-glow-hover": colors.effectGlow.replace("0.3", "0.5"),
+      "--ks-effect-pulse-bg": colors.effectBg,
+      "--ks-effect-pulse-bg-mid": colors.effect.replace("0.4", "0.2"),
+      "--ks-effect-pulse-glow": colors.effectGlow.replace("0.3", "0.2"),
+      "--ks-effect-pulse-glow-mid": colors.effectGlow,
+      "--ks-ripple-color": colors.ripple,
+    } as JSX.CSSProperties;
+  });
+
+  const classes = createMemo(() => {
+    const coreClasses =
+      "select-none inline-flex items-center justify-center gap-2 font-medium transition-all duration-200 focus:outline-none text-sm rounded";
+    const textColor = intentConfig().textColor;
+    const backgroundClasses = variantConfig().overrideType
+      ? ""
+      : `${intentConfig().background} ${intentConfig().hover}`;
+    const variantClasses = variantConfig().baseClasses;
+
+    return cn(
+      coreClasses,
+      textColor,
+      backgroundClasses,
+      variantClasses,
+      local.class,
+      hasRipple() && styles["ks-btn-ripple"],
+      !hasRipple() && styles["ks-interactive"],
+      isIconOnly() && "aspect-square !p-2",
+      ...effectClasses(),
+      local.disabled && "opacity-50 cursor-not-allowed",
+    );
+  });
+
+  const handleMouseDown = (event: MouseEvent) => {
+    if (local.disabled) return;
+    if (hasRipple() && elementRef) {
+      mouseDownTime = Date.now();
+      const rect = elementRef.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const y = event.clientY - rect.top;
+      const size = Math.max(rect.width, rect.height) * 2;
+      const rippleId = Date.now() + Math.random();
+      setRipples((prev) => [...prev, { id: rippleId, x, y, size, isFading: false }]);
+    }
+  };
+
+  const handleMouseUp = () => {
+    if (!hasRipple() || local.disabled) return;
+    const timeSinceMouseDown = Date.now() - mouseDownTime;
+    const delayBeforeFade = Math.max(0, 400 - timeSinceMouseDown);
+    setTimeout(() => {
+      setRipples((prev) => prev.map((r) => ({ ...r, isFading: true })));
+      setTimeout(() => setRipples([]), 400);
+    }, delayBeforeFade);
+  };
+
+  const handleMouseLeave = () => {
+    if (!local.disabled) handleMouseUp();
+  };
+
+  const handleClick = (event: MouseEvent) => {
+    if (local.onClick && !local.disabled) local.onClick(event);
+  };
+
+  const renderContent = createMemo(() => {
+    const IconComponent = local.icon;
+    if (isIconOnly() && IconComponent) return <IconComponent />;
+    if (IconComponent && local.children) {
+      const icon = <IconComponent />;
+      return local.iconPosition === "left" ? (
+        <>
+          {icon}
+          {local.children}
+        </>
+      ) : (
+        <>
+          {local.children}
+          {icon}
+        </>
+      );
+    }
+    if (IconComponent) return <IconComponent />;
+    return local.children;
+  });
+
+  onCleanup(() => setRipples([]));
+
+  return (
+    <Dynamic
+      component={local.as}
+      ref={(el: HTMLElement) => {
+        elementRef = el;
+        const maybeRef = (others as { ref?: unknown }).ref;
+        if (typeof maybeRef === "function") (maybeRef as (e: HTMLElement) => void)(el);
+      }}
+      class={classes()}
+      style={customProperties()}
+      onMouseDown={handleMouseDown}
+      onMouseUp={handleMouseUp}
+      onMouseLeave={handleMouseLeave}
+      onClick={handleClick}
+      disabled={local.disabled}
+      {...others}
+    >
+      {renderContent()}
+      <Show when={hasRipple()}>
+        <For each={ripples()}>
+          {(ripple) => (
+            <span
+              class={cn(styles["ks-btn-ripple-effect"], ripple.isFading && styles["ks-btn-ripple-fade"])}
+              style={{
+                left: `${ripple.x - ripple.size / 2}px`,
+                top: `${ripple.y - ripple.size / 2}px`,
+                width: `${ripple.size}px`,
+                height: `${ripple.size}px`,
+                "background-color": "var(--ks-ripple-color, rgba(255, 255, 255, 0.3))",
+              }}
+            />
+          )}
+        </For>
+      </Show>
+    </Dynamic>
+  );
+};
+
+export default Button;

package/src/components/base/Dropdown.tsx

@@ -0,0 +1,164 @@
+import { createSignal, For, onCleanup, onMount, Show, type Component, type JSX } from "solid-js";
+import { Dynamic } from "solid-js/web";
+import ChevronDown from "lucide-solid/icons/chevron-down";
+
+/** A lucide-solid icon component (or any component taking size/class). */
+type IconComponent = Component<{ size?: number; class?: string }>;
+
+/** The status of a dropdown item, used to render a small leading colored dot
+ *  when no explicit icon is supplied. Domain-free: the caller maps its own
+ *  enum onto one of these three presentational states. */
+export type DropdownItemStatus = "open" | "closed" | "neutral";
+
+export interface DropdownItem {
+  /** Stable identity, matched against the selected `value`. */
+  id: string;
+  /** Primary text shown for the item and on the trigger when selected. */
+  label: string;
+  /** Optional secondary line under the label. */
+  description?: string;
+  /** Arbitrary payload handed back to `onSelect` unchanged. */
+  value?: unknown;
+  /** Optional leading icon. Takes precedence over the status dot. */
+  icon?: IconComponent;
+  /** Optional pill rendered beside the label. */
+  badge?: string;
+  /** When true the item is dimmed and not selectable. */
+  disabled?: boolean;
+  /** When no `icon` is set, renders a small colored status dot. */
+  status?: DropdownItemStatus;
+}
+
+export interface DropdownProps {
+  /** The selectable options, top to bottom. */
+  items: DropdownItem[];
+  /** The currently selected item's `id`. Uncontrolled fallback selects the first item. */
+  value?: string;
+  /** Trigger text when nothing is selected. */
+  placeholder?: string;
+  /** Optional leading icon on the trigger button. */
+  icon?: IconComponent;
+  /** Minimum width of the trigger/menu (any CSS length). Defaults to 280px. */
+  minWidth?: string;
+  /** Disables the whole control. */
+  disabled?: boolean;
+  /** Called with the chosen item when an option is selected. */
+  onSelect?: (item: DropdownItem) => void;
+  /** Extra classes on the outer container. */
+  class?: string;
+}
+
+// Maps a presentational status to a dot color. Domain-free: only the three
+// status states are recognized; everything else falls back to neutral gray.
+function statusColor(status?: DropdownItemStatus): string {
+  switch (status) {
+    case "open":
+      return "#10B981";
+    case "closed":
+      return "#6B7280";
+    default:
+      return "#6B7280";
+  }
+}
+
+// A generic single-select dropdown: a labeled trigger that opens a panel of
+// items, each optionally carrying a description, icon (or status dot), and
+// badge. Click-outside closes the panel; the chevron rotates while open.
+// Presentational only and domain-free — no baked-in copy or business literals.
+export default function Dropdown(props: DropdownProps): JSX.Element {
+  const [isOpen, setIsOpen] = createSignal(false);
+  const [selectedItem, setSelectedItem] = createSignal<DropdownItem | undefined>(
+    props.items.find((item) => item.id === props.value),
+  );
+
+  const currentSelection = () => selectedItem() ?? props.items.find((i) => i.id === props.value) ?? props.items[0];
+
+  onMount(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      const target = e.target as Element | null;
+      if (!target?.closest("[data-dropdown-container]")) {
+        setIsOpen(false);
+      }
+    };
+    document.addEventListener("click", handleClickOutside);
+    onCleanup(() => document.removeEventListener("click", handleClickOutside));
+  });
+
+  const handleSelect = (item: DropdownItem) => {
+    if (item.disabled) return;
+    setSelectedItem(item);
+    setIsOpen(false);
+    props.onSelect?.(item);
+  };
+
+  return (
+    <div class={`relative inline-block ${props.class ?? ""}`} data-dropdown-container>
+      <button
+        onClick={() => !props.disabled && setIsOpen(!isOpen())}
+        disabled={props.disabled}
+        class={`flex items-center gap-3 px-4 py-3 bg-zinc-900/50 border border-zinc-800/50 rounded-lg hover:bg-zinc-900/70 transition-all backdrop-blur-sm select-none ${
+          props.disabled ? "opacity-50 cursor-not-allowed" : "cursor-pointer"
+        }`}
+        style={{ "min-width": props.minWidth ?? "280px" }}
+      >
+        <Show when={props.icon}>
+          {(Icon) => <Dynamic component={Icon()} size={18} class="text-amber-500" />}
+        </Show>
+        <div class="flex-1 text-left">
+          <div class="font-semibold text-white">
+            {currentSelection()?.label ?? props.placeholder ?? "Select an option"}
+          </div>
+          <Show when={currentSelection()?.description}>
+            <div class="text-xs text-zinc-400">{currentSelection()?.description}</div>
+          </Show>
+        </div>
+        <ChevronDown size={18} class={`text-zinc-400 transition-transform ${isOpen() ? "rotate-180" : ""}`} />
+      </button>
+
+      <Show when={isOpen()}>
+        <div class="absolute top-full left-0 mt-2 w-full bg-zinc-900/95 border border-zinc-800/50 rounded-lg backdrop-blur-xl z-50 shadow-xl select-none">
+          <For each={props.items}>
+            {(item) => (
+              <button
+                onClick={() => handleSelect(item)}
+                disabled={item.disabled}
+                class={`w-full px-4 py-3 flex items-center gap-3 hover:bg-zinc-800/50 transition-all first:rounded-t-lg last:rounded-b-lg select-none ${
+                  currentSelection()?.id === item.id ? "bg-zinc-800/30" : ""
+                } ${item.disabled ? "opacity-50 cursor-not-allowed" : "cursor-pointer"}`}
+              >
+                <div class="flex items-center gap-2 flex-shrink-0">
+                  <Show
+                    when={item.icon}
+                    fallback={
+                      <Show when={item.status}>
+                        <div
+                          class="w-2 h-2 rounded-full flex-shrink-0"
+                          style={{ background: statusColor(item.status) }}
+                        />
+                      </Show>
+                    }
+                  >
+                    {(Icon) => <Dynamic component={Icon()} size={16} class="text-amber-500" />}
+                  </Show>
+                </div>
+                <div class="flex-1 text-left min-w-0">
+                  <div class="font-medium text-white flex items-center gap-2">
+                    {item.label}
+                    <Show when={item.badge}>
+                      <span class="px-2 py-0.5 text-xs font-medium bg-zinc-700/50 text-zinc-400 rounded flex-shrink-0">
+                        {item.badge}
+                      </span>
+                    </Show>
+                  </div>
+                  <Show when={item.description}>
+                    <div class="text-xs text-zinc-400 truncate">{item.description}</div>
+                  </Show>
+                </div>
+              </button>
+            )}
+          </For>
+        </div>
+      </Show>
+    </div>
+  );
+}

package/src/components/base/EyebrowBadge.tsx

@@ -0,0 +1,108 @@
+import { Show, type JSX } from "solid-js";
+
+export type EyebrowTone = "amber" | "blue" | "emerald" | "red" | "zinc";
+
+interface ToneClass {
+  /** Text color for the kicker label. */
+  text: string;
+  /** Tinted background, used by the bordered pill variant. */
+  bg: string;
+  /** Accent border color, used by the bordered pill variant. */
+  border: string;
+}
+
+// Module-private tone palette. The caller picks a tone; nothing
+// domain-specific leaks into this atom. Each tone is a flat color family so
+// the badge reads as a quiet accent rather than a loud chip.
+const TONE_CLASS: Record<EyebrowTone, ToneClass> = {
+  amber: {
+    text: "text-amber-400",
+    bg: "bg-amber-500/10",
+    border: "border-amber-500",
+  },
+  blue: {
+    text: "text-blue-400",
+    bg: "bg-blue-500/10",
+    border: "border-blue-500",
+  },
+  emerald: {
+    text: "text-emerald-400",
+    bg: "bg-emerald-500/10",
+    border: "border-emerald-500",
+  },
+  red: {
+    text: "text-red-400",
+    bg: "bg-red-500/10",
+    border: "border-red-500",
+  },
+  zinc: {
+    text: "text-zinc-500",
+    bg: "bg-zinc-800/50",
+    border: "border-zinc-600",
+  },
+};
+
+// Tracking presets for the wide letter-spacing. "normal" is Tailwind's
+// tracking-widest; the wider presets cover the heading kickers that use
+// arbitrary tracking values.
+const TRACKING_CLASS = {
+  normal: "tracking-widest",
+  wide: "tracking-[0.2em]",
+  wider: "tracking-[0.3em]",
+} as const;
+
+export type EyebrowTracking = keyof typeof TRACKING_CLASS;
+
+export interface EyebrowBadgeProps {
+  /** The kicker text. Rendered uppercase via CSS, so pass natural casing. */
+  label: string;
+  /** Color family for the label (and the accent border when bordered). */
+  tone?: EyebrowTone;
+  /**
+   * Render the bordered pill variant: a tinted background with a left accent
+   * border (the hero-style kicker). When false (default) it is a plain
+   * tracked-text kicker with no box.
+   */
+  bordered?: boolean;
+  /** Letter-spacing preset. */
+  tracking?: EyebrowTracking;
+  /** Render as an inline-block <div> instead of an inline <span>. */
+  block?: boolean;
+  /** Extra classes on the wrapper. */
+  class?: string;
+  testId?: string;
+}
+
+// A tiny, domain-free eyebrow / kicker atom: an uppercase, wide-tracked,
+// bold micro-label. The plain variant is just tracked text; the bordered
+// variant wraps it in a tinted pill with a left accent border. Presentational
+// only — the caller supplies the label and picks a tone.
+export default function EyebrowBadge(props: EyebrowBadgeProps): JSX.Element {
+  const tc = () => TONE_CLASS[props.tone ?? "amber"];
+  const tracking = () => TRACKING_CLASS[props.tracking ?? "normal"];
+
+  const base = () =>
+    `text-xs font-bold uppercase ${tracking()} ${tc().text}`;
+  const borderedExtra = () =>
+    props.bordered
+      ? `inline-block px-4 py-1 border-l-2 ${tc().bg} ${tc().border}`
+      : "";
+
+  const className = () =>
+    `${base()} ${borderedExtra()} ${props.class ?? ""}`.trim();
+
+  return (
+    <Show
+      when={props.block || props.bordered}
+      fallback={
+        <span data-testid={props.testId} class={className()}>
+          {props.label}
+        </span>
+      }
+    >
+      <div data-testid={props.testId} class={`inline-block ${className()}`}>
+        {props.label}
+      </div>
+    </Show>
+  );
+}