@ktbsh/ui 0.1.0 → 0.3.0

package/README.md

@@ -49,8 +49,10 @@ dist/
 | `@ktbsh/ui` | Tokens helpers + shared types |
 | `@ktbsh/ui/vanilla/<name>` | Register `kitbash-<name>` custom element |
 | `@ktbsh/ui/react/<name>` | React wrapper (`Kitbash*`) + types |
-| `@ktbsh/ui/themes/light.css` | Light theme (`:root` default) |
-| `@ktbsh/ui/themes/dark.css` | Dark theme (`:root[data-theme="dark"]`) |
+| `@ktbsh/ui/themes/light.css` | Default preset light (`:root` default) |
+| `@ktbsh/ui/themes/dark.css` | Default preset dark (`:root[data-theme="dark"]`) |
+| `@ktbsh/ui/themes/terminal/light.css` | Terminal preset light |
+| `@ktbsh/ui/themes/terminal/dark.css` | Terminal preset dark (Matrix night) |
 | `@ktbsh/ui/tokens` | Token API only |
 | `@ktbsh/ui/types` | Shared TypeScript unions |
 | `@ktbsh/ui/custom-elements.json` | Custom Elements Manifest |
@@ -87,13 +89,20 @@ Load theme CSS in the host app (variables inherit into shadow roots):
 ```ts
 import '@ktbsh/ui/themes/light.css';
 import '@ktbsh/ui/themes/dark.css';
-import { applyTheme } from '@ktbsh/ui';
-
-applyTheme('dark'); // document.documentElement dataset.theme
-// light is default via :root even without data-theme
+// Optional Matrix-style preset (blog terminal mode):
+import '@ktbsh/ui/themes/terminal/light.css';
+import '@ktbsh/ui/themes/terminal/dark.css';
+import { applyPreset, applyTheme } from '@ktbsh/ui';
+
+applyTheme('dark'); // data-theme — light | dark (night)
+applyPreset('terminal'); // data-kb-preset — default | terminal
+// light + default when attributes omitted
 ```
 
-Components use semantic vars such as `var(--kb-color-accent-default)`. Kitbash also injects light defaults onto `:host` from `tokens.json`.
+Two axes (same idea as the personal blog): **theme** (light/dark) × **preset** (default/terminal).  
+Components use only semantic vars such as `var(--kb-color-accent-default)`, **inherited from document** theme CSS.
+
+> **Required:** load theme stylesheets on the app shell (`:root`). We do **not** bake absolute token values onto each component `:host` — that sealed the shadow tree and blocked theme toggles (see `docs/sdk-feedback.md` P0 #0).
 
 ## Consume
 

package/dist/custom-elements.json

@@ -207,6 +207,45 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "vanilla/preset-toggle.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "KitbashPresetToggle",
+          "customElement": true,
+          "tagName": "kitbash-preset-toggle",
+          "attributes": [
+            {
+              "name": "value",
+              "type": {
+                "text": "String"
+              },
+              "default": "\"\""
+            },
+            {
+              "name": "storageKey",
+              "type": {
+                "text": "String"
+              },
+              "default": "\"ui-mode\""
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "kitbash-preset-toggle",
+          "declaration": {
+            "name": "KitbashPresetToggle",
+            "module": "vanilla/preset-toggle.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "vanilla/toast.js",
@@ -564,6 +603,98 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "vanilla/theme-toggle.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "KitbashThemeToggle",
+          "customElement": true,
+          "tagName": "kitbash-theme-toggle",
+          "attributes": [
+            {
+              "name": "value",
+              "type": {
+                "text": "String"
+              },
+              "default": "\"\""
+            },
+            {
+              "name": "storageKey",
+              "type": {
+                "text": "String"
+              },
+              "default": "\"theme\""
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "kitbash-theme-toggle",
+          "declaration": {
+            "name": "KitbashThemeToggle",
+            "module": "vanilla/theme-toggle.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "vanilla/scroll-top.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "KitbashScrollTop",
+          "customElement": true,
+          "tagName": "kitbash-scroll-top",
+          "attributes": [
+            {
+              "name": "visible",
+              "type": {
+                "text": "Boolean"
+              },
+              "default": "false"
+            },
+            {
+              "name": "label",
+              "type": {
+                "text": "String"
+              },
+              "default": "\"Scroll to top\""
+            },
+            {
+              "name": "caption",
+              "type": {
+                "text": "String"
+              },
+              "default": "\"$ top\""
+            },
+            {
+              "name": "behavior",
+              "type": {
+                "text": "String"
+              },
+              "default": "\"smooth\""
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "kitbash-scroll-top",
+          "declaration": {
+            "name": "KitbashScrollTop",
+            "module": "vanilla/scroll-top.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "vanilla/switch.js",
@@ -744,6 +875,30 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "vanilla/toggle-group.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "KitbashToggleGroup",
+          "customElement": true,
+          "tagName": "kitbash-toggle-group",
+          "attributes": []
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "kitbash-toggle-group",
+          "declaration": {
+            "name": "KitbashToggleGroup",
+            "module": "vanilla/toggle-group.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "vanilla/stack.js",

package/dist/index.d.ts

@@ -8,6 +8,10 @@
  * Theme CSS (load once in the app shell):
  *   import '@ktbsh/ui/themes/light.css'
  *   import '@ktbsh/ui/themes/dark.css'
+ *   import '@ktbsh/ui/themes/terminal/light.css' // optional
+ *   import '@ktbsh/ui/themes/terminal/dark.css'
+ *
+ * applyTheme('light'|'dark'); applyPreset('default'|'terminal');
  */
-export { applyTheme, cssVar, cssVarName, getTheme, type KitbashTheme, type SemanticTokenName, semanticTokens, type TokenValue, } from './tokens/index.ts';
+export { applyPreset, applyTheme, cssVar, cssVarName, getPreset, getTheme, type KitbashPreset, type KitbashTheme, type SemanticTokenName, semanticTokens, type TokenValue, } from './tokens/index.ts';
 export type { KitbashBadgeTone, KitbashButtonVariant, KitbashContainerWidth, KitbashFeedbackTone, KitbashHeadingLevel, KitbashLinkTone, KitbashSize, KitbashSkeletonVariant, KitbashSpace, KitbashStackAlign, KitbashStackDirection, KitbashStackJustify, KitbashTextTone, } from './types/index.ts';

package/dist/index.js

@@ -8,5 +8,9 @@
  * Theme CSS (load once in the app shell):
  *   import '@ktbsh/ui/themes/light.css'
  *   import '@ktbsh/ui/themes/dark.css'
+ *   import '@ktbsh/ui/themes/terminal/light.css' // optional
+ *   import '@ktbsh/ui/themes/terminal/dark.css'
+ *
+ * applyTheme('light'|'dark'); applyPreset('default'|'terminal');
  */
-export { applyTheme, cssVar, cssVarName, getTheme, semanticTokens, } from "./tokens/index.js";
+export { applyPreset, applyTheme, cssVar, cssVarName, getPreset, getTheme, semanticTokens, } from "./tokens/index.js";

package/dist/react/preset-toggle.d.ts

@@ -0,0 +1,18 @@
+
+import * as React from 'react';
+
+export interface KitbashPresetToggleProps extends React.HTMLAttributes<HTMLElement> {
+  'value'?: string;
+  'storageKey'?: string;
+  onKitbashChange?: (event: CustomEvent<{ props: Record<string, unknown>; state: Record<string, unknown> }>) => void;
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitbash-preset-toggle': KitbashPresetToggleProps & React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+
+export declare const KitbashPresetToggle: React.ForwardRefExoticComponent<KitbashPresetToggleProps & React.RefAttributes<HTMLElement>>;

package/dist/react/preset-toggle.js

@@ -0,0 +1,30 @@
+
+import * as React from 'react';
+import '../vanilla/preset-toggle.js';
+
+export const KitbashPresetToggle = React.forwardRef(({ children, onKitbashChange, ...props }, ref) => {
+  const innerRef = React.useRef(null);
+
+  // kitbash-change is a CustomEvent — bridge manually. Native events (onClick, etc.)
+  // stay on ...props so React 19 binds them once (no double-fire).
+  React.useEffect(() => {
+    const el = innerRef.current;
+    if (!el || !onKitbashChange) return;
+
+    const handleCustomChange = (e) => onKitbashChange(e);
+    el.addEventListener('kitbash-change', handleCustomChange);
+    return () => el.removeEventListener('kitbash-change', handleCustomChange);
+  }, [onKitbashChange]);
+
+  // Callback ref: assign + clear on unmount / ref change (object + function refs).
+  const setRefs = React.useCallback((node) => {
+    innerRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    } else if (ref && typeof ref === 'object') {
+      ref.current = node;
+    }
+  }, [ref]);
+
+  return React.createElement('kitbash-preset-toggle', { ref: setRefs, ...props }, children);
+});

package/dist/react/scroll-top.d.ts

@@ -0,0 +1,20 @@
+
+import * as React from 'react';
+
+export interface KitbashScrollTopProps extends React.HTMLAttributes<HTMLElement> {
+  'visible'?: boolean;
+  'label'?: string;
+  'caption'?: string;
+  'behavior'?: string;
+  onKitbashChange?: (event: CustomEvent<{ props: Record<string, unknown>; state: Record<string, unknown> }>) => void;
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitbash-scroll-top': KitbashScrollTopProps & React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+
+export declare const KitbashScrollTop: React.ForwardRefExoticComponent<KitbashScrollTopProps & React.RefAttributes<HTMLElement>>;

package/dist/react/scroll-top.js

@@ -0,0 +1,30 @@
+
+import * as React from 'react';
+import '../vanilla/scroll-top.js';
+
+export const KitbashScrollTop = React.forwardRef(({ children, onKitbashChange, ...props }, ref) => {
+  const innerRef = React.useRef(null);
+
+  // kitbash-change is a CustomEvent — bridge manually. Native events (onClick, etc.)
+  // stay on ...props so React 19 binds them once (no double-fire).
+  React.useEffect(() => {
+    const el = innerRef.current;
+    if (!el || !onKitbashChange) return;
+
+    const handleCustomChange = (e) => onKitbashChange(e);
+    el.addEventListener('kitbash-change', handleCustomChange);
+    return () => el.removeEventListener('kitbash-change', handleCustomChange);
+  }, [onKitbashChange]);
+
+  // Callback ref: assign + clear on unmount / ref change (object + function refs).
+  const setRefs = React.useCallback((node) => {
+    innerRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    } else if (ref && typeof ref === 'object') {
+      ref.current = node;
+    }
+  }, [ref]);
+
+  return React.createElement('kitbash-scroll-top', { ref: setRefs, ...props }, children);
+});

package/dist/react/theme-toggle.d.ts

@@ -0,0 +1,18 @@
+
+import * as React from 'react';
+
+export interface KitbashThemeToggleProps extends React.HTMLAttributes<HTMLElement> {
+  'value'?: string;
+  'storageKey'?: string;
+  onKitbashChange?: (event: CustomEvent<{ props: Record<string, unknown>; state: Record<string, unknown> }>) => void;
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitbash-theme-toggle': KitbashThemeToggleProps & React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+
+export declare const KitbashThemeToggle: React.ForwardRefExoticComponent<KitbashThemeToggleProps & React.RefAttributes<HTMLElement>>;

package/dist/react/theme-toggle.js

@@ -0,0 +1,30 @@
+
+import * as React from 'react';
+import '../vanilla/theme-toggle.js';
+
+export const KitbashThemeToggle = React.forwardRef(({ children, onKitbashChange, ...props }, ref) => {
+  const innerRef = React.useRef(null);
+
+  // kitbash-change is a CustomEvent — bridge manually. Native events (onClick, etc.)
+  // stay on ...props so React 19 binds them once (no double-fire).
+  React.useEffect(() => {
+    const el = innerRef.current;
+    if (!el || !onKitbashChange) return;
+
+    const handleCustomChange = (e) => onKitbashChange(e);
+    el.addEventListener('kitbash-change', handleCustomChange);
+    return () => el.removeEventListener('kitbash-change', handleCustomChange);
+  }, [onKitbashChange]);
+
+  // Callback ref: assign + clear on unmount / ref change (object + function refs).
+  const setRefs = React.useCallback((node) => {
+    innerRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    } else if (ref && typeof ref === 'object') {
+      ref.current = node;
+    }
+  }, [ref]);
+
+  return React.createElement('kitbash-theme-toggle', { ref: setRefs, ...props }, children);
+});

package/dist/react/toggle-group.d.ts

@@ -0,0 +1,17 @@
+
+import * as React from 'react';
+
+export interface KitbashToggleGroupProps extends React.HTMLAttributes<HTMLElement> {
+  
+  onKitbashChange?: (event: CustomEvent<{ props: Record<string, unknown>; state: Record<string, unknown> }>) => void;
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'kitbash-toggle-group': KitbashToggleGroupProps & React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+
+export declare const KitbashToggleGroup: React.ForwardRefExoticComponent<KitbashToggleGroupProps & React.RefAttributes<HTMLElement>>;

package/dist/react/toggle-group.js

@@ -0,0 +1,30 @@
+
+import * as React from 'react';
+import '../vanilla/toggle-group.js';
+
+export const KitbashToggleGroup = React.forwardRef(({ children, onKitbashChange, ...props }, ref) => {
+  const innerRef = React.useRef(null);
+
+  // kitbash-change is a CustomEvent — bridge manually. Native events (onClick, etc.)
+  // stay on ...props so React 19 binds them once (no double-fire).
+  React.useEffect(() => {
+    const el = innerRef.current;
+    if (!el || !onKitbashChange) return;
+
+    const handleCustomChange = (e) => onKitbashChange(e);
+    el.addEventListener('kitbash-change', handleCustomChange);
+    return () => el.removeEventListener('kitbash-change', handleCustomChange);
+  }, [onKitbashChange]);
+
+  // Callback ref: assign + clear on unmount / ref change (object + function refs).
+  const setRefs = React.useCallback((node) => {
+    innerRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    } else if (ref && typeof ref === 'object') {
+      ref.current = node;
+    }
+  }, [ref]);
+
+  return React.createElement('kitbash-toggle-group', { ref: setRefs, ...props }, children);
+});

package/dist/themes/dark.css

@@ -1,6 +1,6 @@
 /**
  * GENERATED FILE — do not edit by hand.
- * Source: src/tokens/semantic.ts
+ * Source: src/tokens/semantic.ts (+ presets)
  * Regenerate: bun run tokens:build
  */
 :root[data-theme="dark"] {

package/dist/themes/light.css

@@ -1,6 +1,6 @@
 /**
  * GENERATED FILE — do not edit by hand.
- * Source: src/tokens/semantic.ts
+ * Source: src/tokens/semantic.ts (+ presets)
  * Regenerate: bun run tokens:build
  */
 :root,

package/dist/themes/terminal/dark.css

@@ -0,0 +1,52 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ * Source: src/tokens/semantic.ts (+ presets)
+ * Regenerate: bun run tokens:build
+ */
+:root[data-kb-preset="terminal"][data-theme="dark"] {
+  --kb-color-bg-canvas: #050a05;
+  --kb-color-bg-surface: #0a120a;
+  --kb-color-bg-subtle: #0f1a0f;
+  --kb-color-bg-inverse: #d1fae5;
+  --kb-color-fg-default: #4ade80;
+  --kb-color-fg-muted: #a3f2b0;
+  --kb-color-fg-subtle: #00cc33;
+  --kb-color-fg-on-accent: #050a05;
+  --kb-color-fg-on-inverse: #050a05;
+  --kb-color-border-default: #00e637;
+  --kb-color-border-muted: #00b42d;
+  --kb-color-border-focus: #00ff41;
+  --kb-color-accent-default: #00ff41;
+  --kb-color-accent-hover: #00e637;
+  --kb-color-accent-subtle: rgba(74, 222, 128, 0.1);
+  --kb-color-danger-default: #f85149;
+  --kb-color-danger-subtle: #2d1214;
+  --kb-color-success-default: #4ade80;
+  --kb-color-success-subtle: #12261e;
+  --kb-color-warning-default: #d29922;
+  --kb-color-warning-subtle: #2a2111;
+  --kb-space-2xs: 2px;
+  --kb-space-xs: 4px;
+  --kb-space-sm: 8px;
+  --kb-space-md: 16px;
+  --kb-space-lg: 24px;
+  --kb-space-xl: 32px;
+  --kb-space-2xl: 48px;
+  --kb-radius-sm: 2px;
+  --kb-radius-md: 4px;
+  --kb-radius-lg: 6px;
+  --kb-radius-full: 9999px;
+  --kb-font-family-sans: 'VT323', ui-monospace, 'Courier New', monospace;
+  --kb-font-size-sm: 0.875rem;
+  --kb-font-size-md: 1rem;
+  --kb-font-size-lg: 1.125rem;
+  --kb-font-size-xl: 1.25rem;
+  --kb-font-weight-regular: 400;
+  --kb-font-weight-medium: 500;
+  --kb-font-weight-semibold: 600;
+  --kb-line-height-tight: 1.25;
+  --kb-line-height-normal: 1.625;
+  --kb-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.5);
+  --kb-shadow-md: 0 4px 16px rgba(0, 0, 0, 0.55);
+  --kb-focus-ring: 0 0 0 3px rgba(0, 255, 65, 0.35);
+}

package/dist/themes/terminal/light.css

@@ -0,0 +1,53 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ * Source: src/tokens/semantic.ts (+ presets)
+ * Regenerate: bun run tokens:build
+ */
+:root[data-kb-preset="terminal"],
+:root[data-kb-preset="terminal"][data-theme="light"] {
+  --kb-color-bg-canvas: #f8f9fa;
+  --kb-color-bg-surface: #ffffff;
+  --kb-color-bg-subtle: #eef2ee;
+  --kb-color-bg-inverse: #212529;
+  --kb-color-fg-default: #212529;
+  --kb-color-fg-muted: #495057;
+  --kb-color-fg-subtle: #6c757d;
+  --kb-color-fg-on-accent: #ffffff;
+  --kb-color-fg-on-inverse: #f8f9fa;
+  --kb-color-border-default: rgba(0, 102, 0, 0.25);
+  --kb-color-border-muted: rgba(0, 102, 0, 0.15);
+  --kb-color-border-focus: #006600;
+  --kb-color-accent-default: #006600;
+  --kb-color-accent-hover: #008000;
+  --kb-color-accent-subtle: rgba(0, 102, 0, 0.08);
+  --kb-color-danger-default: #b42318;
+  --kb-color-danger-subtle: #fee4e2;
+  --kb-color-success-default: #006600;
+  --kb-color-success-subtle: rgba(0, 102, 0, 0.08);
+  --kb-color-warning-default: #9a6700;
+  --kb-color-warning-subtle: #fff8c5;
+  --kb-space-2xs: 2px;
+  --kb-space-xs: 4px;
+  --kb-space-sm: 8px;
+  --kb-space-md: 16px;
+  --kb-space-lg: 24px;
+  --kb-space-xl: 32px;
+  --kb-space-2xl: 48px;
+  --kb-radius-sm: 2px;
+  --kb-radius-md: 4px;
+  --kb-radius-lg: 6px;
+  --kb-radius-full: 9999px;
+  --kb-font-family-sans: 'VT323', ui-monospace, 'Courier New', monospace;
+  --kb-font-size-sm: 0.875rem;
+  --kb-font-size-md: 1rem;
+  --kb-font-size-lg: 1.125rem;
+  --kb-font-size-xl: 1.25rem;
+  --kb-font-weight-regular: 400;
+  --kb-font-weight-medium: 500;
+  --kb-font-weight-semibold: 600;
+  --kb-line-height-tight: 1.25;
+  --kb-line-height-normal: 1.625;
+  --kb-shadow-sm: 0 1px 2px rgba(0, 102, 0, 0.08);
+  --kb-shadow-md: 0 4px 12px rgba(0, 102, 0, 0.1);
+  --kb-focus-ring: 0 0 0 3px rgba(0, 102, 0, 0.35);
+}

package/dist/tokens/index.d.ts

@@ -3,5 +3,9 @@
  * Import theme CSS in the app (or Storybook) so variables resolve:
  *   import '@ktbsh/ui/themes/light.css'
  *   import '@ktbsh/ui/themes/dark.css'
+ *   import '@ktbsh/ui/themes/terminal/light.css'  // optional preset
+ *   import '@ktbsh/ui/themes/terminal/dark.css'
+ *
+ * Axes: applyTheme('light'|'dark') + applyPreset('default'|'terminal')
  */
-export { applyTheme, cssVar, cssVarName, getTheme, type KitbashTheme, type SemanticTokenName, semanticTokens, type TokenValue, } from './semantic.ts';
+export { applyPreset, applyTheme, cssVar, cssVarName, getPreset, getTheme, type KitbashPreset, type KitbashTheme, type SemanticTokenName, semanticTokens, type TokenValue, } from './semantic.ts';

package/dist/tokens/index.js

@@ -3,5 +3,9 @@
  * Import theme CSS in the app (or Storybook) so variables resolve:
  *   import '@ktbsh/ui/themes/light.css'
  *   import '@ktbsh/ui/themes/dark.css'
+ *   import '@ktbsh/ui/themes/terminal/light.css'  // optional preset
+ *   import '@ktbsh/ui/themes/terminal/dark.css'
+ *
+ * Axes: applyTheme('light'|'dark') + applyPreset('default'|'terminal')
  */
-export { applyTheme, cssVar, cssVarName, getTheme, semanticTokens, } from "./semantic.js";
+export { applyPreset, applyTheme, cssVar, cssVarName, getPreset, getTheme, semanticTokens, } from "./semantic.js";

package/dist/tokens/semantic.d.ts

@@ -1,10 +1,23 @@
 /**
- * Design tokens — single source of truth for names and light/dark values.
- * CSS themes + kitbash `tokens.json` are generated from this module.
+ * Design tokens — single source of truth for names and **default** light/dark values.
+ * CSS themes + kitbash `tokens.json` are generated from this module + presets.
  *
  * CSS custom property for key `color-bg-canvas` → `--kb-color-bg-canvas`
+ *
+ * **Presets** (UI chrome / brand pack), orthogonal to light/dark:
+ * - `default` — neutral/blue DS (no `data-kb-preset` or `data-kb-preset="default"`)
+ * - `terminal` — Matrix-style pack from consumer blog (`data-kb-preset="terminal"`)
+ *
+ * See `docs/consumer-astro-blog-md.md`.
  */
+/** Color scheme axis (night = dark). */
 export type KitbashTheme = 'light' | 'dark';
+/**
+ * Brand / UI-mode axis. Maps to blog `data-ui-mode`:
+ * - default ≈ regular
+ * - terminal ≈ terminal
+ */
+export type KitbashPreset = 'default' | 'terminal';
 export type TokenValue = {
     readonly light: string;
     readonly dark: string;
@@ -201,9 +214,16 @@ export declare function cssVarName(token: SemanticTokenName): `--kb-${SemanticTo
 /** `var(--kb-…)` reference for use in component styles. */
 export declare function cssVar(token: SemanticTokenName): string;
 /**
- * Apply theme on an element (default: document root in browsers).
+ * Apply color scheme on an element (default: document root in browsers).
  * No-op without a DOM root (SSR) unless `root` is passed explicitly.
  */
 export declare function applyTheme(theme: KitbashTheme, root?: HTMLElement): void;
 /** Defaults to `light` when no DOM / no data-theme (SSR-safe). */
 export declare function getTheme(root?: HTMLElement): KitbashTheme;
+/**
+ * Apply brand preset (`data-kb-preset`). Omit/`default` uses base theme CSS only.
+ * Load matching CSS: `@ktbsh/ui/themes/terminal/light.css` + `dark.css` for terminal.
+ */
+export declare function applyPreset(preset: KitbashPreset, root?: HTMLElement): void;
+/** Defaults to `default` when unset (SSR-safe). */
+export declare function getPreset(root?: HTMLElement): KitbashPreset;