@skdx/docs-kit 0.35.0

package/dist/themes/createBrandTheme.ts

@@ -0,0 +1,298 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import { contrastRatio } from '../utils/contrast';
+import type { ColorScale, Theme, ThemeColorMode, ThemeOverride } from '../utils/theme';
+import { createTheme, defaultTheme } from './DefaultTheme';
+
+/** Seed for {@link createBrandTheme}: brand hues and chroma, with the rest derived. */
+export interface BrandSeed {
+  /** Theme name (e.g. `'midnight-light'`); becomes `theme.name`. */
+  name: string;
+  /** Which mode's semantic roles to derive (ramps are mode-independent). */
+  mode: ThemeColorMode;
+  /** Primary hue in degrees, 0–360 (e.g. 272 for violet). */
+  primaryHue: number;
+  /** Primary ramp saturation, 0–100. Toward 0 for monochrome. @default 75 */
+  primaryChroma?: number;
+  /** Gray tint hue. @default primaryHue */
+  neutralHue?: number;
+  /** Gray tint amount, 0–100. @default 8 */
+  neutralChroma?: number;
+  /** Intent ramp hues. @default { success: 145, warning: 40, danger: 0 } */
+  intentHues?: { success?: number; warning?: number; danger?: number };
+  /** Intent ramp saturation, 0–100. @default 70 */
+  intentChroma?: number;
+  /** Hand-picked overrides merged last (typically shadow tint). */
+  override?: ThemeOverride;
+}
+
+const STEP_LIGHTNESS = {
+  50: 97,
+  100: 94,
+  200: 87,
+  300: 77,
+  400: 65,
+  500: 55,
+  600: 45,
+  700: 36,
+  800: 27,
+  900: 18,
+  950: 9,
+} as const satisfies Record<keyof ColorScale, number>;
+
+const STEP_CHROMA = {
+  50: 0.5,
+  100: 0.62,
+  200: 0.76,
+  300: 0.88,
+  400: 0.96,
+  500: 1,
+  600: 1,
+  700: 0.96,
+  800: 0.9,
+  900: 0.84,
+  950: 0.74,
+} as const satisfies Record<keyof ColorScale, number>;
+
+const STEPS = Object.keys(STEP_LIGHTNESS).map(Number) as Array<keyof ColorScale>;
+
+function hslToHex(hue: number, saturation: number, lightness: number): string {
+  const l = Math.min(100, Math.max(0, lightness)) / 100;
+  const s = Math.min(100, Math.max(0, saturation)) / 100;
+  const a = s * Math.min(l, 1 - l);
+  const channel = (n: number) => {
+    const k = (n + hue / 30) % 12;
+    const value = l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+    return Math.round(255 * Math.min(1, Math.max(0, value)))
+      .toString(16)
+      .padStart(2, '0');
+  };
+  return `#${channel(0)}${channel(8)}${channel(4)}`;
+}
+
+function hexToRgbTriplet(hex: string): string {
+  const num = Number.parseInt(hex.slice(1), 16);
+  return `${(num >> 16) & 255} ${(num >> 8) & 255} ${num & 255}`;
+}
+
+function ramp(hue: number, chroma: number): ColorScale {
+  const scale = {} as Record<keyof ColorScale, string>;
+  for (const step of STEPS) {
+    scale[step] = hslToHex(hue, chroma * STEP_CHROMA[step], STEP_LIGHTNESS[step]);
+  }
+  return scale;
+}
+
+function enforceContrast(
+  hue: number,
+  chroma: number,
+  lightness: number,
+  constraints: ReadonlyArray<readonly [against: string, min: number]>,
+  toward: 0 | 100,
+): string {
+  const step = toward === 0 ? -1 : 1;
+  let current = Math.round(lightness);
+  let hex = hslToHex(hue, chroma, current);
+  const unmet = () => constraints.some(([against, min]) => contrastRatio(hex, against) < min);
+  while (current !== toward && unmet()) {
+    current += step;
+    hex = hslToHex(hue, chroma, current);
+  }
+  return hex;
+}
+
+interface DerivedBrand {
+  isDark: boolean;
+  primaryHue: number;
+  primaryChroma: number;
+  neutralHue: number;
+  neutralChroma: number;
+  neutral: ColorScale;
+  background: string;
+  textInverted: string;
+  /** Lightness bound enforcement walks toward, per mode. */
+  toward: 0 | 100;
+}
+
+// primary-500/600 must clear WCAG 1.4.11 (3:1 vs background) and 4.5:1 (label text).
+function enforceActionSteps(primary: ColorScale, brand: DerivedBrand): void {
+  const { isDark, primaryHue, primaryChroma, background, textInverted, toward } = brand;
+  for (const [step, darkAnchor] of [
+    [500, 300],
+    [600, 400],
+  ] as const) {
+    primary[step] = enforceContrast(
+      primaryHue,
+      primaryChroma * STEP_CHROMA[step],
+      isDark ? STEP_LIGHTNESS[darkAnchor] : STEP_LIGHTNESS[step],
+      [
+        [textInverted, 4.5],
+        [background, 3],
+      ],
+      toward,
+    );
+  }
+}
+
+function intentScales(
+  hues: { success: number; warning: number; danger: number },
+  chroma: number,
+  brand: DerivedBrand,
+): Record<'success' | 'warning' | 'danger', ColorScale> {
+  const { isDark, toward } = brand;
+  // Status icon (aliases.ts step 600 light / 400 dark) is enforced to 3:1
+  // (WCAG 1.4.11) against its own ramp's wash, not the page.
+  const iconStep: keyof ColorScale = isDark ? 400 : 600;
+  const washStep: keyof ColorScale = isDark ? 950 : 50;
+  return Object.fromEntries(
+    (
+      [
+        ['success', hues.success],
+        ['warning', hues.warning],
+        ['danger', hues.danger],
+      ] as const
+    ).map(([intent, hue]) => {
+      const scale = ramp(hue, chroma);
+      scale[iconStep] = enforceContrast(
+        hue,
+        chroma * STEP_CHROMA[iconStep],
+        STEP_LIGHTNESS[iconStep],
+        [[scale[washStep], 3]],
+        toward,
+      );
+      return [intent, scale];
+    }),
+  ) as Record<'success' | 'warning' | 'danger', ColorScale>;
+}
+
+function semanticRoles(brand: DerivedBrand) {
+  const {
+    isDark,
+    neutral,
+    neutralHue,
+    neutralChroma,
+    primaryHue,
+    primaryChroma,
+    background,
+    textInverted,
+    toward,
+  } = brand;
+  const surface = isDark ? neutral[900] : neutral[50];
+  // Ink must clear the darkest (light) / lightest (dark) neutral fill it lands on:
+  // hover is neutral-100/800 and pressed neutral-200/900 (see aliases.ts).
+  const inkTargets: Array<[string, number]> = [
+    [surface, 4.5],
+    [isDark ? neutral[800] : neutral[200], 4.5],
+  ];
+  const textStep: keyof ColorScale = isDark ? 100 : 900;
+  const mutedStep: keyof ColorScale = isDark ? 400 : 500;
+  const accentStep: keyof ColorScale = isDark ? 400 : 500;
+  const borderStrongStep: keyof ColorScale = isDark ? 700 : 300;
+
+  return {
+    background,
+    surface,
+    surfaceHover: isDark ? neutral[800] : neutral[100],
+    overlay: `rgb(${hexToRgbTriplet(neutral[950])} / ${isDark ? '0.65' : '0.5'})`,
+    text: enforceContrast(
+      neutralHue,
+      neutralChroma * STEP_CHROMA[textStep],
+      STEP_LIGHTNESS[textStep],
+      inkTargets,
+      toward,
+    ),
+    textMuted: enforceContrast(
+      neutralHue,
+      neutralChroma * STEP_CHROMA[mutedStep],
+      STEP_LIGHTNESS[mutedStep],
+      inkTargets,
+      toward,
+    ),
+    textInverted,
+    // border is decorative and unenforced; borderStrong targets 3:1 (WCAG 1.4.11).
+    border: isDark ? neutral[800] : neutral[200],
+    borderStrong: enforceContrast(
+      neutralHue,
+      neutralChroma * STEP_CHROMA[borderStrongStep],
+      STEP_LIGHTNESS[borderStrongStep],
+      [[surface, 3]],
+      toward,
+    ),
+    focusRing: enforceContrast(
+      primaryHue,
+      primaryChroma * STEP_CHROMA[accentStep],
+      STEP_LIGHTNESS[accentStep],
+      [[background, 3]],
+      toward,
+    ),
+  };
+}
+
+/**
+ * Generates a {@link Theme} from a {@link BrandSeed}, deriving ramps and WCAG AA
+ * enforced semantic roles per mode.
+ *
+ * @example
+ * ```ts
+ * export const acmeLight = createBrandTheme({
+ *   name: 'acme-light',
+ *   mode: 'light',
+ *   primaryHue: 272,
+ *   primaryChroma: 85,
+ *   neutralHue: 265,
+ *   neutralChroma: 22,
+ * });
+ * ```
+ */
+export function createBrandTheme(seed: BrandSeed): Theme {
+  const {
+    name,
+    mode,
+    primaryHue,
+    primaryChroma = 75,
+    neutralHue = primaryHue,
+    neutralChroma = 8,
+    intentHues = {},
+    intentChroma = 70,
+    override = {},
+  } = seed;
+  const { success = 145, warning = 40, danger = 0 } = intentHues;
+
+  const primary = ramp(primaryHue, primaryChroma);
+  const neutral = ramp(neutralHue, neutralChroma);
+  const isDark = mode === 'dark';
+
+  const brand: DerivedBrand = {
+    isDark,
+    primaryHue,
+    primaryChroma,
+    neutralHue,
+    neutralChroma,
+    neutral,
+    background: isDark ? neutral[950] : '#ffffff',
+    textInverted: isDark ? neutral[950] : '#ffffff',
+    toward: isDark ? 100 : 0,
+  };
+
+  enforceActionSteps(primary, brand);
+
+  const theme = createTheme(
+    name,
+    {
+      mode,
+      colors: {
+        primary,
+        neutral,
+        ...intentScales({ success, warning, danger }, intentChroma, brand),
+        semantic: semanticRoles(brand),
+      },
+    },
+    defaultTheme,
+  );
+
+  return createTheme(name, override, theme);
+}

package/dist/themes/index.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+// Theme exports are named `<brand><Mode>`, except pairs whose upstream already
+// names the modes (`catppuccinLatte`/`catppuccinMocha`, `rosePineDawn`/`rosePine`).
+import type { Theme } from '../utils/theme';
+import { brands } from './brands';
+
+export { skandaLight } from './SkandaLight';
+export { emeraldLight } from './EmeraldLight';
+export { midnightDark } from './MidnightDark';
+export { graphiteLight } from './GraphiteLight';
+export { materialLight } from './MaterialLight';
+export { antLight } from './AntLight';
+export { fluentLight } from './FluentLight';
+export { chakraLight } from './ChakraLight';
+export { nordDark } from './NordDark';
+export { draculaDark } from './DraculaDark';
+export { catppuccinLatte } from './CatppuccinLatte';
+export { catppuccinMocha } from './CatppuccinMocha';
+export { solarizedLight } from './SolarizedLight';
+export { solarizedDark } from './SolarizedDark';
+export { gruvboxDark } from './GruvboxDark';
+export { rosePine } from './RosePine';
+export { everforestDark } from './EverforestDark';
+export { oneDark } from './OneDark';
+export { primerLight } from './PrimerLight';
+export { primerDark } from './PrimerDark';
+export { cupcakeLight } from './CupcakeLight';
+export { synthwaveDark } from './SynthwaveDark';
+export { skandaDark } from './SkandaDark';
+export { emeraldDark } from './EmeraldDark';
+export { midnightLight } from './MidnightLight';
+export { graphiteDark } from './GraphiteDark';
+export { materialDark } from './MaterialDark';
+export { antDark } from './AntDark';
+export { fluentDark } from './FluentDark';
+export { chakraDark } from './ChakraDark';
+export { nordLight } from './NordLight';
+export { draculaLight } from './DraculaLight';
+export { gruvboxLight } from './GruvboxLight';
+export { rosePineDawn } from './RosePineDawn';
+export { everforestLight } from './EverforestLight';
+export { oneLight } from './OneLight';
+export { cupcakeDark } from './CupcakeDark';
+export { synthwaveLight } from './SynthwaveLight';
+
+export { brands, defaultBrand, getBrand, getBrandByThemeName, type Brand } from './brands';
+
+/** Every bundled theme, brand by brand with light before dark — handy for building a theme picker. @public */
+export const themes: Theme[] = brands.flatMap((brand) => [brand.themes.light, brand.themes.dark]);

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@skdx/docs-kit",
+  "version": "0.35.0",
+  "description": "Build-time toolkit for the SKDX documentation site: the shared contracts, the framework table, generated manifests and the source files the docs measure. Not a public API — no semver guarantees, may change in any release.",
+  "license": "MIT",
+  "homepage": "https://github.com/SkandaDX/ui.skdx/tree/main/internal/docs-kit#readme",
+  "repository": {
+    "directory": "internal/docs-kit",
+    "type": "git",
+    "url": "git+https://github.com/SkandaDX/ui.skdx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SkandaDX/ui.skdx/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "exports": {
+    "./shared": {
+      "types": "./dist/shared/index.d.ts",
+      "default": "./dist/shared/index.js"
+    },
+    "./frameworks": "./dist/frameworks.mjs",
+    "./strip-paint": "./dist/strip-paint.mjs",
+    "./component-aliases.json": "./dist/component-aliases.json",
+    "./data/*": "./dist/data/*",
+    "./skins-src/*": "./dist/skins-src/*",
+    "./themes/*": "./dist/themes/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@skdx/angular": "0.35.0",
+    "@skdx/angular-blocks": "0.35.0",
+    "@skdx/react-blocks": "0.35.0",
+    "@skdx/shared": "0.35.0",
+    "@skdx/svelte": "0.35.0",
+    "@skdx/react": "0.35.0",
+    "@skdx/vue": "0.35.0",
+    "@skdx/skins": "0.35.0",
+    "@skdx/vue-blocks": "0.35.0",
+    "@skdx/tokens": "0.35.0",
+    "@skdx/web-components": "0.35.0",
+    "@skdx/svelte-blocks": "0.35.0",
+    "@skdx/web-components-blocks": "0.35.0"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": [
+          "^build",
+          {
+            "projects": [
+              "@skdx/web-components",
+              "@skdx/web-components-blocks"
+            ],
+            "target": "analyze"
+          }
+        ]
+      }
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/"
+  }
+}