@krizaka/sovkora-design-system 0.0.0-stage → 4.0.0

package/src/components/ClipPlayer.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+/**
+ * @file ClipPlayer.tsx
+ * @description A short clip that is plainly a clip: a muted loop that plays in view, a badge, play/pause and sound
+ * buttons, and a click that opens it larger. Words are props; nothing is fetched.
+ */
+import { MuteIcon, PauseIcon, PlayIcon, SoundIcon, VideoIcon } from "@krizaka/icons";
+import { Button } from "@krizaka/ui/button";
+import { cn } from "@krizaka/ui/cn";
+import { Dialog } from "@krizaka/ui/dialog";
+import * as React from "react";
+
+/** The files of a clip: H.264 `mp4` (the fallback), `webm` (tried first) and the poster. */
+export interface ClipSources {
+  mp4: string;
+  /** The VP9 file, tried first by the browsers that read it. */
+  webm?: string;
+  poster: string;
+}
+
+/** Every word of the player, translated by the app. */
+export interface ClipPlayerLabels {
+  /** The badge that says it is a video, with its length: `Video · 5 s`. */
+  badge: string;
+  play: string;
+  pause: string;
+  mute: string;
+  /** The sound button while the clip is muted. */
+  unmute: string;
+  /** The name of the button that opens the clip larger (the whole frame is that button). */
+  enlarge: string;
+  /** The close button of the large view. */
+  close: string;
+}
+
+/** Props of {@link ClipPlayer}. */
+export interface ClipPlayerProps {
+  /** The files. */
+  sources: ClipSources;
+  /** The accessible name of the video: what it shows, in a sentence. */
+  title: string;
+  /** The words. */
+  labels: ClipPlayerLabels;
+  /** The shape of the frame: a 16:9 one by default, a portrait one as tall as a phone allows. */
+  orientation?: "landscape" | "portrait";
+  /** Extra classes on the video, merged last. */
+  className?: string;
+}
+
+const REDUCED = "(prefers-reduced-motion: reduce)";
+const readReducedMotion = () => (typeof window.matchMedia === "function" ? window.matchMedia(REDUCED).matches : false);
+function subscribeReducedMotion(notify: () => void) {
+  const query = typeof window.matchMedia === "function" ? window.matchMedia(REDUCED) : null;
+  query?.addEventListener?.("change", notify);
+  return () => query?.removeEventListener?.("change", notify);
+}
+
+const control = "pointer-events-auto bg-surface-0/80 backdrop-blur";
+
+/**
+ * A clip that is plainly a clip: muted loop that plays only while on screen (and pauses off screen and in a hidden
+ * tab), a badge, play/pause and sound buttons on hover and focus (always shown where the pointer cannot hover), and a
+ * click anywhere on the frame opens it larger in a dialog with the native controls. Under `prefers-reduced-motion` it
+ * never plays by itself: the poster and a play button. Plain files, `playsInline`, `preload="none"`.
+ *
+ * @param props - {@link ClipPlayerProps}
+ * @returns The player of a short clip.
+ */
+export function ClipPlayer({
+  sources,
+  title,
+  labels,
+  orientation = "landscape",
+  className,
+}: Readonly<ClipPlayerProps>) {
+  const ref = React.useRef<HTMLVideoElement>(null);
+  const userPaused = React.useRef(false);
+  const [playing, setPlaying] = React.useState(false);
+  const [muted, setMuted] = React.useState(true);
+  const [open, setOpen] = React.useState(false);
+  // On the server nothing plays (the preference is unknown); in the browser it is the visitor's.
+  const reduced = React.useSyncExternalStore(subscribeReducedMotion, readReducedMotion, () => true);
+
+  React.useEffect(() => {
+    const video = ref.current;
+    if (!video || reduced || typeof IntersectionObserver === "undefined") return;
+    let visible = false;
+    const sync = () => {
+      if (visible && !document.hidden && !userPaused.current && !open) void video.play?.()?.catch?.(() => undefined);
+      else video.pause?.();
+    };
+    const observer = new IntersectionObserver(
+      (entries) => {
+        visible = entries.some((entry) => entry.isIntersecting);
+        sync();
+      },
+      { threshold: 0.35 },
+    );
+    observer.observe(video);
+    document.addEventListener("visibilitychange", sync);
+    return () => {
+      observer.disconnect();
+      document.removeEventListener("visibilitychange", sync);
+      video.pause?.();
+    };
+  }, [reduced, open]);
+
+  const toggle = () => {
+    const video = ref.current;
+    if (!video) return;
+    if (video.paused) {
+      userPaused.current = false;
+      void video.play?.()?.catch?.(() => undefined);
+    } else {
+      userPaused.current = true;
+      video.pause?.();
+    }
+  };
+  const toggleSound = () => {
+    const video = ref.current;
+    if (!video) return;
+    video.muted = !video.muted;
+    setMuted(video.muted);
+  };
+  const frame = orientation === "portrait" ? "aspect-[9/16] max-h-[70vh] w-auto" : "aspect-[26/15] w-full";
+
+  return (
+    <>
+      <div className="group relative overflow-hidden" data-clip-player>
+        <video
+          ref={ref}
+          aria-label={title}
+          poster={sources.poster}
+          muted
+          loop
+          playsInline
+          preload="none"
+          onPlay={() => setPlaying(true)}
+          onPause={() => setPlaying(false)}
+          data-reduced-motion={reduced ? "true" : undefined}
+          className={cn("mx-auto block object-cover", frame, className)}
+        >
+          {sources.webm && <source src={sources.webm} type="video/webm" />}
+          <source src={sources.mp4} type="video/mp4" />
+        </video>
+        <button
+          type="button"
+          onClick={() => setOpen(true)}
+          aria-label={labels.enlarge}
+          className="absolute inset-0 cursor-zoom-in focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        />
+        <span
+          className={cn(
+            control,
+            "pointer-events-none absolute left-3 top-3 inline-flex items-center gap-1.5 rounded-full border border-border-default px-2.5 py-1 font-mono text-xs text-fg",
+          )}
+          data-clip-badge
+        >
+          <VideoIcon size={14} />
+          {labels.badge}
+        </span>
+        {reduced && !playing && (
+          <span className="pointer-events-none absolute inset-0 flex items-center justify-center">
+            <Button
+              type="button"
+              variant="primary"
+              size="lg"
+              shape="pill"
+              className="pointer-events-auto"
+              onClick={toggle}
+              aria-label={labels.play}
+            >
+              <PlayIcon size={20} />
+            </Button>
+          </span>
+        )}
+        <div className="pointer-events-none absolute bottom-3 right-3 flex gap-2 opacity-100 transition-opacity [@media(hover:hover)]:opacity-0 [@media(hover:hover)]:group-focus-within:opacity-100 [@media(hover:hover)]:group-hover:opacity-100">
+          <Button
+            type="button"
+            variant="secondary"
+            size="sm"
+            className={control}
+            onClick={toggle}
+            aria-label={playing ? labels.pause : labels.play}
+          >
+            {playing ? <PauseIcon size={16} /> : <PlayIcon size={16} />}
+          </Button>
+          <Button
+            type="button"
+            variant="secondary"
+            size="sm"
+            className={control}
+            onClick={toggleSound}
+            aria-label={muted ? labels.unmute : labels.mute}
+            aria-pressed={!muted}
+          >
+            {muted ? <MuteIcon size={16} /> : <SoundIcon size={16} />}
+          </Button>
+        </div>
+      </div>
+      <Dialog.Root open={open} onOpenChange={setOpen}>
+        <Dialog.Content closeLabel={labels.close} className="max-w-5xl">
+          <Dialog.Header>
+            <Dialog.Title>{title}</Dialog.Title>
+          </Dialog.Header>
+          <video
+            aria-label={title}
+            poster={sources.poster}
+            controls
+            autoPlay
+            loop
+            playsInline
+            className="mx-auto block max-h-[75vh] w-full rounded-lg bg-surface-2"
+          >
+            {sources.webm && <source src={sources.webm} type="video/webm" />}
+            <source src={sources.mp4} type="video/mp4" />
+          </video>
+        </Dialog.Content>
+      </Dialog.Root>
+    </>
+  );
+}

package/src/components/CommandPalette.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { Command, CommandDialog } from "@krizaka/ui/command";
+import { Kbd } from "@krizaka/ui/kbd";
+import { useRouter } from "next/navigation";
+import * as React from "react";
+
+import { Icon } from "../icon";
+import type { CommandPaletteItem, CommandPaletteLabels } from "./CommandPalette.types";
+
+export type { CommandPaletteItem, CommandPaletteLabels } from "./CommandPalette.types";
+
+/** Props of {@link CommandPalette}. */
+export interface CommandPaletteProps {
+  /** The entries, grouped by `section` in their order. */
+  commands: CommandPaletteItem[];
+  /** The words, translated. */
+  labels: CommandPaletteLabels;
+  /** Where an entry's `href` goes. Default: the Next.js router (`router.push`). */
+  onNavigate?: (href: string) => void;
+  /** The letter that opens it with ⌘ / Ctrl. Default `k`. */
+  shortcut?: string;
+}
+
+/** The entries grouped by section, in the order they first appear. */
+function bySection(commands: CommandPaletteItem[]) {
+  const groups = new Map<string, CommandPaletteItem[]>();
+  for (const command of commands) groups.set(command.section, [...(groups.get(command.section) ?? []), command]);
+  return [...groups];
+}
+
+/**
+ * The Sovkora ⌘K palette: a product composite on `CommandDialog` from `@krizaka/ui/command` (cmdk + the platform's
+ * dialog: the combobox and listbox roles, the arrows, Enter, the filtering, the focus trap, Escape). It adds what is
+ * Sovkora's: the shortcut, the registry icons, the sections and the footer of hints. Words and entries arrive as
+ * props (since 3.0 they are required: the 1.x English defaults are gone).
+ *
+ * @param props - {@link CommandPaletteProps}
+ * @returns The palette, closed until ⌘K / Ctrl+K.
+ */
+export function CommandPalette({ commands, labels, onNavigate, shortcut = "k" }: Readonly<CommandPaletteProps>) {
+  const router = useRouter();
+  const [open, setOpen] = React.useState(false);
+
+  React.useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === shortcut) {
+        event.preventDefault();
+        setOpen((previous) => !previous);
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [shortcut]);
+
+  const run = (command: CommandPaletteItem) => {
+    setOpen(false);
+    if (command.href) (onNavigate ?? router.push)(command.href);
+    command.onSelect?.();
+  };
+
+  return (
+    <CommandDialog
+      open={open}
+      onOpenChange={setOpen}
+      label={labels.label}
+      footer={
+        <footer className="flex items-center gap-3 border-t border-border-subtle bg-surface-2 px-4 py-2 text-xs text-fg-secondary">
+          <span className="flex items-center gap-1">
+            <Kbd>↑↓</Kbd>
+            {labels.navigate}
+          </span>
+          <span className="flex items-center gap-1">
+            <Kbd>↵</Kbd>
+            {labels.open}
+          </span>
+          <span className="flex items-center gap-1">
+            <Kbd>esc</Kbd>
+            {labels.close}
+          </span>
+        </footer>
+      }
+    >
+      <Command.Input placeholder={labels.placeholder} />
+      <Command.List label={labels.results} emptyLabel={labels.empty}>
+        {bySection(commands).map(([section, items]) => (
+          <Command.Group key={section} heading={section}>
+            {items.map((command) => (
+              <Command.Item
+                key={command.id}
+                value={`${command.label} ${command.id}`}
+                keywords={command.keywords}
+                onSelect={() => run(command)}
+              >
+                <Icon name={command.icon} size={16} className="text-fg-secondary" />
+                <span className="flex-1">{command.label}</span>
+              </Command.Item>
+            ))}
+          </Command.Group>
+        ))}
+      </Command.List>
+    </CommandDialog>
+  );
+}

package/src/components/CommandPalette.types.ts

@@ -0,0 +1,33 @@
+import type { IconName } from "../icon";
+
+/** One entry of the palette. */
+export interface CommandPaletteItem {
+  /** Stable id (also the cmdk value, with the label). */
+  id: string;
+  /** What the person reads — passed translated. */
+  label: string;
+  icon: IconName;
+  /** Where it goes: handed to `onNavigate`. */
+  href?: string;
+  /** What it does, instead of (or after) navigating. */
+  onSelect?: () => void;
+  /** The group heading it sits under — passed translated. */
+  section: string;
+  /** More words the filter matches. */
+  keywords?: string[];
+}
+
+/** The words of the palette — passed translated. */
+export interface CommandPaletteLabels {
+  /** The accessible name of the palette (the dialog and the combobox). */
+  label: string;
+  placeholder: string;
+  /** The accessible name of the list of results. */
+  results: string;
+  /** Shown when nothing matches. */
+  empty: string;
+  /** Footer hints. */
+  navigate: string;
+  open: string;
+  close: string;
+}

package/src/components/Input.tsx

@@ -0,0 +1,14 @@
+import type * as React from "react";
+
+/**
+ * @file Input.tsx
+ * @description The text field is the @krizaka/ui primitive (`@krizaka/ui/field`), re-exported with its siblings.
+ * `invalid` sets aria-invalid; pair it with a `Field.Error`. React 19: `ref` is a prop.
+ */
+export { Field, Input, Select, Textarea } from "@krizaka/ui/field";
+
+/** Props of `Input`: the native input attributes, plus `invalid`. */
+export type InputProps = React.ComponentProps<"input"> & {
+  /** Marks the control invalid (aria-invalid, data-invalid). */
+  invalid?: boolean;
+};

package/src/components/RunFacts.tsx

@@ -0,0 +1,36 @@
+import { cn } from "@krizaka/ui/cn";
+
+/** One fact of a run: `Seed` → `20261011`. */
+export interface RunFact {
+  /** What it is, translated by the app (`Seed`). */
+  label: string;
+  /** Its value, as the run recorded it (`20261011`). */
+  value: string;
+}
+
+/** Props of {@link RunFacts}. */
+export interface RunFactsProps {
+  /** The facts, in reading order. */
+  facts: readonly RunFact[];
+  /** Extra classes on the list, merged last. */
+  className?: string;
+}
+
+/**
+ * What a run recorded, as a description list in mono: label left, value right (a long id breaks instead of overflowing).
+ *
+ * @param props - {@link RunFactsProps}
+ * @returns A description list.
+ */
+export function RunFacts({ facts, className }: Readonly<RunFactsProps>) {
+  return (
+    <dl className={cn("grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 font-mono text-xs", className)}>
+      {facts.map((fact) => (
+        <div key={fact.label} className="contents">
+          <dt className="text-fg-muted">{fact.label}</dt>
+          <dd className="text-fg [overflow-wrap:anywhere]">{fact.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/components/SentinelMini.tsx

@@ -0,0 +1,61 @@
+/**
+ * @file SentinelMini.tsx
+ * @description Miniaturized Sentinel nucleus for sidebar/header branding.
+ * Lives in components/ui to avoid cross-boundary imports between
+ * layout components and feature modules.
+ */
+
+interface SentinelMiniProps {
+  /** SVG size in pixels. Defaults to 24. */
+  size?: number;
+  /** Additional CSS classes. */
+  className?: string;
+}
+
+/**
+ * Compact 24×24 Sentinel mascot with simplified core + single orbital ring.
+ *
+ * @param props - Sentinel mini configuration.
+ * @returns A compact SVG brand mark element.
+ */
+export function SentinelMini({ size = 24, className = "" }: Readonly<SentinelMiniProps>) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className}
+      aria-hidden="true"
+    >
+      {/* Outer orbital */}
+      <circle
+        cx="12"
+        cy="12"
+        r="10"
+        stroke="var(--kz-accent)"
+        strokeWidth="0.5"
+        strokeDasharray="3 5 2 4"
+        opacity="0.4"
+      />
+      {/* Hexagonal frame */}
+      <polygon
+        points="12,4 18.9,8 18.9,16 12,20 5.1,16 5.1,8"
+        stroke="var(--kz-accent)"
+        strokeWidth="0.6"
+        opacity="0.25"
+        fill="none"
+      />
+      {/* Core ring */}
+      <circle cx="12" cy="12" r="4" stroke="var(--kz-accent)" strokeWidth="1" opacity="0.6" fill="none" />
+      {/* Inner core */}
+      <circle cx="12" cy="12" r="2" fill="var(--kz-accent)" opacity="0.8" />
+      {/* Core highlight */}
+      <circle cx="12" cy="11" r="0.8" fill="white" opacity="0.3" />
+      {/* Energy nodes */}
+      <circle cx="22" cy="12" r="0.8" fill="var(--kz-accent)" opacity="0.5" />
+      <circle cx="12" cy="2" r="0.8" fill="var(--kz-accent)" opacity="0.5" />
+    </svg>
+  );
+}

package/src/components/Skeleton.tsx

@@ -0,0 +1,50 @@
+import { cn } from "@krizaka/ui/cn";
+import { Skeleton as KzSkeleton, type SkeletonProps as KzSkeletonProps, skeletonVariants } from "@krizaka/ui/skeleton";
+
+export { skeletonVariants };
+
+/** Props of {@link Skeleton}: the @krizaka/ui skeleton, plus the 1.x shorthands. */
+export type SkeletonProps = KzSkeletonProps & {
+  /** @deprecated Since 2.0 — use `shape` (same names). */
+  variant?: NonNullable<KzSkeletonProps["shape"]>;
+  /** @deprecated Since 2.0 — size it with a `className` (`w-32`) or `style`. */
+  width?: string;
+  /** @deprecated Since 2.0 — size it with a `className` (`h-4`) or `style`. */
+  height?: string;
+};
+
+/**
+ * The @krizaka/ui skeleton (`shape` text · circle · rect, pulsing, hidden from assistive technology). The 1.x
+ * `variant`, `width` and `height` are kept as deprecated shorthands; the default shape stays `rect`.
+ *
+ * @param props - {@link SkeletonProps}
+ * @returns A loading placeholder.
+ */
+export function Skeleton({ variant, shape, width, height, style, ...props }: SkeletonProps) {
+  const sized = width || height ? { width, height, ...style } : style;
+  return <KzSkeleton shape={shape ?? variant ?? "rect"} style={sized} {...props} />;
+}
+
+/** Props of {@link SkeletonGroup}. */
+export interface SkeletonGroupProps {
+  /** The number of text lines; the last one is shorter. Default 3. */
+  lines?: number;
+  /** Extra classes on the group (its width), merged last. */
+  className?: string;
+}
+
+/**
+ * A paragraph of text skeletons; the last line is shorter.
+ *
+ * @param props - `lines` (default 3) and `className`.
+ * @returns A group of text skeletons.
+ */
+export function SkeletonGroup({ lines = 3, className }: Readonly<SkeletonGroupProps>) {
+  return (
+    <div className={cn("space-y-2.5", className)} aria-hidden="true">
+      {Array.from({ length: lines }, (_, i) => (
+        <Skeleton key={i} shape="text" className={i === lines - 1 ? "w-3/5" : undefined} />
+      ))}
+    </div>
+  );
+}

package/src/components/VideoResult.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+/**
+ * @file VideoResult.tsx
+ * @description What a video run of an Sovkora Studio leaves: the clip in its player, the exact prompt, what the run
+ * recorded (model, seed, frame, length, time, cost, run id), the command that makes it again and a download. Words are
+ * props; nothing is fetched.
+ */
+import { Button } from "@krizaka/ui/button";
+import { cn } from "@krizaka/ui/cn";
+import { CodeBlock } from "@krizaka/ui/code-block";
+import type * as React from "react";
+
+import { ClipPlayer, type ClipPlayerLabels, type ClipSources } from "./ClipPlayer";
+import { type RunFact,RunFacts } from "./RunFacts";
+
+/** One fact of the run (see {@link RunFact}). */
+export type VideoResultFact = RunFact;
+
+/** Every word of the component, translated by the app. */
+export interface VideoResultLabels extends ClipPlayerLabels {
+  /** The heading of the prompt. */
+  prompt: string;
+  /** The heading of the run's facts. */
+  facts: string;
+  /** The heading of the command. */
+  reproduce: string;
+  /** The copy button of the command. */
+  copy: string;
+  /** What the copy button says once the command is copied. */
+  copied: string;
+  /** The download button. */
+  download: string;
+}
+
+/** Props of {@link VideoResult}. */
+export interface VideoResultProps {
+  /** The accessible name of the video: what it shows, in a sentence. */
+  title: string;
+  /** The files: H.264 `mp4` (always), `webm` when there is one, and the poster. */
+  sources: ClipSources;
+  /** The frame the clip was made in; a portrait one is drawn as tall as a phone allows, a landscape one 16:9. */
+  orientation?: "landscape" | "portrait";
+  /** The exact prompt that reached the model. */
+  prompt: string;
+  /** Replaces the plain prompt (the app may type it in, over its final size): the heading stays. */
+  promptNode?: React.ReactNode;
+  /** What the run recorded, in reading order (model, seed, frame, length, time, cost, run id). */
+  facts: readonly VideoResultFact[];
+  /** The CLI command that makes the clip again; without it there is no "Reproduce it". */
+  reproduce?: string;
+  /** One sentence above the command. */
+  reproduceLead?: string;
+  /** Where the file can be downloaded; without it there is no download button. */
+  downloadHref?: string;
+  /** The words. */
+  labels: VideoResultLabels;
+  /** Extra classes on the root, merged last. */
+  className?: string;
+}
+
+const heading = "font-mono text-xs font-semibold uppercase tracking-[0.14em] text-fg-accent";
+
+/**
+ * The result of a video run: the player (a muted loop in view, badge, controls, opens larger), the prompt, the facts,
+ * "Reproduce it" and the download.
+ *
+ * @param props - {@link VideoResultProps}
+ * @returns The result card of a video run.
+ */
+export function VideoResult({
+  title,
+  sources,
+  orientation = "landscape",
+  prompt,
+  promptNode,
+  facts,
+  reproduce,
+  reproduceLead,
+  downloadHref,
+  labels,
+  className,
+}: Readonly<VideoResultProps>) {
+  return (
+    <article className={cn("space-y-5", className)} data-orientation={orientation}>
+      <figure className="overflow-hidden rounded-2xl border border-border-default bg-surface-2">
+        <ClipPlayer sources={sources} title={title} labels={labels} orientation={orientation} />
+      </figure>
+      <section aria-label={labels.prompt} className="space-y-2">
+        <h3 className={heading}>{labels.prompt}</h3>
+        {promptNode ?? (
+          <blockquote lang="en" className="text-sm leading-relaxed text-fg-secondary">
+            {prompt}
+          </blockquote>
+        )}
+      </section>
+      <section aria-label={labels.facts} className="space-y-2">
+        <h3 className={heading}>{labels.facts}</h3>
+        <RunFacts facts={facts} />
+      </section>
+      {reproduce && (
+        <section aria-label={labels.reproduce} className="space-y-2">
+          <h3 className={heading}>{labels.reproduce}</h3>
+          {reproduceLead && <p className="text-xs leading-relaxed text-fg-secondary">{reproduceLead}</p>}
+          <CodeBlock
+            code={reproduce}
+            language="bash"
+            file="Terminal"
+            copyLabel={labels.copy}
+            copiedLabel={labels.copied}
+          />
+        </section>
+      )}
+      {downloadHref && (
+        <Button asChild variant="secondary" size="md">
+          <a href={downloadHref} download>
+            {labels.download}
+          </a>
+        </Button>
+      )}
+    </article>
+  );
+}

package/src/components/badge.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Badge",
+  summary: "The @krizaka/ui badge with the 1.x `variant` kept as a deprecated alias of `tone`.",
+  why: "Sovkora 1.x badges took `variant` (`default`, `success`…); the platform says `tone`. This adapter maps one onto the other so the apps keep working while they migrate.",
+  status: "stable",
+  category: "data-display",
+  platforms: "web",
+  builtOn: ["ui/badge"],
+  whenToUse: [
+    "In code already importing `Badge` from `@krizaka/sovkora-design-system`: a model's state, a job's status.",
+  ],
+  whenNotToUse: [{ when: "In new code: import `Badge` from `@krizaka/ui/badge` and write `tone`.", use: "ui/badge" }],
+  bestPractices: [
+    "Write `tone`, not `variant` (deprecated since 2.0; `default` → `neutral`).",
+    "One or two words: `Local`, `Running`, `Failed`.",
+  ],
+  accessibility: {
+    keyboard: [],
+    notes: ["The primitive's: a `<span>` read with its content; the colour is never the only signal."],
+  },
+  related: ["ui/badge"],
+  web: {
+    imports: ["Badge"],
+    examples: [
+      {
+        name: "model-state",
+        title: "A model's state",
+        description: "Local, loading, failed — the tones of the primitive.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;