@twinmatrix/ui-sdk 0.0.1

package/README.md

@@ -0,0 +1,49 @@
+# @twinmatrix/ui-sdk
+
+TwinMatrix UI SDK - Dashboard components, widgets, and UI primitives for React applications.
+
+## Installation
+
+This SDK is used as a git dependency in TwinMatrix applications. It will be cloned during the build process.
+
+## Usage
+
+```typescript
+import { 
+  DashboardShell, 
+  DashboardSidePanel, 
+  AlertsPanel,
+  useAppTheme,
+  setCustomTheme 
+} from '@twinmatrix/ui-sdk';
+
+function MyDashboard() {
+  const theme = useAppTheme();
+  
+  return (
+    <DashboardShell>
+      <DashboardSidePanel side="right" isOpen={true} title="Alerts">
+        <AlertsPanel items={alertItems} />
+      </DashboardSidePanel>
+    </DashboardShell>
+  );
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+```
+
+## Documentation
+
+See [THEME_CUSTOMIZATION.md](./THEME_CUSTOMIZATION.md) for theme customization guide.
+
+## License
+
+MIT

package/THEME_CUSTOMIZATION.md

@@ -0,0 +1,221 @@
+# Theme Customization Guide
+
+The Dashboard SDK provides a default theme with sensible colors, but you can customize it to match your brand.
+
+## Quick Start
+
+```typescript
+import { setCustomTheme, getTheme } from '@dashboard-sdk';
+
+// Customize theme colors for dark mode
+setCustomTheme('dark', {
+  accent: {
+    primary: '#FF5733',    // Your brand primary color
+    secondary: '#33FF57',  // Your brand secondary color
+  },
+  surface: {
+    topbar: '#FF5733',     // Match topbar to your brand
+  },
+  text: {
+    onAccent: '#FFFFFF',   // Text color on accent backgrounds
+  },
+});
+
+// Customize both light and dark modes at once
+setCustomTheme('light', {
+  accent: { primary: '#0066CC' },
+  surface: { topbar: '#0066CC' },
+});
+
+setCustomTheme('dark', {
+  accent: { primary: '#3399FF' },
+  surface: { topbar: '#3399FF' },
+});
+```
+
+## API Reference
+
+### `setCustomTheme(mode, override)`
+
+Set custom theme overrides for a specific mode.
+
+**Parameters:**
+- `mode: 'light' | 'dark'` - The theme mode to customize
+- `override: PartialTheme` - Partial theme object with your customizations
+
+**Example:**
+```typescript
+setCustomTheme('dark', {
+  accent: {
+    primary: '#FF5733',
+    secondary: '#33FF57',
+  },
+  surface: {
+    topbar: '#FF5733',
+    panel: '#1a1a1a',
+  },
+  chart: {
+    palette: ['#FF5733', '#33FF57', '#3357FF'],
+  },
+});
+```
+
+### `setCustomThemes(overrides)`
+
+Set custom theme overrides for both modes at once.
+
+**Parameters:**
+- `overrides: { light?: PartialTheme; dark?: PartialTheme }` - Theme overrides for each mode
+
+**Example:**
+```typescript
+setCustomThemes({
+  light: {
+    accent: { primary: '#0066CC' },
+  },
+  dark: {
+    accent: { primary: '#3399FF' },
+  },
+});
+```
+
+### `resetTheme(mode?)`
+
+Reset theme overrides to defaults.
+
+**Parameters:**
+- `mode?: 'light' | 'dark'` - Optional mode to reset. If omitted, resets both modes.
+
+**Example:**
+```typescript
+resetTheme('dark');  // Reset only dark mode
+resetTheme();         // Reset both modes
+```
+
+### `getTheme(mode)`
+
+Get the current theme (with custom overrides applied).
+
+**Parameters:**
+- `mode: 'light' | 'dark'` - The theme mode to retrieve
+
+**Returns:** `Theme` - The complete theme object
+
+**Example:**
+```typescript
+const darkTheme = getTheme('dark');
+console.log(darkTheme.accent.primary); // Your custom primary color
+```
+
+### `getBaseTheme(mode)`
+
+Get the base theme without any custom overrides.
+
+**Parameters:**
+- `mode: 'light' | 'dark'` - The theme mode to retrieve
+
+**Returns:** `Theme` - The base theme object
+
+## Theme Structure
+
+The `Theme` type includes the following properties:
+
+```typescript
+type Theme = {
+  surface: {
+    app: string;        // Main app background
+    topbar: string;     // Top bar background
+    panel: string;      // Side panel background
+    card: string;       // Card background
+    modal: string;      // Modal background
+    control: string;    // Control elements background
+    backdrop: string;   // Modal backdrop
+    neutral: string;    // Neutral background
+    hover: string;      // Hover state background
+  };
+  text: {
+    primary: string;    // Primary text color
+    muted: string;      // Muted/secondary text
+    inverted: string;   // Inverted text (for dark backgrounds)
+    onAccent: string;   // Text on accent backgrounds
+  };
+  accent: {
+    primary: string;    // Primary accent color
+    secondary: string;  // Secondary accent color
+  };
+  semantic: {
+    success: string;    // Success state color
+    warning: string;   // Warning state color
+    danger: string;    // Danger/error color
+    info: string;       // Info state color
+  };
+  border: {
+    subtle: string;     // Subtle border color
+    strong: string;     // Strong border color
+  };
+  chart: {
+    palette: string[]; // Chart color palette
+    grid: string;       // Chart grid color
+    text: string;       // Chart text color
+  };
+  state: {
+    hover: string;      // Hover state color
+    active: string;     // Active state color
+    focus: string;      // Focus state color
+  };
+};
+```
+
+## Best Practices
+
+1. **Set theme early**: Call `setCustomTheme` before rendering any SDK components, ideally in your app initialization code.
+
+2. **Use brand colors**: Map your brand's primary and secondary colors to `accent.primary` and `accent.secondary`.
+
+3. **Maintain contrast**: Ensure text colors have sufficient contrast against their backgrounds for accessibility.
+
+4. **Test both modes**: Customize both light and dark modes if your app supports theme switching.
+
+## Example: Complete Theme Setup
+
+```typescript
+// In your app initialization (e.g., App.tsx or main.tsx)
+import { setCustomThemes } from '@dashboard-sdk';
+
+// Your brand colors
+const BRAND_PRIMARY = '#FF5733';
+const BRAND_SECONDARY = '#33FF57';
+const BRAND_DARK = '#1a1a1a';
+
+// Setup themes
+setCustomThemes({
+  light: {
+    accent: {
+      primary: BRAND_PRIMARY,
+      secondary: BRAND_SECONDARY,
+    },
+    surface: {
+      topbar: BRAND_PRIMARY,
+    },
+    text: {
+      onAccent: '#FFFFFF',
+    },
+  },
+  dark: {
+    accent: {
+      primary: BRAND_PRIMARY,
+      secondary: BRAND_SECONDARY,
+    },
+    surface: {
+      topbar: BRAND_PRIMARY,
+      app: BRAND_DARK,
+      panel: '#222222',
+    },
+    text: {
+      onAccent: '#FFFFFF',
+    },
+  },
+});
+
+// Now render your dashboard components
+```