@cyberskill/design 1.0.0

package/components/ai/ChatMessage.d.ts

@@ -0,0 +1,17 @@
+import type * as React from "react";
+import type { ReactNode } from "react";
+
+/**
+ * A single conversation turn with Lumi. role "lumi" (Ochre genie avatar,
+ * left) or "user" (Umber, right). Override the avatar with the real mascot
+ * image where available.
+ */
+export interface ChatMessageProps {
+  role?: "lumi" | "user";
+  name?: ReactNode;
+  avatar?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+}
+
+export function ChatMessage(props: ChatMessageProps): React.ReactElement;

package/components/ai/ChatMessage.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { ChatMessage } from './ChatMessage.jsx'
+
+/**
+ * Code Connect stub — ChatMessage
+ * Prop maps stay minimal until the matching Figma library component is published;
+ * then set nodeId in code-connect/node-map.json and re-run generate-code-connect.
+ */
+figma.connect(ChatMessage, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-16', {
+  example: () => <ChatMessage />,
+  imports: ["import { ChatMessage } from '@cyberskill/design'"],
+})

package/components/ai/ChatMessage.jsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { cx } from "../_utils/cx.js";
+
+/**
+ * CyberSkill ChatMessage — one turn in a Lumi conversation. role "lumi" (genie,
+ * Ochre avatar) or "user" (Umber, right-aligned). Pass `avatar` to override.
+ */
+export function ChatMessage({ role = "lumi", name, avatar, children, className }) {
+  const isUser = role === "user";
+  const defaultAvatar = isUser
+    ? <span aria-hidden="true">You</span>
+    : <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.9" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d="M12 3l1.8 5.4L19 10l-5.2 1.6L12 17l-1.8-5.4L5 10l5.2-1.6z" /></svg>;
+  return (
+    <div className={cx("cs-chat-msg", isUser ? "cs-chat-msg--user" : "cs-chat-msg--lumi", className)}>
+      <div className="cs-chat-msg__avatar">{avatar ?? defaultAvatar}</div>
+      <div className="cs-chat-msg__col">
+        <div className="cs-chat-msg__name">{name ?? (isUser ? "You" : "Lumi")}</div>
+        <div className="cs-chat-msg__bubble">{children}</div>
+      </div>
+    </div>
+  );
+}

package/components/ai/ChatMessage.prompt.md

@@ -0,0 +1,8 @@
+**ChatMessage** — one turn in a Lumi conversation. `role="lumi"` (Ochre genie, left) or `role="user"` (Umber, right). Override `avatar` with the real mascot image where you have it.
+
+```jsx
+<div className="cs-chat">
+  <ChatMessage role="lumi">Tell me a wish, and I'll share plain advice first.</ChatMessage>
+  <ChatMessage role="user">A faster checkout.</ChatMessage>
+</div>
+```

package/components/ai/CitationList.d.ts

@@ -0,0 +1,13 @@
+import type * as React from "react";
+import type { ReactNode } from "react";
+
+export interface Citation { title: ReactNode; source?: ReactNode; href?: string; }
+
+/** Numbered provenance list for AI output — pairs with AIDisclosureBadge to show
+ *  what a response was grounded in. Rows link out when href is set. */
+export interface CitationListProps {
+  label?: ReactNode;
+  items: Citation[];
+  className?: string;
+}
+export function CitationList(props: CitationListProps): React.ReactElement;

package/components/ai/CitationList.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { CitationList } from './CitationList.jsx'
+
+/**
+ * Code Connect stub — CitationList
+ * Prop maps stay minimal until the matching Figma library component is published;
+ * then set nodeId in code-connect/node-map.json and re-run generate-code-connect.
+ */
+figma.connect(CitationList, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-18', {
+  example: () => <CitationList />,
+  imports: ["import { CitationList } from '@cyberskill/design'"],
+})

package/components/ai/CitationList.jsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { cx } from "../_utils/cx.js";
+
+/** CyberSkill CitationList — numbered provenance sources for AI output. Rows link out when href is set. */
+export function CitationList({ label = "Sources", items = [], className }) {
+  return (
+    <div className={cx("cs-citations", className)}>
+      {label ? <div className="cs-citations__label">{label}</div> : null}
+      {items.map((it, i) => {
+        const inner = (
+          <>
+            <span className="cs-citation__num">{i + 1}</span>
+            <span className="cs-citation__text">{it.title}{it.source ? <span className="cs-citation__src"> · {it.source}</span> : null}</span>
+          </>
+        );
+        return it.href
+          ? <a key={i} className="cs-citation" href={it.href} target="_blank" rel="noreferrer">{inner}</a>
+          : <div key={i} className="cs-citation">{inner}</div>;
+      })}
+    </div>
+  );
+}

package/components/ai/CitationList.prompt.md

@@ -0,0 +1,5 @@
+**CitationList** — numbered provenance sources for AI output (pairs with AIDisclosureBadge).
+
+```jsx
+<CitationList items={[{title:"release-notes.md"},{title:"Task backlog",source:"Status Hub",href:"#"}]} />
+```

package/components/ai/ConfidenceMeter.d.ts

@@ -0,0 +1,17 @@
+import type * as React from "react";
+import type { ReactNode } from "react";
+
+/**
+ * Segmented AI-confidence indicator. Pass a numeric `value` 0–1 or a `level`.
+ * The level is always spelled out in words next to the bar — never colour alone.
+ * Pair with AIDisclosureBadge / HumanReviewGate for full provenance.
+ */
+export interface ConfidenceMeterProps {
+  value?: number;
+  level?: "low" | "medium" | "high";
+  segments?: number;
+  label?: ReactNode;
+  className?: string;
+}
+
+export function ConfidenceMeter(props: ConfidenceMeterProps): React.ReactElement;

package/components/ai/ConfidenceMeter.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { ConfidenceMeter } from './ConfidenceMeter.jsx'
+
+/**
+ * Code Connect stub — ConfidenceMeter
+ * Prop maps stay minimal until the matching Figma library component is published;
+ * then set nodeId in code-connect/node-map.json and re-run generate-code-connect.
+ */
+figma.connect(ConfidenceMeter, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-24', {
+  example: () => <ConfidenceMeter />,
+  imports: ["import { ConfidenceMeter } from '@cyberskill/design'"],
+})

package/components/ai/ConfidenceMeter.jsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+const TONE = {
+  low: { color: "var(--cs-color-semantic-danger)", label: "Low", fill: 2 },
+  medium: { color: "var(--cs-color-semantic-warning)", label: "Medium", fill: 3 },
+  high: { color: "var(--cs-color-semantic-success)", label: "High", fill: 5 },
+};
+
+/**
+ * CyberSkill ConfidenceMeter — segmented AI-confidence indicator. Pass a numeric
+ * `value` 0–1, or a `level` ("low"|"medium"|"high"). Confidence is stated in
+ * words too, never colour alone — pair with AIDisclosureBadge / HumanReviewGate.
+ */
+export function ConfidenceMeter({ value, level, segments = 5, label, lang, className }) {
+  let tone, filled;
+  if (value != null) {
+    tone = value < 0.4 ? "low" : value < 0.75 ? "medium" : "high";
+    filled = Math.max(1, Math.round(value * segments));
+  } else {
+    tone = level || "medium";
+    filled = Math.round((TONE[tone].fill / 5) * segments);
+  }
+  const meta = TONE[tone];
+  const [ref, L] = useLang(lang);
+  const t = makeT("ConfidenceMeter", L);
+  const lbl = label != null ? label : t("label");
+  const levelText = t(tone);
+  return (
+    <div ref={ref} className={cx("cs-confidence", className)}>
+      <div className="cs-confidence__head">
+        <span>{lbl}</span>
+        <span className="cs-confidence__level" style={{ color: meta.color }}>{levelText}</span>
+      </div>
+      <div className="cs-confidence__track" role="meter" aria-valuemin={0} aria-valuemax={segments} aria-valuenow={filled} aria-label={lbl + ": " + levelText}>
+        {Array.from({ length: segments }).map((_, i) => (
+          <span key={i} className="cs-confidence__seg" style={i < filled ? { background: meta.color } : undefined} />
+        ))}
+      </div>
+    </div>
+  );
+}

package/components/ai/ConfidenceMeter.prompt.md

@@ -0,0 +1,6 @@
+**ConfidenceMeter** — segmented AI-confidence indicator. Pass `value` 0–1 or a `level`; the level is always spelled out (never colour alone). Pair with AIDisclosureBadge / HumanReviewGate.
+
+```jsx
+<ConfidenceMeter value={0.82} />
+<ConfidenceMeter level="low" label="Model confidence" />
+```

package/components/ai/HumanReviewGate.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+import type * as React from "react";
+
+/**
+ * AI-native human-in-the-loop checkpoint: warning-bordered card with a risk
+ * label, plain-language summary, optional reviewer, and Approve / Reject
+ * actions. Risk is never communicated by colour alone.
+ */
+export interface HumanReviewGateProps {
+  risk?: ReactNode;
+  summary: ReactNode;
+  reviewer?: ReactNode;
+  approveLabel?: string;
+  rejectLabel?: string;
+  className?: string;
+  onApprove?: () => void;
+  onReject?: () => void;
+}
+
+export function HumanReviewGate(props: HumanReviewGateProps): React.ReactElement;

package/components/ai/HumanReviewGate.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { HumanReviewGate } from './HumanReviewGate.jsx'
+
+/**
+ * Code Connect stub — HumanReviewGate
+ * Prop maps stay minimal until the matching Figma library component is published;
+ * then set nodeId in code-connect/node-map.json and re-run generate-code-connect.
+ */
+figma.connect(HumanReviewGate, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-41', {
+  example: () => <HumanReviewGate />,
+  imports: ["import { HumanReviewGate } from '@cyberskill/design'"],
+})

package/components/ai/HumanReviewGate.jsx

@@ -0,0 +1,37 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+/**
+ * CyberSkill HumanReviewGate — an AI-native checkpoint: a risk label, a
+ * plain-language summary, an optional reviewer, and Approve / Reject actions.
+ * Keeps a human in the loop before a high-stakes AI action proceeds.
+ */
+export function HumanReviewGate({
+  risk,
+  summary,
+  reviewer,
+  onApprove,
+  onReject,
+  approveLabel,
+  rejectLabel,
+  lang,
+  className,
+}) {
+  const [ref, L] = useLang(lang);
+  const t = makeT("HumanReviewGate", L);
+  const rk = risk != null ? risk : t("risk");
+  const al = approveLabel != null ? approveLabel : t("approve");
+  const rl = rejectLabel != null ? rejectLabel : t("reject");
+  return (
+    <section ref={ref} className={cx("cs-review-gate", className)} aria-label={t("aria")}>
+      <div className="cs-review-gate__risk">{rk}</div>
+      <p className="cs-review-gate__summary">{summary}</p>
+      {reviewer ? <p className="cs-review-gate__reviewer">{t("reviewer")}: {reviewer}</p> : null}
+      <div className="cs-review-gate__actions">
+        <button type="button" className="cs-button cs-button--secondary" onClick={onReject}>{rl}</button>
+        <button type="button" className="cs-button cs-button--primary" onClick={onApprove}>{al}</button>
+      </div>
+    </section>
+  );
+}

package/components/ai/HumanReviewGate.prompt.md

@@ -0,0 +1,13 @@
+**HumanReviewGate** — an AI-native checkpoint that keeps a human in the loop before a high-stakes action. Warning-bordered card with a risk label, plain-language summary, optional reviewer, and Approve / Reject.
+
+```jsx
+<HumanReviewGate
+  risk="High-stakes · billing change"
+  summary="Lumi proposes moving this client to the annual plan and issuing a prorated credit."
+  reviewer="Ops on call"
+  onApprove={apply}
+  onReject={dismiss}
+/>
+```
+
+- Risk is stated in words, never colour alone. Pair with `AIDisclosureBadge` for full provenance.

package/components/ai/PromptInput.d.ts

@@ -0,0 +1,21 @@
+import type * as React from "react";
+import type { ReactNode } from "react";
+
+/**
+ * AI-native prompt box (the "make a wish" input). Enter submits, Shift+Enter
+ * newlines. Controlled via value/onChange or uncontrolled. Keep the disclosure
+ * hint — it tells users a human reviews clear wishes.
+ */
+export interface PromptInputProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  onSubmit?: (value: string) => void;
+  placeholder?: string;
+  sendLabel?: string;
+  hint?: ReactNode;
+  disabled?: boolean;
+  busy?: boolean;
+  className?: string;
+}
+
+export function PromptInput(props: PromptInputProps): React.ReactElement;

package/components/ai/PromptInput.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { PromptInput } from './PromptInput.jsx'
+
+/**
+ * Code Connect stub — PromptInput
+ * Prop maps stay minimal until the matching Figma library component is published;
+ * then set nodeId in code-connect/node-map.json and re-run generate-code-connect.
+ */
+figma.connect(PromptInput, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-62', {
+  example: () => <PromptInput />,
+  imports: ["import { PromptInput } from '@cyberskill/design'"],
+})

package/components/ai/PromptInput.jsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+/**
+ * CyberSkill PromptInput — the AI-native ask box. Enter submits (Shift+Enter =
+ * newline). Works controlled (value/onChange) or uncontrolled. The hint states
+ * that Lumi replies, then hands clear wishes to a human — keep that disclosure.
+ */
+export function PromptInput({
+  value, onChange, onSubmit,
+  placeholder,
+  sendLabel,
+  hint,
+  lang,
+  disabled = false, busy = false, className,
+}) {
+  const [inner, setInner] = React.useState("");
+  const val = value != null ? value : inner;
+  const setVal = (v) => (onChange ? onChange(v) : setInner(v));
+  const submit = () => { if (!disabled && !busy && String(val).trim()) onSubmit && onSubmit(val); };
+  const [ref, L] = useLang(lang);
+  const t = makeT("PromptInput", L);
+  const ph = placeholder != null ? placeholder : t("placeholder");
+  const sl = sendLabel != null ? sendLabel : t("send");
+  const ht = hint !== undefined ? hint : t("hint");
+  return (
+    <div ref={ref} className={cx("cs-prompt", className)}>
+      <textarea
+        className="cs-prompt__field" rows={1} value={val} placeholder={ph} disabled={disabled}
+        onChange={(e) => setVal(e.target.value)}
+        onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); submit(); } }}
+      />
+      <div className="cs-prompt__bar">
+        {ht ? (
+          <span className="cs-prompt__hint">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d="M12 3l1.8 5.4L19 10l-5.2 1.6L12 17l-1.8-5.4L5 10l5.2-1.6z" /></svg>
+            {ht}
+          </span>
+        ) : null}
+        <button type="button" className="cs-button cs-button--primary cs-button--sm" onClick={submit} disabled={disabled || busy}>
+          {busy ? <span className="cs-button__spinner" aria-hidden="true" /> : null}
+          {sl}
+        </button>
+      </div>
+    </div>
+  );
+}

package/components/ai/PromptInput.prompt.md

@@ -0,0 +1,5 @@
+**PromptInput** — the AI-native "make a wish" box. Enter submits, Shift+Enter newlines; controlled or uncontrolled. Keep the disclosure `hint` (a human reviews clear wishes).
+
+```jsx
+<PromptInput value={q} onChange={setQ} onSubmit={send} placeholder="Make a wish…" />
+```

package/components/ai/PromptSuggestions.d.ts

@@ -0,0 +1,12 @@
+import type * as React from "react";
+import type { ReactNode } from "react";
+
+export type PromptSuggestion = string | { label: string; icon?: ReactNode };
+
+/** Tappable "wish" starter chips shown above/inside a PromptInput or chat. */
+export interface PromptSuggestionsProps {
+  suggestions: PromptSuggestion[];
+  onSelect?: (label: string) => void;
+  className?: string;
+}
+export function PromptSuggestions(props: PromptSuggestionsProps): React.ReactElement;

package/components/ai/PromptSuggestions.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { PromptSuggestions } from './PromptSuggestions.jsx'
+
+/**
+ * Code Connect stub — PromptSuggestions
+ * Prop maps stay minimal until the matching Figma library component is published;
+ * then set nodeId in code-connect/node-map.json and re-run generate-code-connect.
+ */
+figma.connect(PromptSuggestions, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-63', {
+  example: () => <PromptSuggestions />,
+  imports: ["import { PromptSuggestions } from '@cyberskill/design'"],
+})

package/components/ai/PromptSuggestions.jsx

@@ -0,0 +1,20 @@
+import React from "react";
+import { cx } from "../_utils/cx.js";
+
+/** CyberSkill PromptSuggestions — tappable "wish" starter chips for a chat/prompt. */
+export function PromptSuggestions({ suggestions = [], onSelect, className }) {
+  return (
+    <div className={cx("cs-suggest", className)}>
+      {suggestions.map((s, i) => {
+        const label = typeof s === "string" ? s : s.label;
+        const icon = typeof s === "string" ? null : s.icon;
+        return (
+          <button key={i} type="button" onClick={() => onSelect && onSelect(label)}>
+            {icon ?? <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d="M12 3l1.8 5.4L19 10l-5.2 1.6L12 17l-1.8-5.4L5 10l5.2-1.6z" /></svg>}
+            {label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/components/ai/PromptSuggestions.prompt.md

@@ -0,0 +1,5 @@
+**PromptSuggestions** — tappable "wish" starter chips for a prompt/chat.
+
+```jsx
+<PromptSuggestions suggestions={["A web app","An internal tool","A design system"]} onSelect={send} />
+```

package/components/ai/TypingIndicator.d.ts

@@ -0,0 +1,9 @@
+import type * as React from "react";
+
+/** Three animated dots in a bubble — shown while Lumi composes a reply. Freezes
+ *  under reduced-motion. */
+export interface TypingIndicatorProps {
+  label?: string;
+  className?: string;
+}
+export function TypingIndicator(props: TypingIndicatorProps): React.ReactElement;

package/components/ai/TypingIndicator.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { TypingIndicator } from './TypingIndicator.jsx'
+
+/**
+ * Code Connect stub — TypingIndicator
+ * Prop maps stay minimal until the matching Figma library component is published;
+ * then set nodeId in code-connect/node-map.json and re-run generate-code-connect.
+ */
+figma.connect(TypingIndicator, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-98', {
+  example: () => <TypingIndicator />,
+  imports: ["import { TypingIndicator } from '@cyberskill/design'"],
+})

package/components/ai/TypingIndicator.jsx

@@ -0,0 +1,14 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+/** CyberSkill TypingIndicator — animated dots for when Lumi is composing a reply. */
+export function TypingIndicator({ label, lang, className }) {
+  const [ref, L] = useLang(lang);
+  const lbl = label != null ? label : makeT("TypingIndicator", L)("label");
+  return (
+    <span ref={ref} className={cx("cs-typing", className)} role="status" aria-label={lbl}>
+      <span /><span /><span />
+    </span>
+  );
+}

package/components/ai/TypingIndicator.prompt.md

@@ -0,0 +1,5 @@
+**TypingIndicator** — animated dots while Lumi composes a reply.
+
+```jsx
+<TypingIndicator />
+```

package/components/ai/ai-conversation.card.html

@@ -0,0 +1,49 @@
+<!-- @dsCard group="Components" viewport="700x420" name="AI-native — conversation" subtitle="PromptInput, ChatMessage (Lumi), ConfidenceMeter" -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="stylesheet" href="../../styles.css" />
+<style>
+  body { margin: 0; background: var(--cs-color-surface-page); padding: 22px 24px; }
+  .grid { display: grid; grid-template-columns: 1.2fr 1fr; gap: 24px; max-width: 660px; align-items: start; }
+  .lbl { font: 600 11px/1 var(--cs-font-family-ui); text-transform: uppercase; letter-spacing: .09em; color: var(--cs-color-text-muted); margin-bottom: 10px; }
+</style>
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_ds_bundle.js"></script>
+</head>
+<body>
+<div id="root"></div>
+<script type="text/babel">
+const { PromptInput, ChatMessage, ConfidenceMeter } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+function Demo() {
+  const [q, setQ] = React.useState("A faster checkout for our shop");
+  return (
+    <div className="grid">
+      <div>
+        <div className="lbl">Conversation with Lumi</div>
+        <div className="cs-chat" style={{marginBottom:14}}>
+          <ChatMessage role="lumi">Hello, I’m Lumi. Tell me a wish, and I’ll share plain advice before asking for anything.</ChatMessage>
+          <ChatMessage role="user">A faster checkout.</ChatMessage>
+          <ChatMessage role="lumi">A wish worth granting. I’ll hand it to the team — what should I call you?</ChatMessage>
+        </div>
+        <PromptInput value={q} onChange={setQ} onSubmit={()=>{}} placeholder="Make a wish…" />
+      </div>
+      <div>
+        <div className="lbl">Confidence</div>
+        <div style={{display:"grid",gap:16}}>
+          <ConfidenceMeter value={0.82} />
+          <ConfidenceMeter level="medium" label="Model confidence" />
+          <ConfidenceMeter level="low" label="Draft estimate" />
+        </div>
+      </div>
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>

package/components/ai/ai-lumi.card.html

@@ -0,0 +1,39 @@
+<!-- @dsCard group="Components" viewport="700x320" name="AI-native — Lumi conversation" subtitle="PromptSuggestions, TypingIndicator, CitationList" -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<link rel="stylesheet" href="../../styles.css" />
+<style>
+  body { margin: 0; background: var(--cs-color-surface-page); padding: 22px 24px; }
+  .lbl { font: 600 11px/1 var(--cs-font-family-ui); text-transform: uppercase; letter-spacing: .09em; color: var(--cs-color-text-muted); margin-bottom: 10px; }
+  .blk { margin-bottom: 20px; }
+</style>
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_ds_bundle.js"></script>
+</head>
+<body>
+<div id="root"></div>
+<script type="text/babel">
+const { PromptSuggestions, TypingIndicator, CitationList, ChatMessage } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+function Demo() {
+  return (
+    <div style={{maxWidth:560}}>
+      <div className="blk"><div className="lbl">Prompt suggestions</div>
+        <PromptSuggestions suggestions={["A web app","An internal tool","A design system"]} onSelect={()=>{}} />
+      </div>
+      <div className="blk"><div className="lbl">Typing</div>
+        <div className="cs-chat"><ChatMessage role="lumi"><TypingIndicator /></ChatMessage></div>
+      </div>
+      <div><div className="lbl">Citations</div>
+        <CitationList items={[{title:"release-notes.md"},{title:"Task backlog",source:"Status Hub",href:"#"},{title:"DESIGN.md · Part 21",source:"Liquid Glass"}]} />
+      </div>
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>

package/components/ai/ai.card.html

@@ -0,0 +1,43 @@
+<!-- @dsCard group="Components" viewport="700x340" name="AI-native — Disclosure & Review Gate" subtitle="Explainable AI badge + human-in-the-loop approval" -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="stylesheet" href="../../styles.css" />
+<style>
+  body { margin: 0; background: var(--cs-color-surface-page); padding: 22px 24px; }
+  .stack { display: grid; gap: 18px; max-width: 560px; }
+  .lbl { font: 600 11px/1 var(--cs-font-family-ui); text-transform: uppercase; letter-spacing: .09em; color: var(--cs-color-text-muted); margin-bottom: 8px; }
+</style>
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_ds_bundle.js"></script>
+</head>
+<body>
+<div id="root"></div>
+<script type="text/babel">
+const { AIDisclosureBadge, HumanReviewGate } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+function Demo() {
+  return (
+    <div className="stack">
+      <div>
+        <div className="lbl">AI disclosure (click to expand)</div>
+        <AIDisclosureBadge label="AI assisted" details="Draft summary generated by Lumi, reviewed by the team." sources={["release-notes.md", "task backlog"]} />
+      </div>
+      <div>
+        <div className="lbl">Human review gate</div>
+        <HumanReviewGate
+          risk="High-stakes · billing change"
+          summary="Lumi proposes moving this client to the annual plan and issuing a prorated credit."
+          reviewer="Ops on call"
+        />
+      </div>
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>

package/components/brand/LumiAvatar.d.ts

@@ -0,0 +1,14 @@
+import type * as React from "react";
+
+/**
+ * Avatar for Lumi, the golden-genie mascot. Pass `src` (the real mascot image,
+ * e.g. assets/lumi-poster.webp) — otherwise it falls back to the ✦ "wish" glyph
+ * on the golden gradient. Use for chat, assistants, and AI touchpoints.
+ */
+export interface LumiAvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
+  src?: string;
+  size?: "sm" | "md" | "lg";
+  ring?: boolean;
+  alt?: string;
+}
+export function LumiAvatar(props: LumiAvatarProps): React.ReactElement;