@skdx/docs-kit 0.35.0

package/dist/themes/DefaultTheme.ts

@@ -0,0 +1,137 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import { type Theme, type ThemeOverride } from '../utils/theme';
+
+/** The reference {@link Theme} ("skanda-light") every other theme overrides via {@link createTheme}. @public */
+export const defaultTheme: Theme = {
+  name: 'skanda-light',
+  mode: 'light',
+  colors: {
+    primary: {
+      50: '#eef4ff',
+      100: '#dce7fd',
+      200: '#c0d4fc',
+      300: '#94b8fa',
+      400: '#6193f5',
+      500: '#3d6eef',
+      600: '#274ee3',
+      700: '#1f3bd0',
+      800: '#2032a9',
+      900: '#1f2f85',
+      950: '#171f51',
+    },
+    neutral: {
+      50: '#f8fafc',
+      100: '#f1f5f9',
+      200: '#e2e8f0',
+      300: '#cbd5e1',
+      400: '#94a3b8',
+      500: '#64748b',
+      600: '#475569',
+      700: '#334155',
+      800: '#1e293b',
+      900: '#0f172a',
+      950: '#020617',
+    },
+    success: {
+      50: '#f0fdf4',
+      100: '#dcfce7',
+      200: '#bbf7d0',
+      300: '#86efac',
+      400: '#4ade80',
+      500: '#22c55e',
+      600: '#16a34a',
+      700: '#15803d',
+      800: '#166534',
+      900: '#14532d',
+      950: '#052e16',
+    },
+    warning: {
+      50: '#fffbeb',
+      100: '#fef3c7',
+      200: '#fde68a',
+      300: '#fcd34d',
+      400: '#fbbf24',
+      500: '#f59e0b',
+      600: '#d97706',
+      700: '#b45309',
+      800: '#92400e',
+      900: '#78350f',
+      950: '#451a03',
+    },
+    danger: {
+      50: '#fef2f2',
+      100: '#fee2e2',
+      200: '#fecaca',
+      300: '#fca5a5',
+      400: '#f87171',
+      500: '#ef4444',
+      600: '#dc2626',
+      700: '#b91c1c',
+      800: '#991b1b',
+      900: '#7f1d1d',
+      950: '#450a0a',
+    },
+    semantic: {
+      background: '#ffffff',
+      surface: '#f8fafc',
+      surfaceHover: '#f1f5f9',
+      overlay: 'rgb(2 6 23 / 0.5)',
+      text: '#0f172a',
+      textMuted: '#64748b',
+      textInverted: '#ffffff',
+      border: '#e2e8f0',
+      borderStrong: '#7791b0',
+      focusRing: '#3d6eef',
+    },
+  },
+  // strength: '1' is the reference every base alpha in foundation.ts's shadow geometry is calibrated against.
+  shadow: { color: '2 6 23', strength: '1' },
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function deepMerge<T>(base: T, override: Record<string, unknown>): T {
+  const result: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+    const baseValue = result[key];
+    result[key] = isObject(baseValue) && isObject(value) ? deepMerge(baseValue, value) : value;
+  }
+  return result as T;
+}
+
+/**
+ * Deep-merges a {@link ThemeOverride} onto a base theme to produce a complete
+ * {@link Theme}, so brand themes only need to specify what differs.
+ *
+ * @param name - Unique theme name, e.g. `'acme'`. Becomes `theme.name` and the `[data-skdx-theme="acme"]` selector, overriding any `name` in `override`.
+ * @param override - Partial values to merge onto `base`. Objects merge key-by-key (deeply); primitives replace outright.
+ * @param base - Theme to merge onto. @default defaultTheme
+ * @returns A complete {@link Theme} ready for {@link themeToCss} or {@link applyTheme}.
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from '@skdx/tokens';
+ *
+ * const acme = createTheme('acme', {
+ *   colors: { primary: { 500: '#e11d48', 600: '#be123c' }, semantic: { focusRing: '#e11d48' } },
+ *   radii: { md: '0.25rem' },
+ * });
+ * ```
+ *
+ * @public
+ */
+export function createTheme(
+  name: string,
+  override: ThemeOverride = {},
+  base: Theme = defaultTheme,
+): Theme {
+  return { ...deepMerge(base, override as Record<string, unknown>), name };
+}

package/dist/themes/DraculaDark.md

@@ -0,0 +1,14 @@
+---
+upstream: Dracula
+deviations:
+  - token: text-muted
+    upstream: #929cc3
+    ours: #939dc4
+    reason: Read 4.48:1 against selected, under the 4.5:1 floor for body text.
+      Lightened on lightness alone, hue and saturation kept, to clear 4.5:1
+      against selected.
+---
+
+# themes/dracula-dark.ts
+
+Character: Dracula purple primary actions (`#bd93f9` at 400, ramp centered on it), the classic `#282a36` background with slightly lifted `surface`/`surfaceHover` panels, Dracula's near-white foreground text (`#f8f8f2`), and a neutral ramp remapped to Dracula's "current line"/comment grays in its dark steps.

package/dist/themes/DraculaDark.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+
+/** Dracula inspired dark theme: purple actions on the classic #282a36 background. @public */
+export const draculaDark: Theme = {
+  name: 'dracula',
+  mode: 'dark',
+  colors: {
+    primary: {
+      50: '#fbf9ff',
+      100: '#f6f0fe',
+      200: '#ebdffd',
+      300: '#dec9fc',
+      400: '#d2b6fb',
+      500: '#c8a4fa',
+      600: '#bd93f9',
+      700: '#9978ca',
+      800: '#7d62a5',
+      900: '#644f84',
+      950: '#3c3051',
+    },
+    neutral: {
+      50: '#f8fafc',
+      100: '#f1f5f9',
+      200: '#44475a',
+      300: '#565b74',
+      400: '#94a3b8',
+      500: '#64748b',
+      600: '#475569',
+      700: '#334155',
+      800: '#1e293b',
+      900: '#191a21',
+      950: '#020617',
+    },
+    success: {
+      50: '#f0fdf4',
+      100: '#dcfce7',
+      200: '#bbf7d0',
+      300: '#86efac',
+      400: '#4ade80',
+      500: '#50fa7b',
+      600: '#3fd968',
+      700: '#2fb355',
+      800: '#166534',
+      900: '#14532d',
+      950: '#052e16',
+    },
+    warning: {
+      50: '#fffbeb',
+      100: '#fef3c7',
+      200: '#fde68a',
+      300: '#fcd34d',
+      400: '#fbbf24',
+      500: '#ffb86c',
+      600: '#f5a15a',
+      700: '#d98443',
+      800: '#92400e',
+      900: '#78350f',
+      950: '#451a03',
+    },
+    danger: {
+      50: '#fef2f2',
+      100: '#fee2e2',
+      200: '#fecaca',
+      300: '#fca5a5',
+      400: '#f87171',
+      500: '#ff5555',
+      600: '#e64747',
+      700: '#c43a3a',
+      800: '#991b1b',
+      900: '#7f1d1d',
+      950: '#450a0a',
+    },
+    semantic: {
+      background: '#282a36',
+      surface: '#313342',
+      surfaceHover: '#3a3d4e',
+      overlay: 'rgb(0 0 0 / 0.6)',
+      text: '#f8f8f2',
+      textMuted: '#939dc4',
+      textInverted: '#282a36',
+      border: '#44475a',
+      borderStrong: '#777d9a',
+      focusRing: '#bd93f9',
+    },
+  },
+  shadow: { color: '0 0 0', strength: '5.2' },
+};

package/dist/themes/DraculaLight.md

@@ -0,0 +1,8 @@
+---
+upstream: Alucard (Dracula's light theme)
+deviations: []
+---
+
+# themes/dracula-light.ts
+
+Exports **`draculaLight`** — a light theme registered as `data-skdx-theme="dracula-light"`, the `dracula` brand's light mode — **Alucard**, Dracula's own published light theme rather than an inversion of the dark one — warm `#fffbeb` paper, `#1f1f1f` ink, olive-comment muted text (`#6c664b`), and Alucard's deeper `#644ac9` purple at 600 in place of Dracula's `#bd93f9`.

package/dist/themes/DraculaLight.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+import { createTheme } from './DefaultTheme';
+import { draculaDark } from './DraculaDark';
+
+/**
+ * Light counterpart of `dracula` — Alucard's published palette, not an inversion of the dark theme.
+ *
+ * @public
+ */
+export const draculaLight: Theme = createTheme(
+  'dracula-light',
+  {
+    mode: 'light',
+    colors: {
+      primary: {
+        50: '#f6f4fc',
+        100: '#e9e6f7',
+        200: '#d1c9ef',
+        300: '#b2a5e4',
+        400: '#9684da',
+        500: '#7d67d2',
+        600: '#644ac9',
+        700: '#523da4',
+        800: '#443386',
+        900: '#372a6c',
+        950: '#231c43',
+      },
+      neutral: { 200: '#eae5cf', 300: '#d9d3ba' },
+      // Dracula's neon status hues wash out on paper; these take Alucard's own light-mode values.
+      success: { 600: '#14710a' },
+      warning: { 600: '#846e15' },
+      danger: { 600: '#cb3a2a' },
+      semantic: {
+        background: '#fffbeb',
+        surface: '#f6f2e0',
+        surfaceHover: '#ede9d6',
+        overlay: 'rgb(31 31 31 / 0.4)',
+        text: '#1f1f1f',
+        textMuted: '#6c664b',
+        textInverted: '#ffffff',
+        border: '#eae5cf',
+        borderStrong: '#8a8468',
+        focusRing: '#644ac9',
+      },
+    },
+    shadow: { color: '2 6 23', strength: '1' },
+  },
+  draculaDark,
+);

package/dist/themes/EmeraldDark.md

@@ -0,0 +1,8 @@
+---
+upstream: none
+deviations: []
+---
+
+# themes/emerald-dark.ts
+
+Exports **`emeraldDark`** — a dark theme registered as `data-skdx-theme="emerald-dark"`, the `emerald` brand's dark mode — emerald primaries shifted one step lighter (`#10b981` at 600) with dark inverted text (closing emerald-brand's known white-on-primary AA gap), on deep green-tinted surfaces (`background: #04211a`).

package/dist/themes/EmeraldDark.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+import { createTheme } from './DefaultTheme';
+import { emeraldLight } from './EmeraldLight';
+
+/** Dark counterpart of `emerald-brand`, shifting the primary ramp one step lighter with dark inverted text. @public */
+export const emeraldDark: Theme = createTheme(
+  'emerald-dark',
+  {
+    mode: 'dark',
+    colors: {
+      primary: { 400: '#6ee7b7', 500: '#34d399', 600: '#10b981', 700: '#059669' },
+      neutral: { 200: '#14453a', 300: '#1e5c4c', 800: '#06392d', 900: '#04211a', 950: '#021711' },
+      semantic: {
+        background: '#04211a',
+        surface: '#06392d',
+        surfaceHover: '#0b4a3b',
+        overlay: 'rgb(0 0 0 / 0.6)',
+        text: '#e7f6ee',
+        textMuted: '#8fb3a4',
+        textInverted: '#04211a',
+        border: '#14453a',
+        borderStrong: '#2d8a72',
+        focusRing: '#34d399',
+      },
+    },
+    shadow: { color: '0 0 0', strength: '4.7' },
+  },
+  emeraldLight,
+);

package/dist/themes/EmeraldLight.md

@@ -0,0 +1,8 @@
+---
+upstream: none
+deviations: []
+---
+
+# themes/emerald-light.ts
+
+Character: fresh emerald primary ramp (`#10b981` at 500), soft mint-tinted surfaces (`background: #fbfefc`, green-tinged `surface`/`surfaceHover`), deep green text (`#0d2b1e`), and notably tight corners (`sm: 0.125rem` … `xl: 0.5rem`) compared to the default theme. Typography and spacing follow the default system stack.

package/dist/themes/EmeraldLight.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+
+/** Emerald green brand: fresh greens with soft mint surfaces and tight corners. @public */
+export const emeraldLight: Theme = {
+  name: 'emerald-brand',
+  mode: 'light',
+  colors: {
+    primary: {
+      50: '#ecfdf5',
+      100: '#d1fae5',
+      200: '#a7f3d0',
+      300: '#6ee7b7',
+      400: '#34d399',
+      500: '#10b981',
+      600: '#059669',
+      700: '#047857',
+      800: '#065f46',
+      900: '#064e3b',
+      950: '#022c22',
+    },
+    neutral: {
+      50: '#f8fafc',
+      100: '#f1f5f9',
+      200: '#e2e8f0',
+      300: '#cbd5e1',
+      400: '#94a3b8',
+      500: '#64748b',
+      600: '#475569',
+      700: '#334155',
+      800: '#1e293b',
+      900: '#0f172a',
+      950: '#020617',
+    },
+    success: {
+      50: '#f0fdf4',
+      100: '#dcfce7',
+      200: '#bbf7d0',
+      300: '#86efac',
+      400: '#4ade80',
+      500: '#22c55e',
+      600: '#16a34a',
+      700: '#15803d',
+      800: '#166534',
+      900: '#14532d',
+      950: '#052e16',
+    },
+    warning: {
+      50: '#fffbeb',
+      100: '#fef3c7',
+      200: '#fde68a',
+      300: '#fcd34d',
+      400: '#fbbf24',
+      500: '#f59e0b',
+      600: '#d97706',
+      700: '#b45309',
+      800: '#92400e',
+      900: '#78350f',
+      950: '#451a03',
+    },
+    danger: {
+      50: '#fef2f2',
+      100: '#fee2e2',
+      200: '#fecaca',
+      300: '#fca5a5',
+      400: '#f87171',
+      500: '#ef4444',
+      600: '#dc2626',
+      700: '#b91c1c',
+      800: '#991b1b',
+      900: '#7f1d1d',
+      950: '#450a0a',
+    },
+    semantic: {
+      background: '#fbfefc',
+      surface: '#f2faf5',
+      surfaceHover: '#e6f5ec',
+      overlay: 'rgb(2 44 34 / 0.5)',
+      text: '#0d2b1e',
+      textMuted: '#576d64',
+      textInverted: '#1c1c1c',
+      border: '#d8ebe0',
+      borderStrong: '#529e75',
+      focusRing: '#059669',
+    },
+  },
+  shadow: { color: '2 6 23', strength: '1' },
+};

package/dist/themes/EverforestDark.md

@@ -0,0 +1,26 @@
+---
+upstream: Everforest
+deviations:
+  - token: danger-600
+    upstream: none
+    ours: #cf5457
+    reason: Read 2.30:1 against the theme background, under the 3:1 floor for status
+      ramps. Lightened on lightness alone, hue and saturation kept, to reach 3.00:1
+      contrast against the theme background.
+  - token: success-600
+    upstream: none
+    ours: #438b59
+    reason: Read 2.24:1 against the theme background, under the 3:1 floor for status
+      ramps. Lightened on lightness alone, hue and saturation kept, to reach 3.01:1
+      contrast against the theme background.
+  - token: warning-600
+    upstream: none
+    ours: #a87129
+    reason: Read 2.91:1 against the theme background, under the 3:1 floor for status
+      ramps. Lightened on lightness alone, hue and saturation kept, to reach 3.00:1
+      contrast against the theme background.
+---
+
+# themes/everforest-dark.ts
+
+Character: forest `#2d353b` background with `#343f44` surfaces, sage green actions (`#a7c080` at 300) with dark inverted text, aqua/yellow/red status hues, warm cream text (`#d3c6aa`), and a neutral ramp built from the Everforest bg/grey tones.

package/dist/themes/EverforestDark.ts

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+
+/**
+ * Everforest Dark inspired theme: green-on-forest palette with
+ * warm cream text, sage green actions, and aqua/yellow/red status hues.
+ *
+ * @public
+ */
+export const everforestDark: Theme = {
+  name: 'everforest-dark',
+  mode: 'dark',
+  colors: {
+    primary: {
+      50: '#fafbf7',
+      100: '#f3f6ed',
+      200: '#e5ecd9',
+      300: '#d3e0c0',
+      400: '#c3d4a9',
+      500: '#b5ca94',
+      600: '#a7c080',
+      700: '#889c69',
+      800: '#6e7e57',
+      900: '#596548',
+      950: '#363d2f',
+    },
+    neutral: {
+      50: '#f7f4eb',
+      100: '#ece4cf',
+      200: '#3d484d',
+      300: '#475258',
+      400: '#9da9a0',
+      500: '#859289',
+      600: '#7a8478',
+      700: '#4f585e',
+      800: '#3d484d',
+      900: '#232a2e',
+      950: '#232a2e',
+    },
+    success: {
+      50: '#f1f9f3',
+      100: '#def0e3',
+      200: '#c1e2ca',
+      300: '#83c092',
+      400: '#62ab74',
+      500: '#47905c',
+      600: '#438b59',
+      700: '#305d3e',
+      800: '#2a4a34',
+      900: '#253e2e',
+      950: '#112218',
+    },
+    warning: {
+      50: '#fcf9f0',
+      100: '#f8f0db',
+      200: '#f0e0b4',
+      300: '#dbbc7f',
+      400: '#cfa254',
+      500: '#c08a35',
+      600: '#a87129',
+      700: '#845424',
+      800: '#6c4423',
+      900: '#5b3a21',
+      950: '#331d0e',
+    },
+    danger: {
+      50: '#fdf3f3',
+      100: '#fbe5e5',
+      200: '#f8d0d1',
+      300: '#f2abac',
+      400: '#e67e80',
+      500: '#d75052',
+      600: '#cf5457',
+      700: '#a2292c',
+      800: '#862527',
+      900: '#732426',
+      950: '#3e0e0f',
+    },
+    semantic: {
+      background: '#2d353b',
+      surface: '#343f44',
+      surfaceHover: '#3d484d',
+      overlay: 'rgb(0 0 0 / 0.6)',
+      text: '#d3c6aa',
+      // Lightened from the palette's grey-1 #a0aaa3 so muted text clears 4.5:1 on surface-sunken.
+      textMuted: '#aeb6b0',
+      textInverted: '#2d353b',
+      border: '#3d484d',
+      borderStrong: '#7b8b94',
+      focusRing: '#a7c080',
+    },
+  },
+  shadow: { color: '0 0 0', strength: '4.7' },
+};

package/dist/themes/EverforestLight.md

@@ -0,0 +1,31 @@
+---
+upstream: Everforest
+deviations:
+  - token: primary-600
+    upstream: #8da101 (500)
+    ours: #6b7a00
+    reason: Everforest light's olive green at 500 fails AA contrast for white label text
+      on filled buttons. Darkened one step in lightness only, hue and saturation kept.
+  - token: text
+    upstream: #5c6a72
+    ours: #58666d
+    reason: Read 4.29:1 against pressed and 3.08:1 against the secondary button's
+      pressed fill, under the 4.5:1 floor for body text. Darkened on lightness
+      alone, hue and saturation kept, to clear 4.5:1 against both fills.
+  - token: text-muted
+    upstream: #626f61
+    ours: #5b675a
+    reason: Read 4.41:1 against hover and 4.06:1 against pressed, under the 4.5:1
+      floor for body text. Darkened on lightness alone, hue and saturation kept,
+      to clear 4.5:1 against both fills.
+  - token: neutral-600
+    upstream: #7a8478
+    ours: #798377
+    reason: Everforest light's disabled ink read 2.98:1 against pressed, under the
+      3:1 floor for disabled ink. Darkened on lightness alone, hue and saturation
+      kept, to clear 3:1 against pressed.
+---
+
+# themes/everforest-light.ts
+
+Exports **`everforestLight`** — a light theme registered as `data-skdx-theme="everforest-light"`, the `everforest` brand's light mode, built on Everforest's light palette — `background: #fdf6e3`, sage-green text, and Everforest light's own olive green (`#8da101` at 500) darkened to `#6b7a00` at 600 so white labels pass AA — not the dark palette's sage `#a7c080`.

package/dist/themes/EverforestLight.ts

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+import { createTheme } from './DefaultTheme';
+import { everforestDark } from './EverforestDark';
+
+/**
+ * Light counterpart of `everforest-dark`, with Everforest's light palette (#fdf6e3 background, sage greens) and its light-specific green (#8da101).
+ *
+ * @public
+ */
+export const everforestLight: Theme = createTheme(
+  'everforest-light',
+  {
+    mode: 'light',
+    colors: {
+      primary: {
+        50: '#f6f7f0',
+        100: '#eaecdb',
+        200: '#d3d7b3',
+        300: '#b5bd80',
+        400: '#9aa552',
+        500: '#8da101',
+        600: '#6b7a00',
+        700: '#586403',
+        800: '#485205',
+        900: '#3b4208',
+        950: '#25290b',
+      },
+      neutral: { 200: '#e6e2cc', 300: '#bdc3af', 600: '#798377' },
+      semantic: {
+        background: '#fdf6e3',
+        surface: '#f4f0d9',
+        surfaceHover: '#efebd4',
+        overlay: 'rgb(45 53 59 / 0.4)',
+        text: '#58666d',
+        textMuted: '#5b675a',
+        textInverted: '#ffffff',
+        border: '#e6e2cc',
+        borderStrong: '#838d6a',
+        focusRing: '#6b7a00',
+      },
+    },
+    shadow: { color: '2 6 23', strength: '1' },
+  },
+  everforestDark,
+);

package/dist/themes/FluentDark.md

@@ -0,0 +1,8 @@
+---
+upstream: Microsoft Fluent 2
+deviations: []
+---
+
+# themes/fluent-dark.ts
+
+Exports **`fluentDark`** — a dark theme registered as `data-skdx-theme="fluent-dark"`, the `fluent` brand's dark mode, following Microsoft Fluent 2 dark neutrals — `background: #1f1f1f`, `surface: #292929`, white text, and the same Fluent blue primary ramp with the brighter `#479ef5` focus ring.