@cyberskill/design 1.0.0

package/components/datatable/DataGrid.d.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+
+/** Advanced table: sortable columns (aria-sort), checkbox row selection,
+ *  sticky-header scroll area, bilingual empty/select labels,
+ *  optional virtualization + column-order persistence. */
+export interface DataGridColumn<R = any> {
+  key: string;
+  header: ReactNode;
+  sortable?: boolean;
+  /** Sticky first-column style pin (inline-start). */
+  pinned?: boolean;
+  /** Custom sort value; defaults to row[key]. */
+  sortValue?: (row: R) => string | number;
+  render?: (row: R) => ReactNode;
+}
+export interface DataGridProps<R = any> {
+  columns: DataGridColumn<R>[];
+  rows: R[];
+  rowKey?: string;
+  selectable?: boolean;
+  selected?: Array<string | number>;
+  onSelect?: (keys: Array<string | number>) => void;
+  /** Scroll-area max height px. Default 280. */
+  height?: number;
+  caption?: ReactNode;
+  empty?: ReactNode;
+  /** Client-side filter query; matches any column value (or filterKeys). */
+  filterText?: string;
+  /** Column keys to filter when filterText is set. Defaults to all column keys. */
+  filterKeys?: string[];
+  /** Force row windowing. Also auto-enables when rows >= virtualThreshold. */
+  virtual?: boolean;
+  /** Auto-virtualize when row count reaches this (default 80). */
+  virtualThreshold?: number;
+  /** Estimated row height for window math (default 36). */
+  rowHeight?: number;
+  /** When set, column order is stored under localStorage key cs:datagrid:cols:<persistKey>. */
+  persistKey?: string;
+  lang?: string;
+  className?: string;
+}
+export function DataGrid(props: DataGridProps): React.ReactElement;

package/components/datatable/DataGrid.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { DataGrid } from './DataGrid.jsx'
+
+/**
+ * Code Connect stub — DataGrid
+ * 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(DataGrid, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-26', {
+  example: () => <DataGrid />,
+  imports: ["import { DataGrid } from '@cyberskill/design'"],
+})

package/components/datatable/DataGrid.jsx

@@ -0,0 +1,149 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+/**
+ * CyberSkill DataGrid — advanced table: sortable columns, selectable rows, sticky header,
+ * optional column pin + client filter + row virtualization + optional column order persistence.
+ */
+export function DataGrid({
+  columns = [],
+  rows = [],
+  rowKey = "id",
+  selectable = false,
+  selected = [],
+  onSelect,
+  height = 280,
+  caption,
+  empty,
+  lang,
+  className,
+  filterText,
+  filterKeys,
+  /** When true (or rows exceed virtualThreshold), only paint a window of rows. */
+  virtual = false,
+  /** Row threshold that auto-enables virtualization. Default 80. */
+  virtualThreshold = 80,
+  /** Approximate row height for windowing. Default 36. */
+  rowHeight = 36,
+  /** localStorage key — when set, column key order is persisted across reloads. */
+  persistKey,
+}) {
+  const [sort, setSort] = React.useState(null); // {key, dir}
+  const [scrollTop, setScrollTop] = React.useState(0);
+  const [colOrder, setColOrder] = React.useState(() => {
+    if (!persistKey) return null;
+    try {
+      const raw = localStorage.getItem("cs:datagrid:cols:" + persistKey);
+      const arr = raw ? JSON.parse(raw) : null;
+      return Array.isArray(arr) ? arr : null;
+    } catch (e) { return null; }
+  });
+  const [ref, L] = useLang(lang);
+  const t = makeT("DataGrid", L);
+
+  const orderedColumns = React.useMemo(() => {
+    if (!colOrder || !colOrder.length) return columns;
+    const map = new Map(columns.map((c) => [c.key, c]));
+    const out = [];
+    for (const k of colOrder) if (map.has(k)) { out.push(map.get(k)); map.delete(k); }
+    for (const c of map.values()) out.push(c);
+    return out;
+  }, [columns, colOrder]);
+
+  const filtered = React.useMemo(() => {
+    const q = (filterText == null ? "" : String(filterText)).trim().toLowerCase();
+    if (!q) return rows;
+    const keys = filterKeys && filterKeys.length ? filterKeys : orderedColumns.map((c) => c.key);
+    return rows.filter((r) => keys.some((k) => String(r[k] == null ? "" : r[k]).toLowerCase().includes(q)));
+  }, [rows, filterText, filterKeys, orderedColumns]);
+
+  const sorted = React.useMemo(() => {
+    if (!sort) return filtered;
+    const col = orderedColumns.find((c) => c.key === sort.key);
+    const val = (r) => (col && col.sortValue ? col.sortValue(r) : r[sort.key]);
+    return [...filtered].sort((a, b) => { const x = val(a), y = val(b); return (x > y ? 1 : x < y ? -1 : 0) * (sort.dir === "asc" ? 1 : -1); });
+  }, [filtered, sort, orderedColumns]);
+
+  const useVirtual = virtual || sorted.length >= virtualThreshold;
+  const bodyH = Math.max(0, height - 40);
+  const start = useVirtual ? Math.max(0, Math.floor(scrollTop / rowHeight) - 4) : 0;
+  const visibleCount = useVirtual ? Math.ceil(bodyH / rowHeight) + 8 : sorted.length;
+  const end = useVirtual ? Math.min(sorted.length, start + visibleCount) : sorted.length;
+  const slice = sorted.slice(start, end);
+  const padTop = useVirtual ? start * rowHeight : 0;
+  const padBottom = useVirtual ? Math.max(0, (sorted.length - end) * rowHeight) : 0;
+
+  const allSel = selectable && filtered.length && filtered.every((r) => selected.includes(r[rowKey]));
+  const toggleAll = () => onSelect && onSelect(allSel ? [] : filtered.map((r) => r[rowKey]));
+  const toggle = (k) => onSelect && onSelect(selected.includes(k) ? selected.filter((x) => x !== k) : [...selected, k]);
+
+  const pinColumn = (key) => {
+    if (!persistKey) return;
+    const keys = orderedColumns.map((c) => c.key);
+    const next = [key, ...keys.filter((k) => k !== key)];
+    setColOrder(next);
+    try { localStorage.setItem("cs:datagrid:cols:" + persistKey, JSON.stringify(next)); } catch (e) {}
+  };
+
+  return (
+    <div
+      ref={ref}
+      className={cx("cs-datagrid", useVirtual && "cs-datagrid--virtual", className)}
+      style={{ maxBlockSize: height, overflow: "auto" }}
+      onScroll={useVirtual ? (e) => setScrollTop(e.currentTarget.scrollTop) : undefined}
+      data-virtual={useVirtual ? "true" : "false"}
+      data-row-count={sorted.length}
+    >
+      <table className="cs-table">
+        {caption ? <caption>{caption}</caption> : null}
+        <thead>
+          <tr>
+            {selectable ? <th scope="col" className="cs-datagrid__selcol"><input type="checkbox" aria-label={t("selectAll")} checked={!!allSel} onChange={toggleAll} /></th> : null}
+            {orderedColumns.map((c) => (
+              <th
+                key={c.key}
+                scope="col"
+                className={c.pinned ? "cs-datagrid__pinned" : undefined}
+                style={c.pinned ? { position: "sticky", insetInlineStart: 0, zIndex: 1, background: "var(--cs-color-surface-panel)" } : undefined}
+                aria-sort={sort && sort.key === c.key ? (sort.dir === "asc" ? "ascending" : "descending") : undefined}
+              >
+                {c.sortable ? (
+                  <button type="button" className="cs-datagrid__sort" onClick={() => setSort((s) => (!s || s.key !== c.key ? { key: c.key, dir: "asc" } : s.dir === "asc" ? { key: c.key, dir: "desc" } : null))}>
+                    {c.header}<span aria-hidden="true">{sort && sort.key === c.key ? (sort.dir === "asc" ? " ▲" : " ▼") : " ↕"}</span>
+                  </button>
+                ) : c.header}
+                {persistKey ? (
+                  <button type="button" className="cs-datagrid__pin" title="Pin column first" onClick={() => pinColumn(c.key)} aria-label={"Pin " + c.key}>⟂</button>
+                ) : null}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {sorted.length === 0 ? (
+            <tr><td colSpan={orderedColumns.length + (selectable ? 1 : 0)} className="cs-table__empty">{empty != null ? empty : t("empty")}</td></tr>
+          ) : (
+            <>
+              {padTop > 0 ? <tr aria-hidden="true"><td colSpan={orderedColumns.length + (selectable ? 1 : 0)} style={{ height: padTop, padding: 0, border: 0 }} /></tr> : null}
+              {slice.map((r, i) => {
+                const k = r[rowKey] != null ? r[rowKey] : start + i;
+                return (
+                  <tr key={k} className={selected.includes(k) ? "is-selected" : undefined} style={useVirtual ? { height: rowHeight } : undefined}>
+                    {selectable ? <td className="cs-datagrid__selcol"><input type="checkbox" aria-label={t("selectRow")} checked={selected.includes(k)} onChange={() => toggle(k)} /></td> : null}
+                    {orderedColumns.map((c) => (
+                      <td key={c.key} className={c.pinned ? "cs-datagrid__pinned" : undefined} style={c.pinned ? { position: "sticky", insetInlineStart: 0, background: "var(--cs-color-surface-panel)" } : undefined}>
+                        {c.render ? c.render(r) : r[c.key]}
+                      </td>
+                    ))}
+                  </tr>
+                );
+              })}
+              {padBottom > 0 ? <tr aria-hidden="true"><td colSpan={orderedColumns.length + (selectable ? 1 : 0)} style={{ height: padBottom, padding: 0, border: 0 }} /></tr> : null}
+            </>
+          )}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/components/datatable/DataGrid.prompt.md

@@ -0,0 +1,12 @@
+**DataGrid** — sortable + selectable table with sticky header.
+
+```jsx
+<DataGrid selectable selected={sel} onSelect={setSel} rowKey="key"
+  columns={[{key:"name",header:"Project",sortable:true},{key:"pct",header:"Progress",sortable:true}]} rows={rows}/>
+```
+
+**filterText / filterKeys / pinned:** client filter query, optional key subset, and sticky column pin.
+
+**virtual / virtualThreshold / rowHeight:** windowed body rows for large datasets (auto when rows ≥ 80). Sets `data-virtual="true"` and `data-row-count`.
+
+**persistKey:** stores column order in `localStorage` under `cs:datagrid:cols:<persistKey>`; pin control reorders a column to first.

package/components/datatable/DataTable.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import type * as React from "react";
+
+export interface DataTableColumn<Row> {
+  key: string;
+  header: ReactNode;
+  /** Custom cell renderer; defaults to row[key]. */
+  render?: (row: Row) => ReactNode;
+}
+
+/**
+ * Enterprise data table: caption, scoped column headers, per-column render, and
+ * an empty state. Dense content — keep it on a solid surface (no glass).
+ */
+export interface DataTableProps<Row extends Record<string, unknown>> {
+  caption?: ReactNode;
+  columns: DataTableColumn<Row>[];
+  rows: Row[];
+  /** Field used as React key. Default "id". */
+  rowKey?: keyof Row & string;
+  emptyState?: ReactNode;
+  className?: string;
+}
+
+export function DataTable<Row extends Record<string, unknown>>(props: DataTableProps<Row>): React.ReactElement;

package/components/datatable/DataTable.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { DataTable } from './DataTable.jsx'
+
+/**
+ * Code Connect stub — DataTable
+ * 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(DataTable, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-27', {
+  example: () => <DataTable />,
+  imports: ["import { DataTable } from '@cyberskill/design'"],
+})

package/components/datatable/DataTable.jsx

@@ -0,0 +1,42 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+/**
+ * CyberSkill DataTable — semantic table with caption, column scope headers,
+ * per-column render, and an empty state. Solid surface (dense content).
+ */
+export function DataTable({
+  caption,
+  columns,
+  rows,
+  rowKey = "id",
+  emptyState,
+  lang,
+  className,
+}) {
+  const normalized = Array.isArray(rows) ? rows : [];
+  const [ref, L] = useLang(lang);
+  const es = emptyState != null ? emptyState : makeT("DataTable", L)("empty");
+  return (
+    <div ref={ref} className={cx("cs-table-wrap", className)}>
+      <table className="cs-table">
+        {caption ? <caption>{caption}</caption> : null}
+        <thead>
+          <tr>{columns.map((c) => <th key={c.key} scope="col">{c.header}</th>)}</tr>
+        </thead>
+        <tbody>
+          {normalized.length === 0 ? (
+            <tr><td colSpan={columns.length} className="cs-table__empty">{es}</td></tr>
+          ) : (
+            normalized.map((row, i) => (
+              <tr key={row[rowKey] ?? i}>
+                {columns.map((c) => <td key={c.key}>{c.render ? c.render(row) : row[c.key]}</td>)}
+              </tr>
+            ))
+          )}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/components/datatable/DataTable.prompt.md

@@ -0,0 +1,15 @@
+**DataTable** — semantic table with a caption, scoped column headers, per-column `render`, and an empty state. Dense content, so it stays on a solid surface (never glass).
+
+```jsx
+<DataTable
+  caption="Releases"
+  columns={[
+    { key: "ver", header: "Version" },
+    { key: "date", header: "Ships" },
+    { key: "status", header: "Status", render: (r) => <span className={`pill ${r.tone}`}>{r.status}</span> },
+  ]}
+  rows={releases}
+  rowKey="ver"
+  emptyState="No releases yet"
+/>
+```

package/components/datatable/TreeTable.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+
+/** Table whose first column expands nested child rows. */
+export interface TreeTableColumn<R = any> { key: string; header: ReactNode; render?: (row: R) => ReactNode; }
+export interface TreeTableNode { key: string; children?: TreeTableNode[]; [field: string]: unknown; }
+export interface TreeTableProps {
+  columns: TreeTableColumn[];
+  nodes: TreeTableNode[];
+  caption?: ReactNode;
+  defaultExpanded?: string[];
+  lang?: string;
+  className?: string;
+}
+export function TreeTable(props: TreeTableProps): React.ReactElement;

package/components/datatable/TreeTable.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { TreeTable } from './TreeTable.jsx'
+
+/**
+ * Code Connect stub — TreeTable
+ * 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(TreeTable, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-97', {
+  example: () => <TreeTable />,
+  imports: ["import { TreeTable } from '@cyberskill/design'"],
+})

package/components/datatable/TreeTable.jsx

@@ -0,0 +1,47 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+function Row({ n, depth, columns, expanded, setExpanded }) {
+  const kids = n.children || [];
+  const open = expanded.includes(n.key);
+  return (
+    <>
+      <tr>
+        {columns.map((c, i) => (
+          <td key={c.key}>
+            {i === 0 ? (
+              <span className="cs-treetable__cell" style={{ paddingInlineStart: depth * 18 }}>
+                {kids.length ? (
+                  <button type="button" className="cs-tree__twist" aria-expanded={open} onClick={() => setExpanded(open ? expanded.filter((k) => k !== n.key) : [...expanded, n.key])}>{open ? "▾" : "▸"}</button>
+                ) : <span className="cs-tree__twist" aria-hidden="true" />}
+                {c.render ? c.render(n) : n[c.key]}
+              </span>
+            ) : (c.render ? c.render(n) : n[c.key])}
+          </td>
+        ))}
+      </tr>
+      {open ? kids.map((k) => <Row key={k.key} n={k} depth={depth + 1} columns={columns} expanded={expanded} setExpanded={setExpanded} />) : null}
+    </>
+  );
+}
+
+/** CyberSkill TreeTable — table whose first column expands nested rows. nodes: rows with children[]. */
+export function TreeTable({ columns = [], nodes = [], caption, defaultExpanded = [], lang, className }) {
+  const [expanded, setExpanded] = React.useState(defaultExpanded);
+  const [ref, L] = useLang(lang);
+  const t = makeT("DataGrid", L);
+  return (
+    <div ref={ref} className={cx("cs-table-wrap", className)}>
+      <table className="cs-table cs-treetable">
+        {caption ? <caption>{caption}</caption> : null}
+        <thead><tr>{columns.map((c) => <th key={c.key} scope="col">{c.header}</th>)}</tr></thead>
+        <tbody>
+          {nodes.length === 0
+            ? <tr><td colSpan={columns.length} className="cs-table__empty">{t("empty")}</td></tr>
+            : nodes.map((n) => <Row key={n.key} n={n} depth={0} columns={columns} expanded={expanded} setExpanded={setExpanded} />)}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/components/datatable/TreeTable.prompt.md

@@ -0,0 +1,6 @@
+**TreeTable** — expandable nested rows in a table.
+
+```jsx
+<TreeTable defaultExpanded={["p"]} columns={[{key:"name",header:"Item"},{key:"pct",header:"Progress"}]}
+  nodes={[{key:"p",name:"Platform",pct:"70%",children:[{key:"ds",name:"Design System",pct:"72%"}]}]}/>
+```

package/components/datatable/datatable.card.html

@@ -0,0 +1,51 @@
+<!-- @dsCard group="Components" viewport="700x300" name="DataTable" subtitle="Caption, scoped headers, custom cells, empty state" -->
+<!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; }
+  .wrap { border: 1px solid var(--cs-color-border-default); border-radius: var(--cs-radius-lg); padding: 6px 16px 10px; background: var(--cs-color-surface-panel); max-width: 640px; }
+  .pill { display: inline-block; font: 700 11px/1 var(--cs-font-family-ui); text-transform: uppercase; letter-spacing: .04em; padding: 3px 9px; border-radius: 999px; }
+  .pill.done { background: var(--cs-color-semantic-success); color: #fff; }
+  .pill.active { background: var(--cs-color-brand-ochre); color: var(--cs-color-brand-umber); }
+  .pill.hold { background: var(--cs-color-semantic-danger); color: #fff; }
+  .mono { font-family: var(--cs-font-family-mono); font-weight: 600; }
+</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 { DataTable } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+const rows = [
+  { ver: "v1.5.1", ships: "Shipped", status: "done", note: "Element packs" },
+  { ver: "v1.6.0", ships: "This week", status: "active", note: "Glass bindings" },
+  { ver: "v1.7.0", ships: "Q3 2026", status: "hold", note: "Awaiting RFC" },
+];
+function Demo() {
+  return (
+    <div className="wrap">
+      <DataTable
+        caption="Releases"
+        rowKey="ver"
+        columns={[
+          { key: "ver", header: "Version", render: (r) => <span className="mono">{r.ver}</span> },
+          { key: "ships", header: "Ships" },
+          { key: "note", header: "Notes" },
+          { key: "status", header: "Status", render: (r) => <span className={"pill " + r.status}>{r.status}</span> },
+        ]}
+        rows={rows}
+      />
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>

package/components/dialog/Dialog.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+import type * as React from "react";
+
+/**
+ * Modal dialog: dimmed overlay + centred panel, aria-modal and labelled by its
+ * title. Overlay click calls onClose. Put Buttons in `actions`. On narrow
+ * viewports it goes near-fullscreen and actions stack.
+ */
+export interface DialogProps {
+  open: boolean;
+  title: ReactNode;
+  children?: ReactNode;
+  /** Footer actions, typically Buttons. */
+  actions?: ReactNode;
+  onClose?: () => void;
+  closeLabel?: string;
+  /** "en" | "vi" — else resolved from the nearest [lang] ancestor (vi default). */
+  lang?: string;
+  className?: string;
+}
+
+export function Dialog(props: DialogProps): React.ReactElement | null;

package/components/dialog/Dialog.figma.tsx

@@ -0,0 +1,12 @@
+import figma from '@figma/code-connect'
+import { Dialog } from './Dialog.jsx'
+
+figma.connect(Dialog, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-30', {
+  props: {
+    open: figma.boolean('Open'),
+    title: figma.string('Title'),
+    children: figma.string('Body'),
+  },
+  example: (props) => <Dialog {...props} />,
+  imports: ["import { Dialog } from '@cyberskill/design'"],
+})

package/components/dialog/Dialog.jsx

@@ -0,0 +1,99 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { Icon } from "../icon/Icon.jsx";
+import { cx } from "../_utils/cx.js";
+
+const FOCUSABLE = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'audio[controls]',
+  'video[controls]',
+  'summary',
+  'iframe',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+/**
+ * CyberSkill Dialog — modal overlay + panel. aria-modal, labelled by title and
+ * described by its body, scrim click closes. Body scroll is locked while open
+ * (prior overflow restored on close/unmount). Compose actions in the footer
+ * with Buttons.
+ */
+export function Dialog({
+  open,
+  title,
+  children,
+  actions,
+  onClose,
+  className,
+  closeLabel,
+  lang,
+  ...props
+}) {
+  const baseId = React.useId();
+  const titleId = baseId + "-title";
+  const bodyId = children == null ? undefined : baseId + "-body";
+  const [ref, L] = useLang(lang);
+  const panel = React.useRef(null);
+  const closeRef = React.useRef(onClose); closeRef.current = onClose;
+  React.useEffect(() => {
+    if (!open) return;
+    const prev = document.activeElement;
+    const prevOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    const focusables = () => (panel.current ? [...panel.current.querySelectorAll(FOCUSABLE)] : []);
+    const first = focusables()[0];
+    (first || panel.current) && (first || panel.current).focus();
+    const k = (e) => {
+      if (e.key === "Escape") { closeRef.current && closeRef.current(); return; }
+      if (e.key !== "Tab" || !panel.current) return;
+      const f = focusables();
+      if (!f.length) { e.preventDefault(); panel.current.focus(); return; }
+      const a = f[0], z = f[f.length - 1];
+      const active = document.activeElement;
+      const inside = panel.current.contains(active);
+      // Wrap at either edge; if focus somehow escaped the panel, pull it back in.
+      if (e.shiftKey && (!inside || active === a)) { e.preventDefault(); z.focus(); }
+      else if (!e.shiftKey && (!inside || active === z)) { e.preventDefault(); a.focus(); }
+    };
+    document.addEventListener("keydown", k);
+    return () => {
+      document.removeEventListener("keydown", k);
+      document.body.style.overflow = prevOverflow;
+      if (prev && prev.focus) prev.focus();
+    };
+  }, [open]);
+  const cl = closeLabel != null ? closeLabel : makeT("Dialog", L)("close");
+  if (!open) return null;
+  return (
+    <div ref={ref} className="cs-dialog-layer">
+      <div className="cs-dialog__overlay" onClick={onClose} aria-hidden="true" />
+      <section
+        {...props}
+        ref={panel}
+        tabIndex={-1}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        aria-describedby={bodyId != null ? bodyId : props["aria-describedby"]}
+        className={cx("cs-dialog", className)}
+      >
+        <header className="cs-dialog__header">
+          <h2 id={titleId} className="cs-dialog__title">{title}</h2>
+          {onClose ? (
+            <button type="button" className="cs-button cs-button--ghost cs-button--sm" onClick={onClose} aria-label={cl}>
+              <Icon name="close" size="sm" />
+            </button>
+          ) : null}
+        </header>
+        <div id={bodyId} className="cs-dialog__body">{children}</div>
+        {actions ? <footer className="cs-dialog__actions">{actions}</footer> : null}
+      </section>
+    </div>
+  );
+}

package/components/dialog/Dialog.prompt.md

@@ -0,0 +1,17 @@
+**Dialog** — modal overlay + centred panel. `aria-modal`, labelled by title, overlay-click closes. Compose footer actions with `Button`s. Goes near-fullscreen on narrow viewports.
+
+```jsx
+<Dialog
+  open={open}
+  title="Send your wish?"
+  onClose={() => setOpen(false)}
+  actions={<>
+    <Button variant="secondary" onClick={() => setOpen(false)}>Not now</Button>
+    <Button onClick={submit}>Send wish</Button>
+  </>}
+>
+  A real person on the team replies within one business day.
+</Dialog>
+```
+
+- Pair with Heavy Glass (`className="cs-surface-heavy"`) only after checking APCA against the backdrop.

package/components/dialog/dialog.card.html

@@ -0,0 +1,46 @@
+<!-- @dsCard group="Components" viewport="700x320" name="Dialog" subtitle="Modal overlay + panel with footer actions" -->
+<!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; }
+  /* Scope the fixed dialog layer to the preview frame so it renders inline in the card. */
+  .frame { position: relative; height: 256px; border: 1px solid var(--cs-color-border-default); border-radius: var(--cs-radius-lg); overflow: hidden; background: var(--cs-color-surface-raised); }
+  .frame .cs-dialog-layer { position: absolute; }
+  .frame .cs-dialog { top: 24px; }
+</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 { Dialog, Button } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+function Demo() {
+  const [open, setOpen] = React.useState(true);
+  return (
+    <div className="frame">
+      {!open && <div style={{padding:24}}><Button onClick={() => setOpen(true)}>Open dialog</Button></div>}
+      <Dialog
+        open={open}
+        title="Send your wish?"
+        onClose={() => setOpen(false)}
+        actions={<>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Not now</Button>
+          <Button onClick={() => setOpen(false)}>Send wish</Button>
+        </>}
+      >
+        A real person on the team replies within one business day. We never share your details.
+      </Dialog>
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>