@xuefx/ui-theme 1.0.0

package/ThemeProvider.jsx

@@ -0,0 +1,57 @@
+import React, { createContext, useContext, useMemo } from 'react';
+
+const ThemeContext = createContext(null);
+
+/**
+ * Access the current theme object provided by the nearest ThemeProvider.
+ * Returns `null` when no ThemeProvider is mounted (i.e. using default :root styles).
+ */
+export function useTheme() {
+  return useContext(ThemeContext);
+}
+
+/**
+ * Inject a custom theme into a component subtree.
+ *
+ * CSS custom properties are set as inline styles on a wrapper <div>,
+ * scoping them to the subtree. When no ThemeProvider is used, the global
+ * `:root` variables from `theme/styles.css` serve as the default.
+ *
+ * @example
+ * import { ThemeProvider, createTheme } from 'theme';
+ *
+ * const brandTheme = createTheme({
+ *   colors: { primary: '142 76% 36%', 'primary-foreground': '0 0% 100%' },
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <ThemeProvider theme={brandTheme}>
+ *       <Button>Brand Button</Button>
+ *     </ThemeProvider>
+ *   );
+ * }
+ */
+export function ThemeProvider({ theme, children }) {
+  const style = useMemo(() => {
+    const vars = {};
+    if (!theme) return vars;
+    if (theme.colors) {
+      for (const [key, value] of Object.entries(theme.colors)) {
+        vars[`--${key}`] = value;
+      }
+    }
+    if (theme.radius) {
+      vars['--radius'] = theme.radius;
+    }
+    return vars;
+  }, [theme]);
+
+  return (
+    <ThemeContext.Provider value={theme}>
+      <div style={style} data-theme>
+        {children}
+      </div>
+    </ThemeContext.Provider>
+  );
+}

package/create-theme.js

@@ -0,0 +1,30 @@
+import { colors, borderRadius, spacing, fontSize } from './tokens.js';
+
+const defaultTokens = { colors, borderRadius, spacing, fontSize, radius: '0.5rem' };
+
+/**
+ * Create a theme object by merging user overrides with the default design tokens.
+ *
+ * @param {Object} userConfig
+ * @param {Object} [userConfig.colors]    - Partial color token overrides (HSL strings)
+ * @param {Object} [userConfig.borderRadius]
+ * @param {Object} [userConfig.spacing]
+ * @param {Object} [userConfig.fontSize]
+ * @param {string} [userConfig.radius]    - Base border radius (e.g. '0.75rem')
+ * @returns {Object} A complete theme object
+ *
+ * @example
+ * const brandTheme = createTheme({
+ *   colors: { primary: '142 76% 36%', 'primary-foreground': '0 0% 100%' },
+ *   radius: '0.75rem',
+ * });
+ */
+export function createTheme(userConfig = {}) {
+  return {
+    colors: { ...defaultTokens.colors, ...userConfig.colors },
+    borderRadius: { ...defaultTokens.borderRadius, ...userConfig.borderRadius },
+    spacing: { ...defaultTokens.spacing, ...userConfig.spacing },
+    fontSize: { ...defaultTokens.fontSize, ...userConfig.fontSize },
+    radius: userConfig.radius || defaultTokens.radius,
+  };
+}

package/index.js

@@ -0,0 +1,4 @@
+export * from './tokens.js';
+export { default as tailwindPreset } from './tailwind-preset.js';
+export { createTheme } from './create-theme.js';
+export { ThemeProvider, useTheme } from './ThemeProvider.jsx';

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@xuefx/ui-theme",
+  "version": "1.0.0",
+  "description": "Design tokens, Tailwind preset, and theming tools for @xuefx/ui",
+  "type": "module",
+  "main": "./index.js",
+  "files": ["*.js", "*.jsx", "*.css"],
+  "exports": {
+    ".": "./index.js",
+    "./tokens": "./tokens.js",
+    "./tailwind-preset": "./tailwind-preset.js",
+    "./styles.css": "./styles.css",
+    "./create-theme": "./create-theme.js",
+    "./ThemeProvider": "./ThemeProvider.jsx"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "license": "ISC"
+}

package/styles.css

@@ -0,0 +1,55 @@
+/**
+ * CSS custom properties for the React UI design system.
+ *
+ * Color tokens are stored as HSL channels (hue saturation lightness),
+ * without the `hsl()` wrapper. The Tailwind preset wraps them:
+ *   e.g. `primary: 'hsl(var(--primary))'`
+ *
+ * This allows Tailwind's opacity modifiers to work:
+ *   `bg-primary/50` → background-color: hsl(var(--primary) / 0.5)
+ */
+
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 222.2 84% 4.9%;
+  --popover: 0 0% 100%;
+  --popover-foreground: 222.2 84% 4.9%;
+  --primary: 222.2 47.4% 11.2%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  --secondary-foreground: 222.2 47.4% 11.2%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --accent: 210 40% 96.1%;
+  --accent-foreground: 222.2 47.4% 11.2%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 214.3 31.8% 91.4%;
+  --input: 214.3 31.8% 91.4%;
+  --ring: 222.2 84% 4.9%;
+  --radius: 0.5rem;
+}
+
+.dark {
+  --background: 222.2 84% 4.9%;
+  --foreground: 210 40% 98%;
+  --card: 222.2 84% 4.9%;
+  --card-foreground: 210 40% 98%;
+  --popover: 222.2 84% 4.9%;
+  --popover-foreground: 210 40% 98%;
+  --primary: 210 40% 98%;
+  --primary-foreground: 222.2 47.4% 11.2%;
+  --secondary: 217.2 32.6% 17.5%;
+  --secondary-foreground: 210 40% 98%;
+  --muted: 217.2 32.6% 17.5%;
+  --muted-foreground: 215 20.2% 65.1%;
+  --accent: 217.2 32.6% 17.5%;
+  --accent-foreground: 210 40% 98%;
+  --destructive: 0 62.8% 30.6%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 217.2 32.6% 17.5%;
+  --input: 217.2 32.6% 17.5%;
+  --ring: 212.7 26.8% 83.9%;
+}

package/tailwind-preset.js

@@ -0,0 +1,55 @@
+/**
+ * Tailwind CSS preset that maps CSS custom properties from styles.css
+ * into Tailwind's theme namespace.
+ *
+ * Usage in tailwind.config.js:
+ *   import { tailwindPreset } from 'theme';
+ *   export default { presets: [tailwindPreset], ... }
+ */
+
+export default {
+  theme: {
+    extend: {
+      colors: {
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+        popover: {
+          DEFAULT: 'hsl(var(--popover))',
+          foreground: 'hsl(var(--popover-foreground))',
+        },
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--secondary))',
+          foreground: 'hsl(var(--secondary-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+    },
+  },
+};

package/tokens.js

@@ -0,0 +1,70 @@
+/**
+ * Design tokens for the React UI component library.
+ * These values are the source of truth; the Tailwind preset and CSS custom
+ * properties are derived from them.
+ *
+ * Color tokens use HSL channels as space-separated strings — the format
+ * Tailwind's `hsl(var(--name))` expects. No `hsl()` wrapper here.
+ */
+export const colors = {
+  background: '0 0% 100%',
+  foreground: '222.2 84% 4.9%',
+  card: '0 0% 100%',
+  'card-foreground': '222.2 84% 4.9%',
+  popover: '0 0% 100%',
+  'popover-foreground': '222.2 84% 4.9%',
+  primary: '222.2 47.4% 11.2%',
+  'primary-foreground': '210 40% 98%',
+  secondary: '210 40% 96.1%',
+  'secondary-foreground': '222.2 47.4% 11.2%',
+  muted: '210 40% 96.1%',
+  'muted-foreground': '215.4 16.3% 46.9%',
+  accent: '210 40% 96.1%',
+  'accent-foreground': '222.2 47.4% 11.2%',
+  destructive: '0 84.2% 60.2%',
+  'destructive-foreground': '210 40% 98%',
+  border: '214.3 31.8% 91.4%',
+  input: '214.3 31.8% 91.4%',
+  ring: '222.2 84% 4.9%',
+};
+
+export const borderRadius = {
+  lg: 'var(--radius)',
+  md: 'calc(var(--radius) - 2px)',
+  sm: 'calc(var(--radius) - 4px)',
+};
+
+export const spacing = {
+  0: '0px',
+  1: '0.25rem',
+  2: '0.5rem',
+  3: '0.75rem',
+  4: '1rem',
+  5: '1.25rem',
+  6: '1.5rem',
+  8: '2rem',
+  10: '2.5rem',
+  12: '3rem',
+  16: '4rem',
+  20: '5rem',
+  24: '6rem',
+  32: '8rem',
+  40: '10rem',
+  48: '12rem',
+  56: '14rem',
+  64: '16rem',
+  72: '18rem',
+  80: '20rem',
+  96: '24rem',
+};
+
+export const fontSize = {
+  xs: ['0.75rem', { lineHeight: '1rem' }],
+  sm: ['0.875rem', { lineHeight: '1.25rem' }],
+  base: ['1rem', { lineHeight: '1.5rem' }],
+  lg: ['1.125rem', { lineHeight: '1.75rem' }],
+  xl: ['1.25rem', { lineHeight: '1.75rem' }],
+  '2xl': ['1.5rem', { lineHeight: '2rem' }],
+  '3xl': ['1.875rem', { lineHeight: '2.25rem' }],
+  '4xl': ['2.25rem', { lineHeight: '2.5rem' }],
+};