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

package/src/components/button.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Button",
+  summary:
+    "The @krizaka/ui button with the Sovkora 1.x default kept: without a `variant`, it is the primary (orange) button.",
+  why: "Sovkora 1.x buttons were primary by default; the platform's default is `secondary`. This adapter keeps the 1.x default so the apps written against it look the same — everything else is the primitive's.",
+  status: "stable",
+  category: "actions",
+  platforms: "web",
+  builtOn: ["ui/button"],
+  whenToUse: ["In code already importing `Button` from `@krizaka/sovkora-design-system`."],
+  whenNotToUse: [
+    { when: "In new code: import `Button` from `@krizaka/ui/button` and say the variant.", use: "ui/button" },
+  ],
+  bestPractices: [
+    'One primary action per view: pass `variant="secondary"` or `"ghost"` to the others.',
+    "Lock it while sending (`disabled` + `loading`): the input-blocking rule (ERR-126).",
+  ],
+  accessibility: {
+    keyboard: [],
+    notes: ["The primitive's: a native `<button>`, its focus ring, `loading` sets `aria-busy`."],
+  },
+  related: ["ui/button", "icon"],
+  web: {
+    imports: ["Button"],
+    examples: [
+      {
+        name: "send",
+        title: "Send a prompt",
+        description: "The primary by default; locked while the answer is generated.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/chat-showcase.css.ts

@@ -0,0 +1,19 @@
+/** The showcase's own keyframes (the pulse, the typing dots, the caret), all stopped under reduced motion. */
+export const CHAT_SHOWCASE_CSS = `
+        @keyframes kzc-pulse {
+          0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--kz-success) 55%, transparent); }
+          70%, 100% { box-shadow: 0 0 0 6px color-mix(in srgb, var(--kz-success) 0%, transparent); }
+        }
+        @keyframes kzc-typing {
+          0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
+          30% { transform: translateY(-4px); opacity: 1; }
+        }
+        @keyframes kzc-blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
+        .kzc-dot { animation: kzc-pulse 2s ease-out infinite; }
+        .kzc-typing { animation: kzc-typing 1.1s ease-in-out infinite; }
+        .kzc-typing:nth-child(2) { animation-delay: 0.18s; } .kzc-typing:nth-child(3) { animation-delay: 0.36s; }
+        .kzc-caret { animation: kzc-blink 1s steps(2) infinite; }
+        @media (prefers-reduced-motion: reduce) {
+          .kzc-dot, .kzc-typing, .kzc-caret { animation: none; }
+        }
+      `;

package/src/components/chat-showcase.meta.ts

@@ -0,0 +1,50 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Chat showcase",
+  summary:
+    "A self-playing sovereign AI chat: a question, the answer typed out, the interceptor pipeline it went through, and the promise that nothing left the premises.",
+  why: "Sovkora sells one idea — your AI answers on your own machines, through a deterministic pipeline, with zero data egress. A chat bubble from @krizaka/ui cannot tell that story; this composite stages it the same way on the website, the client app and the console: the persona asks, the engine answers locally, the pipeline chips land, the privacy line closes.",
+  status: "stable",
+  category: "data-display",
+  platforms: "web",
+  builtOn: [],
+  whenToUse: [
+    "On a home or a product page, to show what Sovkora does in one glance.",
+    "In an empty state of the chat (first visit), as a demonstration before the first question.",
+  ],
+  whenNotToUse: [
+    { when: "For a real conversation: this is a scripted mockup, not a chat." },
+    { when: "For a short status of the engine (online, model).", use: "ui/badge" },
+  ],
+  bestPractices: [
+    'Speak as a named persona with a real need ("Eric, finance lead"), never an admin or a test account.',
+    "The pipeline names steps the reader understands (`PII masked`, `Routed locally`), not class names.",
+    "Every word is a prop (`labels`, `question`, `answer`, `pipeline`): the app translates them.",
+    "One per page: it moves, and two moving mockups compete.",
+  ],
+  accessibility: {
+    keyboard: [],
+    notes: [
+      '`role="img"` with the question and the answer as its name: a screen reader hears the exchange once, not the typing.',
+      "Under `prefers-reduced-motion` the final state shows at once: no typing, no pulse, no caret.",
+      "The composer is the kit's `MessageComposer` (pill), `inert` and `aria-hidden`: it is the same component as the app's chat, not a field here.",
+    ],
+  },
+  related: ["icon", "sentinel-mini", "ui/card"],
+  web: {
+    imports: ["ChatShowcase"],
+    examples: [
+      {
+        name: "sovereign-answer",
+        title: "A sovereign answer",
+        description: "Eric asks about a contract; the answer is computed on premises and the pipeline shows the steps.",
+      },
+      {
+        name: "french",
+        title: "In the reader's language",
+        description: "The same mockup with the words of another locale — every word is a prop.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/clip-player.meta.ts

@@ -0,0 +1,48 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Clip player",
+  summary:
+    "A short clip that is plainly a clip: a muted loop that plays in view, a badge with its length, play/pause and sound buttons, and a click that opens it larger.",
+  why: "A 5-second generated clip is shown as a loop, not as a video page: it must read as a video at a glance (badge), play by itself only while it is on screen, stay quiet, give the visitor the controls on hover and focus, and open large with the native controls. @krizaka/ui's player is built for long videos; this one is the product's way to show a result.",
+  status: "beta",
+  category: "data-display",
+  platforms: "web",
+  builtOn: ["ui/button", "ui/dialog"],
+  whenToUse: [
+    "A generated clip of a few seconds in a gallery, a result page or a card.",
+    "Anywhere a loop must start and stop with the viewport and respect reduced motion.",
+  ],
+  whenNotToUse: [
+    { when: "A long video, subtitles, chapters or streaming.", use: "ui/video-player" },
+    { when: "A decorative background loop with no controls: a muted `<video>` is enough." },
+  ],
+  bestPractices: [
+    "Give both files: `webm` is tried first, `mp4` is the fallback every browser reads.",
+    "Give the poster: it is what reduced motion and the first paint show.",
+    "Name the clip in a sentence (`title`): it is the video's accessible name and the dialog's title.",
+  ],
+  accessibility: {
+    keyboard: [
+      { keys: "Tab", action: "Reaches the frame (open larger), play/pause and sound." },
+      { keys: "Enter / Space", action: "Activates the focused button." },
+      { keys: "Escape", action: "Closes the large view." },
+    ],
+    notes: [
+      "Nothing plays by itself under `prefers-reduced-motion`: the poster and a play button.",
+      "The clip is muted and `playsInline`; the sound button is a toggle (`aria-pressed`).",
+      "A pause by hand sticks: scrolling away and back does not restart it.",
+    ],
+  },
+  related: ["video-result", "run-facts", "ui/video-player"],
+  web: {
+    imports: ["ClipPlayer"],
+    examples: [
+      {
+        name: "tea-pour",
+        title: "A loop in a card",
+        description: "Eric's tea-pour shot: badge, controls on hover, opens larger on click.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/command-palette.meta.ts

@@ -0,0 +1,47 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Command palette",
+  summary:
+    "The Sovkora ⌘K palette: jump to a studio, a chat, a setting — sections, registry icons and a footer of hints, on the platform's command dialog.",
+  why: "`CommandDialog` from @krizaka/ui gives the combobox, the filtering, the focus trap and Escape. Sovkora adds what is its own: the ⌘K / Ctrl+K shortcut, entries grouped by section with the Sovkora icon registry, and the footer of keyboard hints its consoles share.",
+  status: "stable",
+  category: "navigation",
+  platforms: "web",
+  builtOn: ["ui/command", "ui/kbd", "ui/dialog"],
+  whenToUse: [
+    "Once per app shell: the client app and the console, for power users who navigate by keyboard.",
+    "To reach an action that has no place in the navigation (new chat, switch theme).",
+  ],
+  whenNotToUse: [
+    { when: "As the only way to reach a page: everything stays reachable from the navigation." },
+    { when: "For a search over content (documents, conversations) with results to read.", use: "ui/command" },
+  ],
+  bestPractices: [
+    "Pass `commands` and `labels` translated (both required since 3.0).",
+    "Give `onNavigate` outside Next.js (or in tests); inside, it uses the router.",
+    "Short labels, verbs for actions (`New chat`), nouns for places (`Studios`).",
+  ],
+  accessibility: {
+    keyboard: [
+      { keys: "⌘ K / Ctrl K", action: "Opens and closes the palette." },
+      { keys: "↑ ↓", action: "Moves through the results." },
+      { keys: "Enter", action: "Runs the highlighted entry." },
+      { keys: "Esc", action: "Closes it and returns the focus." },
+    ],
+    notes: [
+      "A dialog with a combobox and a listbox (cmdk on Radix): named by `labels.label`, results by `labels.results`.",
+    ],
+  },
+  related: ["icon", "ui/command", "ui/kbd"],
+  web: {
+    imports: ["CommandPalette"],
+    examples: [
+      {
+        name: "workspace",
+        title: "Eric's workspace",
+        description: "Studios, chats and settings, opened with ⌘K or the button.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/icon.meta.ts

@@ -0,0 +1,45 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Icon",
+  summary:
+    "The Sovkora icon registry: one `Icon` component and a typed `name` for every product concept — studios, models, the pipeline, RAG, MCP.",
+  why: "Sovkora's screens name AI concepts (a router, a refiner, a memory, a cost shield) that no generic set draws. The contract centralises them in one registry, so an app never imports an icon library directly and every concept has one picture across the client, the console and the website.",
+  status: "stable",
+  category: "foundations",
+  platforms: "web",
+  builtOn: [],
+  whenToUse: [
+    "Every icon of an Sovkora screen: navigation, buttons, lists, the palette.",
+    "A concept of the engine (model, pipeline, router) shown next to its name.",
+  ],
+  whenNotToUse: [
+    { when: "For a Krizaka platform concept on the website (the signature set): use @krizaka/icons." },
+    { when: "As the product's logo: use `SovkoraLogo` from @krizaka/ui." },
+  ],
+  bestPractices: [
+    "Never import lucide or another set in an app: add the icon to the registry.",
+    "An icon-only button carries an `aria-label` (`IconButton` from @krizaka/ui requires one).",
+    "Colour through the text role (`text-fg-secondary`, `text-accent`): the strokes are `currentColor`.",
+  ],
+  accessibility: {
+    keyboard: [],
+    notes: ["Decorative by default (`aria-hidden`): the text or the button around it names it."],
+  },
+  related: ["command-palette", "sentinel-mini", "ui/button"],
+  web: {
+    imports: ["Icon"],
+    examples: [
+      {
+        name: "engine",
+        title: "The engine's concepts",
+        description: "Router, pipeline, model, RAG, memory, MCP — the vocabulary of Sovkora.",
+      },
+      {
+        name: "in-a-button",
+        title: "In a button",
+        description: "An icon beside a label, coloured by the button's role.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/run-facts.meta.ts

@@ -0,0 +1,32 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Run facts",
+  summary: "What a run recorded, as a description list: label left, value right, in mono.",
+  why: "Sovkora shows what proves a result — model, seed, frame, length, time, cost, run id — the same way everywhere. A long id breaks instead of overflowing, so the same list reads on a phone and in a wide card.",
+  status: "beta",
+  category: "data-display",
+  platforms: "web",
+  builtOn: [],
+  whenToUse: [
+    "Under a generated result (a clip, an image) to say how it was made.",
+    "In a run's detail, beside its steps.",
+  ],
+  whenNotToUse: [{ when: "Many rows to compare side by side." }],
+  bestPractices: [
+    "Say the real source (`Made by`, `Run by`), never a flattering one.",
+    "Values are as the run recorded them: never rounded to look better.",
+  ],
+  accessibility: { keyboard: [], notes: ["A `dl`: a screen reader reads each label with its value."] },
+  related: ["video-result", "clip-player"],
+  web: {
+    imports: ["RunFacts"],
+    examples: [
+      {
+        name: "clip-run",
+        title: "The run of a clip",
+        description: "Model, seed, frame, length and the run id of Eric's tea-pour shot.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/sentinel-mini.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Sentinel mini",
+  summary:
+    "The Sentinel, Sovkora's guardian, at 24 px: a core, a ring and an orbit in the accent — for a sidebar, a header, a loading corner.",
+  why: "The Sovkora mark (`SovkoraLogo`, @krizaka/ui) signs the product; the Sentinel stands for what watches over the requests — the interceptors. It is drawn once here, in the accent role, so it follows the brand and every named theme.",
+  status: "stable",
+  category: "foundations",
+  platforms: "web",
+  builtOn: [],
+  whenToUse: [
+    "Next to a section that the governance watches (the console's pipeline, the audit trail).",
+    "As a small brand accent in a dense sidebar where the mark would be too much.",
+  ],
+  whenNotToUse: [
+    { when: "As the product's logo: use `SovkoraLogo` from @krizaka/ui." },
+    { when: "As a loading indicator.", use: "ui/spinner" },
+  ],
+  bestPractices: [
+    "Decorative: put it next to a text that says what it means.",
+    "Keep it small (16–32 px): its strokes are drawn for that size.",
+  ],
+  accessibility: {
+    keyboard: [],
+    notes: ["`aria-hidden`: decorative.", "Strokes and fills read `--kz-accent`: it follows the theme."],
+  },
+  related: ["chat-showcase", "icon", "ui/mascots"],
+  web: {
+    imports: ["SentinelMini"],
+    examples: [
+      {
+        name: "sidebar",
+        title: "In a sidebar heading",
+        description: "Beside the name of the section the governance watches.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/skeleton.meta.ts

@@ -0,0 +1,42 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Skeleton",
+  summary:
+    "The @krizaka/ui skeleton (default shape `rect`) with the 1.x shorthands, and `SkeletonGroup` — a paragraph of text lines.",
+  why: "Sovkora 1.x sized skeletons with `width` / `height` and chose the shape with `variant`; this adapter keeps them (deprecated) on the primitive, and adds `SkeletonGroup`, the paragraph its chat and document views wait on.",
+  status: "stable",
+  category: "feedback",
+  platforms: "web",
+  builtOn: ["ui/skeleton"],
+  whenToUse: [
+    "While an answer, a document or a list loads: the shape of what is coming.",
+    "`SkeletonGroup` for a paragraph (an answer being prepared).",
+  ],
+  whenNotToUse: [
+    {
+      when: "In new code for a single block: import `Skeleton` from `@krizaka/ui/skeleton` and size it with `className`.",
+      use: "ui/skeleton",
+    },
+    { when: "For an action in progress (a button, a send).", use: "ui/spinner" },
+  ],
+  bestPractices: [
+    "Size with `className` (`h-4 w-32`), not `width` / `height` (deprecated).",
+    "Match the layout that replaces it, so nothing jumps.",
+  ],
+  accessibility: {
+    keyboard: [],
+    notes: ["Hidden from assistive technology: announce the loading state elsewhere (`aria-busy` on the region)."],
+  },
+  related: ["ui/skeleton", "ui/spinner"],
+  web: {
+    imports: ["Skeleton", "SkeletonGroup"],
+    examples: [
+      {
+        name: "answer-loading",
+        title: "An answer loading",
+        description: "The avatar and three lines while the engine prepares the answer.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;

package/src/components/video-result.meta.ts

@@ -0,0 +1,53 @@
+import type { ComponentMeta } from "../meta";
+
+export const meta = {
+  title: "Video result",
+  summary:
+    "What a video run of a Studio leaves: the clip in its player (a muted loop in view, badge, controls, opens larger), the exact prompt, what the run recorded, the command that makes it again, and a download.",
+  why: "Sovkora's promise is that a result is proven, not claimed: a generated clip comes with its prompt, its model, its seed, its frame, its length, its time, its cost and the id of the run that made it, and says how to make it again. @krizaka/ui has the player and the code block; this composite is the product's way of showing a run's result once, the same on every screen.",
+  status: "beta",
+  category: "data-display",
+  platforms: "web",
+  builtOn: ["ui/code-block", "ui/button"],
+  whenToUse: [
+    "On the page of a finished run of a video Studio, in the console and in the gallery of a site.",
+    "Anywhere a generated clip must come with what proves where it came from.",
+  ],
+  whenNotToUse: [
+    { when: "For a short looping accent with no words: a muted `<video>` that plays in view is enough." },
+    { when: "For a clip the visitor must control in depth (subtitles, speed, chapters).", use: "ui/video-player" },
+  ],
+  bestPractices: [
+    "Say the real source in the facts (`Made by DigitalOcean serverless inference · run by Sovkora`), never a flattering one.",
+    "Give the frame the clip was really made in (`orientation`), never crop a landscape clip into a portrait one.",
+    "Every word is a prop (`labels`, `facts`): the app translates them; the prompt stays as the model received it.",
+  ],
+  accessibility: {
+    keyboard: [
+      { keys: "Enter / Space", action: "Activates the focused button: open larger, play or pause, sound." },
+      { keys: "Tab", action: "Moves through the player controls, the copy button and the download link." },
+    ],
+    notes: [
+      "The video is named (`title`); it is a muted loop that plays only in view, never under reduced motion (poster and a play button).",
+      "The facts are a description list; the command is a code block with a polite copy confirmation.",
+      'The prompt is marked `lang="en"`: it is what the model received, whatever the page\'s language.',
+    ],
+  },
+  related: ["clip-player", "run-facts", "ui/video-player", "ui/code-block"],
+  web: {
+    imports: ["VideoResult"],
+    examples: [
+      {
+        name: "tea-pour",
+        title: "A landscape clip with its run",
+        description:
+          "Eric's tea-pour shot: the poster, the prompt, the facts of the run, the command and the download.",
+      },
+      {
+        name: "assistant",
+        title: "A clip without its command",
+        description: "The player, the prompt and the facts of the run; no command, no download.",
+      },
+    ],
+  },
+} satisfies ComponentMeta;