@xex/tokens 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iGattreX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @xex/tokens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Design tokens for the XeX design system.
+
+```ts
+import { themes, getTheme, SHADE_STEPS, fontStack, DEFAULT_FONT } from '@xex/tokens'
+import '@xex/tokens/styles.css' // brand overrides, dark mode and shared classes
+```
+
+- `themes`: the colour presets (each has `shades` 50–900). Run `npm run audit:contrast` in the repo to check one.
+- `styles.css`: plain CSS (no Tailwind directives); import it once, after your own CSS.
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+declare const SHADE_STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+type ShadeStep = (typeof SHADE_STEPS)[number];
+interface Theme {
+    id: string;
+    name: string;
+    /** Tailwind-style 50–900 steps, hex strings. */
+    shades: Record<ShadeStep, string>;
+}
+/**
+ * Ordered around the colour wheel (blue → violet → pink/red → orange → yellow →
+ * green → teal), then a neutral. Hue of the 600 step is noted for each.
+ *
+ * Sunset, Gold, Lime, Forest and Teal are light hues, so their 500–900 steps are
+ * taken one Tailwind step darker; that keeps white text on bg-brand-600 at ≥ 4.5:1.
+ * `node scripts/audit-contrast.mjs` checks every pairing the system uses.
+ */
+declare const themes: Theme[];
+declare const DEFAULT_THEME_ID = "classic";
+declare function getTheme(id: string | null | undefined): Theme;
+
+type FontCategory = 'sans-serif' | 'serif' | 'display' | 'handwriting' | 'monospace';
+interface FontChoice {
+    /** Font family name (also the unique id), e.g. "DM Sans". */
+    family: string;
+    category: FontCategory;
+    /** Available static weights, used to build the Google Fonts URL. */
+    weights?: number[];
+    /** Custom CSS stack for non-web fonts (e.g. the system font). */
+    stack?: string;
+    /** The app already ships this font (self-hosted); never request it from Google Fonts. */
+    bundled?: boolean;
+}
+/** Inter is the design system's default typeface. Apps are expected to self-host it (e.g. @fontsource/inter). */
+declare const DEFAULT_FONT: FontChoice;
+declare const SYSTEM_FONT: FontChoice;
+declare const FONT_CATEGORIES: {
+    value: FontCategory;
+    label: string;
+}[];
+declare function fontStack(f: FontChoice): string;
+/** True for fonts that must not be fetched from Google Fonts (custom stacks and bundled fonts such as Inter). */
+declare const isLocalFont: (f: FontChoice) => boolean;
+/**
+ * Loads the regular weight of many families with ONE Google Fonts stylesheet request, so
+ * list rows can be drawn in their own typeface. Skips local fonts and families already requested.
+ * Only called by the optional font picker; nothing in the core talks to Google.
+ */
+declare function loadFontPreviews(list: FontChoice[]): void;
+/**
+ * Injects (once) the Google Fonts stylesheet for a family. No-op for local fonts, so an app that
+ * never lets users pick a Google font makes no external requests.
+ */
+declare function loadGoogleFont(f: FontChoice): void;
+
+export { DEFAULT_FONT, DEFAULT_THEME_ID, FONT_CATEGORIES, type FontCategory, type FontChoice, SHADE_STEPS, SYSTEM_FONT, type ShadeStep, type Theme, fontStack, getTheme, isLocalFont, loadFontPreviews, loadGoogleFont, themes };

package/dist/index.js

@@ -0,0 +1,266 @@
+// src/themes.ts
+var SHADE_STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+var themes = [
+  {
+    id: "classic",
+    // blue ~221°
+    name: "Classic",
+    shades: {
+      50: "#eff6ff",
+      100: "#dbeafe",
+      200: "#bfdbfe",
+      300: "#93c5fd",
+      400: "#60a5fa",
+      500: "#3b82f6",
+      600: "#2563eb",
+      700: "#1d4ed8",
+      800: "#1e40af",
+      900: "#1e3a8a"
+    }
+  },
+  {
+    id: "midnight",
+    // indigo ~243°
+    name: "Midnight",
+    shades: {
+      50: "#eef2ff",
+      100: "#e0e7ff",
+      200: "#c7d2fe",
+      300: "#a5b4fc",
+      400: "#818cf8",
+      500: "#6366f1",
+      600: "#4f46e5",
+      700: "#4338ca",
+      800: "#3730a3",
+      900: "#312e81"
+    }
+  },
+  {
+    id: "royal",
+    // violet ~262°
+    name: "Royal",
+    shades: {
+      50: "#f5f3ff",
+      100: "#ede9fe",
+      200: "#ddd6fe",
+      300: "#c4b5fd",
+      400: "#a78bfa",
+      500: "#8b5cf6",
+      600: "#7c3aed",
+      700: "#6d28d9",
+      800: "#5b21b6",
+      900: "#4c1d95"
+    }
+  },
+  {
+    id: "orchid",
+    // fuchsia ~293°
+    name: "Orchid",
+    shades: {
+      50: "#fdf4ff",
+      100: "#fae8ff",
+      200: "#f5d0fe",
+      300: "#f0abfc",
+      400: "#e879f9",
+      500: "#d946ef",
+      600: "#c026d3",
+      700: "#a21caf",
+      800: "#86198f",
+      900: "#701a75"
+    }
+  },
+  {
+    id: "crimson",
+    // rose ~347°
+    name: "Crimson",
+    shades: {
+      50: "#fff1f2",
+      100: "#ffe4e6",
+      200: "#fecdd3",
+      300: "#fda4af",
+      400: "#fb7185",
+      500: "#f43f5e",
+      600: "#e11d48",
+      700: "#be123c",
+      800: "#9f1239",
+      900: "#881337"
+    }
+  },
+  {
+    id: "sunset",
+    // orange ~21°
+    name: "Sunset",
+    shades: {
+      50: "#fff7ed",
+      100: "#ffedd5",
+      200: "#fed7aa",
+      300: "#fdba74",
+      400: "#fb923c",
+      500: "#ea580c",
+      600: "#c2410c",
+      700: "#9a3412",
+      800: "#7c2d12",
+      900: "#431407"
+    }
+  },
+  {
+    id: "gold",
+    // yellow ~40°
+    name: "Gold",
+    shades: {
+      50: "#fefce8",
+      100: "#fef9c3",
+      200: "#fef08a",
+      300: "#fde047",
+      400: "#facc15",
+      500: "#ca8a04",
+      600: "#a16207",
+      700: "#854d0e",
+      800: "#713f12",
+      900: "#422006"
+    }
+  },
+  {
+    id: "lime",
+    // lime ~85°
+    name: "Lime",
+    shades: {
+      50: "#f7fee7",
+      100: "#ecfccb",
+      200: "#d9f99d",
+      300: "#bef264",
+      400: "#a3e635",
+      500: "#65a30d",
+      600: "#4d7c0f",
+      700: "#3f6212",
+      800: "#365314",
+      900: "#1a2e05"
+    }
+  },
+  {
+    id: "forest",
+    // green ~142°
+    name: "Forest",
+    shades: {
+      50: "#f0fdf4",
+      100: "#dcfce7",
+      200: "#bbf7d0",
+      300: "#86efac",
+      400: "#4ade80",
+      500: "#16a34a",
+      600: "#15803d",
+      700: "#166534",
+      800: "#14532d",
+      900: "#052e16"
+    }
+  },
+  {
+    id: "teal",
+    // teal ~175°
+    name: "Teal",
+    shades: {
+      50: "#f0fdfa",
+      100: "#ccfbf1",
+      200: "#99f6e4",
+      300: "#5eead4",
+      400: "#2dd4bf",
+      500: "#0d9488",
+      600: "#0f766e",
+      700: "#115e59",
+      800: "#134e4a",
+      900: "#042f2e"
+    }
+  },
+  {
+    id: "graphite",
+    // neutral slate
+    name: "Graphite",
+    shades: {
+      50: "#f8fafc",
+      100: "#f1f5f9",
+      200: "#e2e8f0",
+      300: "#cbd5e1",
+      400: "#94a3b8",
+      500: "#64748b",
+      600: "#475569",
+      700: "#334155",
+      800: "#1e293b",
+      900: "#0f172a"
+    }
+  }
+];
+var DEFAULT_THEME_ID = "classic";
+function getTheme(id) {
+  return themes.find((t) => t.id === id) ?? themes.find((t) => t.id === DEFAULT_THEME_ID);
+}
+
+// src/fonts.ts
+var DEFAULT_FONT = { family: "Inter", category: "sans-serif", weights: [400, 500, 600, 700], bundled: true };
+var SYSTEM_FONT = {
+  family: "System UI",
+  category: "sans-serif",
+  stack: "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif"
+};
+var FONT_CATEGORIES = [
+  { value: "sans-serif", label: "Sans serif" },
+  { value: "serif", label: "Serif" },
+  { value: "display", label: "Display" },
+  { value: "handwriting", label: "Handwriting" },
+  { value: "monospace", label: "Monospace" }
+];
+var FALLBACK = {
+  "sans-serif": "ui-sans-serif, system-ui, sans-serif",
+  serif: "ui-serif, Georgia, serif",
+  display: "ui-sans-serif, system-ui, sans-serif",
+  handwriting: "cursive",
+  monospace: "ui-monospace, SFMono-Regular, Menlo, monospace"
+};
+function fontStack(f) {
+  return f.stack ?? `'${f.family}', ${FALLBACK[f.category] ?? FALLBACK["sans-serif"]}`;
+}
+var isLocalFont = (f) => Boolean(f.stack || f.bundled || f.family === DEFAULT_FONT.family);
+var WANTED_WEIGHTS = [400, 500, 600, 700];
+var requested = /* @__PURE__ */ new Set();
+var previewBatch = 0;
+function loadFontPreviews(list) {
+  if (typeof document === "undefined") return;
+  const fresh = list.filter((f) => !isLocalFont(f) && !requested.has(f.family));
+  if (fresh.length === 0) return;
+  const params = fresh.map((f) => {
+    const w = f.weights?.includes(400) ? 400 : f.weights?.[0] ?? 400;
+    requested.add(f.family);
+    return `family=${f.family.replace(/ /g, "+")}:wght@${w}`;
+  });
+  const link = document.createElement("link");
+  link.id = `gf-preview-${previewBatch++}`;
+  link.rel = "stylesheet";
+  link.href = `https://fonts.googleapis.com/css2?${params.join("&")}&display=swap`;
+  document.head.appendChild(link);
+}
+function loadGoogleFont(f) {
+  if (isLocalFont(f) || typeof document === "undefined") return;
+  const id = `gf-${f.family.replace(/\s+/g, "-")}`;
+  if (document.getElementById(id)) return;
+  const available = f.weights?.length ? f.weights : [400];
+  let weights = WANTED_WEIGHTS.filter((w) => available.includes(w));
+  if (weights.length === 0) weights = [available[0]];
+  const spec = `${f.family.replace(/ /g, "+")}:wght@${weights.join(";")}`;
+  const link = document.createElement("link");
+  link.id = id;
+  link.rel = "stylesheet";
+  link.href = `https://fonts.googleapis.com/css2?family=${spec}&display=swap`;
+  document.head.appendChild(link);
+}
+export {
+  DEFAULT_FONT,
+  DEFAULT_THEME_ID,
+  FONT_CATEGORIES,
+  SHADE_STEPS,
+  SYSTEM_FONT,
+  fontStack,
+  getTheme,
+  isLocalFont,
+  loadFontPreviews,
+  loadGoogleFont,
+  themes
+};

package/dist/styles.css

@@ -0,0 +1,622 @@
+/* Generated by scripts/gen-css.mjs — do not edit. Compiled to dist/styles.css at build time. */
+
+/* ------------------------------------------------------------------ *
+ * Brand overrides (runtime theming)
+ *
+ * Tailwind compiles bg-brand-600 etc. at build time; relying on the
+ * compiled output to repaint when --brand-* changes is not reliable
+ * across every build setup. These plain-CSS rules use !important to
+ * re-declare the brand utilities we use as direct var() lookups, so a
+ * theme switch repaints immediately wherever this file is loaded.
+ * Only add a utility here if you use it. (Opacity modifiers such as
+ * bg-brand-600/50 are not supported by var() colors.)
+ * ------------------------------------------------------------------ */
+
+:root {
+  /* Fallback = Classic, so the first paint is never unstyled. */
+  --brand-50: #eff6ff;
+  --brand-100: #dbeafe;
+  --brand-200: #bfdbfe;
+  --brand-300: #93c5fd;
+  --brand-400: #60a5fa;
+  --brand-500: #3b82f6;
+  --brand-600: #2563eb;
+  --brand-700: #1d4ed8;
+  --brand-800: #1e40af;
+  --brand-900: #1e3a8a;
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+
+.bg-brand-50 {
+  background-color: var(--brand-50) !important;
+}
+
+.bg-brand-100 {
+  background-color: var(--brand-100) !important;
+}
+
+.bg-brand-200 {
+  background-color: var(--brand-200) !important;
+}
+
+.bg-brand-300 {
+  background-color: var(--brand-300) !important;
+}
+
+.bg-brand-400 {
+  background-color: var(--brand-400) !important;
+}
+
+.bg-brand-500 {
+  background-color: var(--brand-500) !important;
+}
+
+.bg-brand-600 {
+  background-color: var(--brand-600) !important;
+}
+
+.bg-brand-700 {
+  background-color: var(--brand-700) !important;
+}
+
+.bg-brand-800 {
+  background-color: var(--brand-800) !important;
+}
+
+.bg-brand-900 {
+  background-color: var(--brand-900) !important;
+}
+
+.text-brand-500 {
+  color: var(--brand-500) !important;
+}
+
+.text-brand-600 {
+  color: var(--brand-600) !important;
+}
+
+.text-brand-700 {
+  color: var(--brand-700) !important;
+}
+
+.text-brand-800 {
+  color: var(--brand-800) !important;
+}
+
+.border-brand-200 {
+  border-color: var(--brand-200) !important;
+}
+
+.border-brand-300 {
+  border-color: var(--brand-300) !important;
+}
+
+.border-brand-400 {
+  border-color: var(--brand-400) !important;
+}
+
+.border-brand-500 {
+  border-color: var(--brand-500) !important;
+}
+
+.border-brand-600 {
+  border-color: var(--brand-600) !important;
+}
+
+.ring-brand-200 {
+  --tw-ring-color: var(--brand-200) !important;
+}
+
+.ring-brand-300 {
+  --tw-ring-color: var(--brand-300) !important;
+}
+
+.ring-brand-400 {
+  --tw-ring-color: var(--brand-400) !important;
+}
+
+.hover\:bg-brand-50:hover {
+  background-color: var(--brand-50) !important;
+}
+
+.hover\:bg-brand-100:hover {
+  background-color: var(--brand-100) !important;
+}
+
+.hover\:bg-brand-600:hover {
+  background-color: var(--brand-600) !important;
+}
+
+.hover\:bg-brand-700:hover {
+  background-color: var(--brand-700) !important;
+}
+
+.hover\:text-brand-600:hover {
+  color: var(--brand-600) !important;
+}
+
+.hover\:text-brand-700:hover {
+  color: var(--brand-700) !important;
+}
+
+.hover\:text-brand-800:hover {
+  color: var(--brand-800) !important;
+}
+
+.hover\:border-brand-300:hover {
+  border-color: var(--brand-300) !important;
+}
+
+.hover\:border-brand-400:hover {
+  border-color: var(--brand-400) !important;
+}
+
+.hover\:border-brand-500:hover {
+  border-color: var(--brand-500) !important;
+}
+
+.focus\:ring-brand-400:focus, .focus-visible\:ring-brand-400:focus-visible, .focus-within\:ring-brand-400:focus-within {
+  --tw-ring-color: var(--brand-400) !important;
+}
+
+.focus\:border-brand-400:focus {
+  border-color: var(--brand-400) !important;
+}
+
+.group:focus-visible .group-focus-visible\:ring-brand-400 {
+  --tw-ring-color: var(--brand-400) !important;
+}
+
+.from-brand-50 {
+  --tw-gradient-from: var(--brand-50) !important;
+  --tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to, rgb(255 255 255 / 0)) !important;
+}
+
+.from-brand-100 {
+  --tw-gradient-from: var(--brand-100) !important;
+  --tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to, rgb(255 255 255 / 0)) !important;
+}
+
+.from-brand-500 {
+  --tw-gradient-from: var(--brand-500) !important;
+  --tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to, rgb(255 255 255 / 0)) !important;
+}
+
+.from-brand-600 {
+  --tw-gradient-from: var(--brand-600) !important;
+  --tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to, rgb(255 255 255 / 0)) !important;
+}
+
+.to-brand-100 {
+  --tw-gradient-to: var(--brand-100) !important;
+}
+
+.to-brand-600 {
+  --tw-gradient-to: var(--brand-600) !important;
+}
+
+.to-brand-700 {
+  --tw-gradient-to: var(--brand-700) !important;
+}
+
+.to-brand-800 {
+  --tw-gradient-to: var(--brand-800) !important;
+}
+
+/* ------------------------------------------------------------------ *
+ * Global conventions
+ * ------------------------------------------------------------------ */
+
+body {
+  --tw-bg-opacity: 1;
+  background-color: rgb(249 250 251 / var(--tw-bg-opacity, 1));
+  font-family: var(--font-sans), Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif;
+  --tw-text-opacity: 1;
+  color: rgb(17 24 39 / var(--tw-text-opacity, 1));
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+html[data-mode='dark'] body {
+  background-color: #1a2138;
+  color: #f3f4f6;
+}
+
+input[type='checkbox'], input[type='radio'], input[type='range'] {
+  accent-color: var(--brand-600);
+}
+
+/* Default keyboard-focus ring, themed. :where() keeps specificity at zero, so any control that
+   defines its own ring (focus-visible:ring-*, focus:outline-none) simply overrides this. */
+
+:where(:focus-visible) {
+  outline: 2px solid var(--brand-500);
+  outline-offset: 2px;
+}
+
+:where(html[data-mode='dark'] :focus-visible) {
+  outline-color: var(--brand-300);
+}
+
+.card {
+  border-radius: 0.75rem;
+  border-width: 1px;
+  --tw-border-opacity: 1;
+  border-color: rgb(229 231 235 / var(--tw-border-opacity, 1));
+  --tw-bg-opacity: 1;
+  background-color: rgb(255 255 255 / var(--tw-bg-opacity, 1));
+  --tw-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --tw-shadow-colored: 0 1px 2px 0 var(--tw-shadow-color);
+  box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--tw-shadow);
+}
+
+html[data-mode='dark'] .card {
+  background-color: #141a2e;
+  border-color: #2a3352;
+}
+
+.nav-item-active {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  border-radius: 0.5rem;
+  padding-left: 0.75rem;
+  padding-right: 0.75rem;
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  --tw-text-opacity: 1;
+  color: rgb(255 255 255 / var(--tw-text-opacity, 1));
+  background-color: var(--brand-600);
+}
+
+.nav-item-inactive {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  border-radius: 0.5rem;
+  padding-left: 0.75rem;
+  padding-right: 0.75rem;
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  --tw-text-opacity: 1;
+  color: rgb(75 85 99 / var(--tw-text-opacity, 1));
+  transition-property: color, background-color, border-color, text-decoration-color, fill, stroke;
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+  transition-duration: 150ms;
+}
+
+ html[data-mode='dark'] .nav-item-inactive:hover {
+  background-color: #222a45;
+}
+
+ html[data-mode='dark'] .nav-item-inactive {
+  color: #cbd2e1;
+}
+
+.nav-item-inactive:hover {
+  --tw-bg-opacity: 1;
+  background-color: rgb(243 244 246 / var(--tw-bg-opacity, 1));
+  --tw-text-opacity: 1;
+  color: rgb(17 24 39 / var(--tw-text-opacity, 1));
+}
+
+.stat-indigo {
+  border-width: 1px;
+  background-color: var(--brand-50);
+  color: var(--brand-700);
+  border-color: var(--brand-200);
+}
+
+.stat-emerald {
+  border-width: 1px;
+  background-color: #ecfdf5;
+  color: #047857;
+  border-color: #a7f3d0;
+}
+
+.stat-amber {
+  border-width: 1px;
+  background-color: #fffbeb;
+  color: #b45309;
+  border-color: #fde68a;
+}
+
+.stat-rose {
+  border-width: 1px;
+  background-color: #fff1f2;
+  color: #be123c;
+  border-color: #fecdd3;
+}
+
+.stat-sky {
+  border-width: 1px;
+  background-color: #f0f9ff;
+  color: #0369a1;
+  border-color: #bae6fd;
+}
+
+.weight-pill {
+  display: inline-flex;
+  min-width: 1.5rem;
+  align-items: center;
+  justify-content: center;
+  border-radius: 0.375rem;
+  --tw-bg-opacity: 1;
+  background-color: rgb(243 244 246 / var(--tw-bg-opacity, 1));
+  padding-left: 0.375rem;
+  padding-right: 0.375rem;
+  padding-top: 0.125rem;
+  padding-bottom: 0.125rem;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  font-weight: 600;
+  --tw-numeric-spacing: tabular-nums;
+  font-variant-numeric: var(--tw-ordinal) var(--tw-slashed-zero) var(--tw-numeric-figure) var(--tw-numeric-spacing) var(--tw-numeric-fraction);
+  --tw-text-opacity: 1;
+  color: rgb(55 65 81 / var(--tw-text-opacity, 1));
+}
+
+html[data-mode='dark'] .weight-pill {
+  background-color: #222a45;
+  color: #cbd2e1;
+}
+
+/* LoadingDots */
+
+@keyframes xex-dot-fade {
+  0%, 80%, 100% {
+    opacity: 0.2;
+  }
+
+  40% {
+    opacity: 1;
+  }
+}
+
+.xex-dots {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  vertical-align: middle;
+}
+
+.xex-dots > i {
+  width: 6px;
+  height: 6px;
+  border-radius: 9999px;
+  background: currentColor;
+  opacity: 0.2;
+  animation: xex-dot-fade 0.7s ease-in-out infinite;
+}
+
+.xex-dots > i:nth-child(2) {
+  animation-delay: 0.12s;
+}
+
+.xex-dots > i:nth-child(3) {
+  animation-delay: 0.24s;
+}
+
+/* ProgressBar (indeterminate), ProgressRing track, LoadingOverlay scrim */
+
+@keyframes xex-indeterminate {
+  0% {
+    left: -40%;
+  }
+
+  100% {
+    left: 100%;
+  }
+}
+
+.xex-indeterminate {
+  animation: xex-indeterminate 1.2s ease-in-out infinite;
+}
+
+.xex-ring-track {
+  stroke: #e5e7eb;
+}
+
+.xex-overlay {
+  background-color: rgb(255 255 255 / 0.65);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .xex-dots > i {
+    animation: none;
+    opacity: 0.6;
+  }
+
+  .xex-indeterminate {
+    animation: none;
+    left: 0;
+    width: 100%;
+    opacity: 0.5;
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Dark mode (per theme): remap neutral surfaces + soften brand tints.
+ * Driven by <html data-mode="dark">, set by ThemeProvider.
+ * ------------------------------------------------------------------ */
+
+html[data-mode='dark'] body {
+  background-color: #0b1020;
+  color: #e5e7eb;
+}
+
+html[data-mode='dark'] .bg-white {
+  background-color: #141a2e !important;
+}
+
+html[data-mode='dark'] .xex-ring-track {
+  stroke: #2a3352;
+}
+
+html[data-mode='dark'] .xex-overlay {
+  background-color: rgb(20 26 46 / 0.65);
+}
+
+html[data-mode='dark'] .group:focus-visible .group-focus-visible\:ring-offset-white {
+  --tw-ring-offset-color: #141a2e;
+}
+
+html[data-mode='dark'] .bg-gray-50, html[data-mode='dark'] .hover\:bg-gray-50:hover {
+  background-color: #1a2138 !important;
+}
+
+html[data-mode='dark'] .bg-gray-100, html[data-mode='dark'] .hover\:bg-gray-100:hover, html[data-mode='dark'] .weight-pill {
+  background-color: #222a45 !important;
+}
+
+html[data-mode='dark'] .bg-gray-200 {
+  background-color: #323b5c !important;
+}
+
+html[data-mode='dark'] .border-gray-100 {
+  border-color: #1f2740 !important;
+}
+
+html[data-mode='dark'] .border-gray-200 {
+  border-color: #2a3352 !important;
+}
+
+html[data-mode='dark'] .border-gray-300 {
+  border-color: #3a4468 !important;
+}
+
+html[data-mode='dark'] .text-gray-900, html[data-mode='dark'] .text-gray-800 {
+  color: #f3f4f6 !important;
+}
+
+html[data-mode='dark'] .text-gray-700, html[data-mode='dark'] .text-gray-600, html[data-mode='dark'] .weight-pill {
+  color: #cbd2e1 !important;
+}
+
+html[data-mode='dark'] .text-gray-500, html[data-mode='dark'] .text-gray-400 {
+  color: #8d97b3 !important;
+}
+
+html[data-mode='dark'] .bg-brand-50, html[data-mode='dark'] .hover\:bg-brand-50:hover {
+  background-color: color-mix(in srgb, var(--brand-500) 16%, #0b1020) !important;
+}
+
+html[data-mode='dark'] .bg-brand-100 {
+  background-color: color-mix(in srgb, var(--brand-500) 26%, #0b1020) !important;
+}
+
+html[data-mode='dark'] .text-brand-600, html[data-mode='dark'] .text-brand-700, html[data-mode='dark'] .text-brand-800 {
+  color: var(--brand-300) !important;
+}
+
+html[data-mode='dark'] .border-brand-200 {
+  border-color: color-mix(in srgb, var(--brand-500) 40%, #0b1020) !important;
+}
+
+html[data-mode='dark'] .from-brand-50 {
+  --tw-gradient-from: color-mix(in srgb, var(--brand-500) 16%, #0b1020) !important;
+}
+
+html[data-mode='dark'] .from-brand-100 {
+  --tw-gradient-from: color-mix(in srgb, var(--brand-500) 26%, #0b1020) !important;
+}
+
+html[data-mode='dark'] .to-brand-100 {
+  --tw-gradient-to: color-mix(in srgb, var(--brand-500) 30%, #0b1020) !important;
+}
+
+html[data-mode='dark'] .ring-brand-200 {
+  --tw-ring-color: color-mix(in srgb, var(--brand-500) 40%, #0b1020) !important;
+}
+
+html[data-mode='dark'] .stat-indigo {
+  background-color: color-mix(in srgb, var(--brand-500) 16%, #0b1020);
+  color: var(--brand-300);
+  border-color: color-mix(in srgb, var(--brand-500) 40%, #0b1020);
+}
+
+html[data-mode='dark'] .bg-red-50 {
+  background-color: #3a1620 !important;
+}
+
+html[data-mode='dark'] .border-red-200 {
+  border-color: #7f1d1d !important;
+}
+
+html[data-mode='dark'] .text-red-600, html[data-mode='dark'] .text-red-700, html[data-mode='dark'] .text-red-800 {
+  color: #fca5a5 !important;
+}
+
+html[data-mode='dark'] .bg-emerald-100 {
+  background-color: #0c3a2c !important;
+}
+
+html[data-mode='dark'] .text-emerald-700 {
+  color: #6ee7b7 !important;
+}
+
+html[data-mode='dark'] .bg-amber-100 {
+  background-color: #4a3410 !important;
+}
+
+html[data-mode='dark'] .text-amber-700 {
+  color: #fcd34d !important;
+}
+
+html[data-mode='dark'] .bg-red-100 {
+  background-color: #4a1a22 !important;
+}
+
+html[data-mode='dark'] .bg-sky-100 {
+  background-color: #0c3350 !important;
+}
+
+html[data-mode='dark'] .text-sky-700 {
+  color: #7dd3fc !important;
+}
+
+html[data-mode='dark'] .bg-purple-100 {
+  background-color: #3a1f5a !important;
+}
+
+html[data-mode='dark'] .text-purple-700 {
+  color: #d8b4fe !important;
+}
+
+html[data-mode='dark'] .stat-emerald {
+  background-color: #0c2f25;
+  color: #6ee7b7;
+  border-color: #14532d;
+}
+
+html[data-mode='dark'] .stat-amber {
+  background-color: #3a2a0c;
+  color: #fcd34d;
+  border-color: #78350f;
+}
+
+html[data-mode='dark'] .stat-rose {
+  background-color: #3a1420;
+  color: #fda4af;
+  border-color: #881337;
+}
+
+html[data-mode='dark'] .stat-sky {
+  background-color: #0c2a40;
+  color: #7dd3fc;
+  border-color: #075985;
+}
+
+html[data-mode='dark'] input::-moz-placeholder, html[data-mode='dark'] textarea::-moz-placeholder {
+  color: #6b7592;
+}
+
+html[data-mode='dark'] input::placeholder, html[data-mode='dark'] textarea::placeholder {
+  color: #6b7592;
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@xex/tokens",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "XeX design tokens: colour themes, font helpers and the shared stylesheet.",
+  "license": "MIT",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "themes",
+    "tailwind"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iGattreX/xex.git",
+    "directory": "packages/tokens"
+  },
+  "homepage": "https://github.com/iGattreX/xex#readme",
+  "bugs": {
+    "url": "https://github.com/iGattreX/xex/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/gen-css.mjs && tailwindcss -c tailwind.styles.config.js -i src/styles.src.css -o dist/styles.css && tsup",
+    "audit:contrast": "node scripts/audit-contrast.mjs",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@xex/tailwind-preset": "^0.1.0",
+    "tailwindcss": "^3.4.17",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}