@skdx/docs-kit 0.35.0

package/dist/themes/CatppuccinMocha.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';
+
+/** Catppuccin Mocha inspired dark theme: pastel accents on the signature `#1e1e2e` base. Palette source: catppuccin/catppuccin (MIT). @public */
+export const catppuccinMocha: Theme = {
+  name: 'catppuccin-mocha',
+  mode: 'dark',
+  colors: {
+    primary: {
+      50: '#f8fbff',
+      100: '#eef5fe',
+      200: '#dce9fe',
+      300: '#c4dafd',
+      400: '#afccfc',
+      500: '#9cc0fb',
+      600: '#89b4fa',
+      700: '#7092cb',
+      800: '#5b77a5',
+      900: '#4a5f85',
+      950: '#2e3a51',
+    },
+    neutral: {
+      50: '#f5f6fb',
+      100: '#eaedf8',
+      200: '#45475a',
+      300: '#585b70',
+      400: '#9399b2',
+      500: '#7f849c',
+      600: '#6c7086',
+      700: '#45475a',
+      800: '#313244',
+      900: '#11111b',
+      950: '#11111b',
+    },
+    success: {
+      50: '#f2fbf1',
+      100: '#e2f6e0',
+      200: '#c8edc4',
+      300: '#a6e3a1',
+      400: '#7ed177',
+      500: '#5cb954',
+      600: '#479c41',
+      700: '#3a7c36',
+      800: '#32632f',
+      900: '#2b5229',
+      950: '#122d11',
+    },
+    warning: {
+      50: '#fefaf0',
+      100: '#fdf3da',
+      200: '#f9e2af',
+      300: '#f5cd79',
+      400: '#f0b34a',
+      500: '#e99b2b',
+      600: '#cd7d1f',
+      700: '#aa5f1c',
+      800: '#8a4b1d',
+      900: '#713e1b',
+      950: '#401f0c',
+    },
+    danger: {
+      50: '#fef1f5',
+      100: '#fde3ea',
+      200: '#fbcbd9',
+      300: '#f8a8bf',
+      400: '#f38ba8',
+      500: '#e75c85',
+      600: '#d23a6c',
+      700: '#b02b59',
+      800: '#932750',
+      900: '#7d2549',
+      950: '#450f24',
+    },
+    semantic: {
+      background: '#1e1e2e',
+      surface: '#2a2b3d',
+      surfaceHover: '#313244',
+      overlay: 'rgb(0 0 0 / 0.6)',
+      text: '#cdd6f4',
+      textMuted: '#a6adc8',
+      textInverted: '#1e1e2e',
+      border: '#45475a',
+      borderStrong: '#71758f',
+      focusRing: '#89b4fa',
+    },
+  },
+  shadow: { color: '0 0 0', strength: '4.7' },
+};

package/dist/themes/ChakraDark.md

@@ -0,0 +1,8 @@
+---
+upstream: Chakra UI
+deviations: []
+---
+
+# themes/chakra-teal-dark.ts
+
+Exports **`chakraDark`** — a dark theme registered as `data-skdx-theme="chakra-teal-dark"`, the `chakra` brand's dark mode, following Chakra UI's dark gray.800 body (`background: #1a202c`) with gray.700 borders and the same teal primary ramp as `chakra-teal`.

package/dist/themes/ChakraDark.ts

@@ -0,0 +1,47 @@
+/*
+ * 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 { chakraLight } from './ChakraLight';
+import { createTheme } from './DefaultTheme';
+
+/** Dark counterpart of `chakra-teal`, with Chakra UI's dark gray backgrounds and `teal.300` for contrast on dark surfaces. @public */
+export const chakraDark: Theme = createTheme(
+  'chakra-teal-dark',
+  {
+    mode: 'dark',
+    colors: {
+      primary: {
+        50: '#f4fcfc',
+        100: '#e6f9f7',
+        200: '#caf1ee',
+        300: '#a7e8e2',
+        400: '#87e0d8',
+        500: '#6bd8ce',
+        600: '#4fd1c5',
+        700: '#41a9a1',
+        800: '#368983',
+        900: '#2d6e6a',
+        950: '#1d4242',
+      },
+      neutral: { 200: '#2d3748', 300: '#4a5568', 800: '#232c3b', 900: '#1a202c', 950: '#12161f' },
+      semantic: {
+        background: '#1a202c',
+        surface: '#232c3b',
+        surfaceHover: '#2d3748',
+        overlay: 'rgb(0 0 0 / 0.6)',
+        text: '#edf2f7',
+        textMuted: '#a0aec0',
+        textInverted: '#1a202c',
+        border: '#2d3748',
+        borderStrong: '#66758f',
+        focusRing: '#63b3ed',
+      },
+    },
+    shadow: { color: '0 0 0', strength: '4.7' },
+  },
+  chakraLight,
+);

package/dist/themes/ChakraLight.md

@@ -0,0 +1,14 @@
+---
+upstream: Chakra UI
+deviations:
+  - token: text-muted
+    upstream: #657389
+    ours: #5c697d
+    reason: Read 4.27:1 against hover and 3.90: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.
+---
+
+# themes/chakra-light.ts
+
+Character: Chakra's teal primary ramp (`#319795` at 500), its signature blue focus ring (distinct from the primary hue, as in Chakra's `outline` style), cool gray surfaces (`surface: #f7fafc`), dark slate text (`#1a202c`), and Chakra's corner scale (`sm: 0.125rem`, `md: 0.375rem`, `lg: 0.5rem`, `xl: 0.75rem`).

package/dist/themes/ChakraLight.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';
+
+/** Chakra UI inspired: teal actions with Chakra's signature blue focus ring. @public */
+export const chakraLight: Theme = {
+  name: 'chakra-teal',
+  mode: 'light',
+  colors: {
+    primary: {
+      50: '#e6fffa',
+      100: '#b2f5ea',
+      200: '#81e6d9',
+      300: '#4fd1c5',
+      400: '#38b2ac',
+      500: '#319795',
+      600: '#2c7a7b',
+      700: '#285e61',
+      800: '#234e52',
+      900: '#1d4044',
+      950: '#112a2d',
+    },
+    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: '#f7fafc',
+      surfaceHover: '#edf2f7',
+      overlay: 'rgb(0 0 0 / 0.48)',
+      text: '#1a202c',
+      textMuted: '#5c697d',
+      textInverted: '#ffffff',
+      border: '#e2e8f0',
+      borderStrong: '#7892ae',
+      focusRing: '#3182ce',
+    },
+  },
+  shadow: { color: '2 6 23', strength: '1' },
+};

package/dist/themes/Contrast.test.ts

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { contrastRatio } from '../utils/contrast';
+import type { Theme } from '../utils/theme';
+import { themes } from './index';
+
+const SEMANTIC_PAIRS = [
+  ['text', 'background', 4.5],
+  ['text', 'surface', 4.5],
+  ['textMuted', 'background', 4.5],
+  ['textMuted', 'surface', 4.5],
+  ['borderStrong', 'background', 3],
+  ['borderStrong', 'surface', 3],
+  ['focusRing', 'background', 3],
+] as const;
+
+const STATUS_RAMPS = ['primary', 'success', 'warning', 'danger'] as const;
+
+// Fills that ink lands on via aliases.ts: hover/pressed/selected are ramp steps, not semantic entries.
+const fillsOf = (theme: Theme) => {
+  const { semantic: s, neutral: n, primary: p } = theme.colors;
+  return theme.mode === 'light'
+    ? { hover: s.surfaceHover, pressed: n[200], selected: p[50] }
+    : { hover: n[800], pressed: n[900], selected: p[950] };
+};
+
+const measurements = themes.flatMap((theme) => {
+  const s = theme.colors.semantic;
+  const light = theme.mode === 'light';
+  const fills = fillsOf(theme);
+  const rows: Array<{ theme: string; fg: string; bg: string; ratio: number; min: number }> = [];
+
+  const measure = (fg: string, bg: string, fgHex: string, bgHex: string, min: number) => {
+    rows.push({ theme: theme.name, fg, bg, ratio: contrastRatio(fgHex, bgHex), min });
+  };
+
+  for (const [fg, bg, min] of SEMANTIC_PAIRS) measure(fg, bg, s[fg], s[bg], min);
+  for (const [name, hex] of Object.entries(fills)) {
+    measure('text', name, s.text, hex, 4.5);
+    measure('textMuted', name, s.textMuted, hex, 4.5);
+  }
+  const accent = light ? theme.colors.primary[700] : theme.colors.primary[300];
+  for (const [name, hex] of [
+    ['background', s.background],
+    ['surface', s.surface],
+    ['hover', fills.hover],
+    ['selected', fills.selected],
+  ] as const) {
+    measure('text-accent', name, accent, hex, 4.5);
+  }
+  const disabled = light ? theme.colors.neutral[600] : theme.colors.neutral[400];
+  measure('text-disabled', 'surface', disabled, s.surface, 3);
+  measure(
+    'text-disabled',
+    light ? 'pressed' : 'hover',
+    disabled,
+    light ? fills.pressed : fills.hover,
+    3,
+  );
+  measure('textInverted', 'primary-600', s.textInverted, theme.colors.primary[600], 4.5);
+  for (const ramp of STATUS_RAMPS) {
+    measure(`${ramp}-600`, 'background', theme.colors[ramp][600], s.background, 3);
+  }
+  return rows;
+});
+
+describe('theme contrast', () => {
+  it.each(measurements.map((m) => [`${m.theme} — ${m.fg} on ${m.bg}`, m] as const))(
+    '%s meets its WCAG threshold',
+    (_label, m) => {
+      expect(m.ratio).toBeGreaterThanOrEqual(m.min);
+    },
+  );
+});

package/dist/themes/CupcakeDark.md

@@ -0,0 +1,8 @@
+---
+upstream: daisyUI Cupcake
+deviations: []
+---
+
+# themes/cupcake-dark.ts
+
+Exports **`cupcakeDark`** — a dark theme registered as `data-skdx-theme="cupcake-dark"`, the `cupcake` brand's dark mode — the pastel teal primary shifted lighter (`#43a8ae` at 600, dark teal inverted text, closing cupcake-light's known AA gap) on deep plum surfaces built from cupcake's `#291334` ink.

package/dist/themes/CupcakeDark.ts

@@ -0,0 +1,39 @@
+/*
+ * 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 { cupcakeLight } from './CupcakeLight';
+import { createTheme } from './DefaultTheme';
+
+/**
+ * Dark counterpart of `cupcake-light` — pastel teal primary on deep plum surfaces built from cupcake's #291334 ink color.
+ *
+ * @public
+ */
+export const cupcakeDark: Theme = createTheme(
+  'cupcake-dark',
+  {
+    mode: 'dark',
+    colors: {
+      primary: { 600: '#43a8ae', 700: '#388a92' },
+      neutral: { 200: '#433050', 300: '#55405f', 800: '#33203f', 900: '#291334', 950: '#1d0c26' },
+      semantic: {
+        background: '#291334',
+        surface: '#33203f',
+        surfaceHover: '#3d2a4a',
+        overlay: 'rgb(0 0 0 / 0.6)',
+        text: '#f5eefa',
+        textMuted: '#b3a4c0',
+        textInverted: '#0c2b2d',
+        border: '#433050',
+        borderStrong: '#866596',
+        focusRing: '#65c3c8',
+      },
+    },
+    shadow: { color: '0 0 0', strength: '4.7' },
+  },
+  cupcakeLight,
+);

package/dist/themes/CupcakeLight.md

@@ -0,0 +1,31 @@
+---
+upstream: daisyUI Cupcake
+deviations:
+  - token: success-*, warning-*, danger-*
+    upstream: none
+    ours: SkandaDX default ramps, unchanged
+    reason: daisyUI's cupcake theme leaves status colors undefined, so cupcake-light keeps
+      SkandaDX's default success, warning and danger ramps rather than inventing new hues.
+  - token: warning-600
+    upstream: none
+    ours: #d87606
+    reason: Read 2.99:1 against the theme background, under the 3:1 floor for status
+      ramps. Darkened on lightness alone, hue and saturation kept, to reach 3.02:1
+      contrast against the theme background.
+  - token: text-muted
+    upstream: #6f6560
+    ours: #6d635e
+    reason: Read 4.41:1 against hover and 4.41: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: primary-700
+    upstream: #327078
+    ours: #316e76
+    reason: Cupcake's teal link ink read 4.39:1 against hover, under the 4.5:1
+      floor for body text. Darkened on lightness alone, hue and saturation kept,
+      to clear 4.5:1 against hover.
+---
+
+# themes/cupcake-light.ts
+
+Character: creamy `#faf7f5` background with warm putty surfaces (`#efeae6`, `#e7e2df`), soft teal actions (`#65c3c8` at 400), deep plum text (`#291334`), extra-round corners (md `0.75rem`, xl `1.5rem`), and default SkandaDX status ramps (daisyUI leaves status colors to defaults). Typography follows the default theme.

package/dist/themes/CupcakeLight.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';
+
+/** Cupcake inspired pastel light theme: creamy `#faf7f5` background, soft teal actions, extra-round corners. Inspired by daisyUI's "cupcake" theme (saadeghi/daisyui, MIT). @public */
+export const cupcakeLight: Theme = {
+  name: 'cupcake-light',
+  mode: 'light',
+  colors: {
+    primary: {
+      50: '#f0fafa',
+      100: '#dcf2f3',
+      200: '#bfe7e9',
+      300: '#94d7da',
+      400: '#65c3c8',
+      500: '#43a8ae',
+      600: '#388a92',
+      700: '#316e76',
+      800: '#2f5d64',
+      900: '#2b4e55',
+      950: '#183339',
+    },
+    neutral: {
+      50: '#faf7f5',
+      100: '#efeae6',
+      200: '#e7e2df',
+      300: '#d4cdc9',
+      400: '#a89f9a',
+      500: '#8a807b',
+      600: '#6f6560',
+      700: '#5a514d',
+      800: '#453e3b',
+      900: '#322b29',
+      950: '#291334',
+    },
+    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: '#d87606',
+      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: '#faf7f5',
+      surface: '#efeae6',
+      surfaceHover: '#e7e2df',
+      overlay: 'rgb(41 19 52 / 0.4)',
+      text: '#291334',
+      textMuted: '#6d635e',
+      textInverted: '#141414',
+      border: '#e7e2df',
+      borderStrong: '#95837a',
+      focusRing: '#369298',
+    },
+  },
+  shadow: { color: '41 19 52', strength: '1' },
+};

package/dist/themes/DefaultTheme.md

@@ -0,0 +1,8 @@
+---
+upstream: none
+deviations: []
+---
+
+# themes/default-theme.ts
+
+The **reference theme** and the **theme factory**. Every other theme in the system is conceptually an override of this base.

package/dist/themes/DefaultTheme.test.ts

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { createTheme, defaultTheme } from './DefaultTheme';
+
+describe('defaultTheme', () => {
+  it('is named skanda-light', () => {
+    expect(defaultTheme.name).toBe('skanda-light');
+  });
+
+  it('defines a full 50-950 scale for every color ramp', () => {
+    const steps = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
+    for (const ramp of ['primary', 'neutral', 'success', 'warning', 'danger'] as const) {
+      for (const step of steps) {
+        expect(defaultTheme.colors[ramp][step]).toMatch(/^#[0-9a-f]{6}$/i);
+      }
+    }
+  });
+
+  it('defines every semantic color token', () => {
+    const semantic = defaultTheme.colors.semantic;
+    for (const key of [
+      'background',
+      'surface',
+      'surfaceHover',
+      'overlay',
+      'text',
+      'textMuted',
+      'textInverted',
+      'border',
+      'borderStrong',
+      'focusRing',
+    ] as const) {
+      expect(semantic[key]).toBeTruthy();
+    }
+  });
+});
+
+describe('createTheme', () => {
+  it('returns the default theme unchanged when called with no override', () => {
+    const theme = createTheme('skanda-light');
+    expect(theme).toEqual(defaultTheme);
+  });
+
+  it('sets the provided name regardless of base or override', () => {
+    const theme = createTheme('acme-dark');
+    expect(theme.name).toBe('acme-dark');
+  });
+
+  it('deep-merges a nested override without disturbing sibling keys', () => {
+    const theme = createTheme('acme-dark', { colors: { primary: { 500: '#ff0000' } } });
+
+    expect(theme.colors.primary[500]).toBe('#ff0000');
+    expect(theme.colors.primary[600]).toBe(defaultTheme.colors.primary[600]);
+    expect(theme.colors.neutral).toEqual(defaultTheme.colors.neutral);
+  });
+
+  it('merges across multiple top-level sections independently', () => {
+    const theme = createTheme('acme-dark', {
+      shadow: { strength: '5' },
+      colors: { semantic: { background: '#000000' } },
+    });
+
+    expect(theme.shadow.strength).toBe('5');
+    expect(theme.shadow.color).toBe(defaultTheme.shadow.color);
+    expect(theme.colors.semantic.background).toBe('#000000');
+    expect(theme.colors.semantic.text).toBe(defaultTheme.colors.semantic.text);
+  });
+
+  it('lets an explicit override value win even when falsy (empty string)', () => {
+    const theme = createTheme('acme-dark', { colors: { semantic: { text: '' } } });
+    expect(theme.colors.semantic.text).toBe('');
+  });
+
+  it('ignores undefined override values and keeps the base value', () => {
+    const theme = createTheme('acme-dark', { colors: { semantic: { text: undefined } } });
+    expect(theme.colors.semantic.text).toBe(defaultTheme.colors.semantic.text);
+  });
+
+  it('accepts a custom base theme instead of defaultTheme', () => {
+    const customBase = { ...defaultTheme, shadow: { ...defaultTheme.shadow, strength: '10' } };
+    const theme = createTheme('acme-dark', {}, customBase);
+    expect(theme.shadow.strength).toBe('10');
+  });
+
+  it('does not mutate the base theme passed in', () => {
+    const snapshotBefore: unknown = JSON.parse(JSON.stringify(defaultTheme));
+    createTheme('acme-dark', { colors: { primary: { 500: '#ff0000' } } });
+    expect(defaultTheme).toEqual(snapshotBefore);
+  });
+});