docs: add brand color customization examples with light/dark mode

- Document BrandColorValue type usage in README files
- Add examples with generic Tailwind CSS colors
- Include CSS variable reference in TOKEN_USAGE.md

Author: JakeLin

README.md

@@ -306,6 +306,50 @@ function MyApp() {
 - `defaultTheme` - Initial theme ('light' or 'dark'), default: 'light'
 - `storageKey` - LocalStorage key for persistence, default: 'ainativekit-theme'
 - `enableSystemTheme` - Detect system preference, default: true
+- `brandColors` - Custom brand color overrides (see Brand Color Customization below)
+
+### Brand Color Customization
+
+Override default brand colors to match your app's identity. Brand colors support both simple strings and light/dark mode variants:
+
+```tsx
+import { ThemeProvider } from '@ainativekit/ui';
+
+function App() {
+  return (
+    <ThemeProvider
+      defaultTheme="light"
+      brandColors={{
+        // Simple: Same color for both light and dark modes
+        primary: '#6366F1', // Indigo
+
+        // Light/dark variants: Different colors per mode
+        success: { light: '#059669', dark: '#34D399' },
+        warning: { light: '#D97706', dark: '#FBBF24' },
+        error: { light: '#DC2626', dark: '#F87171' },
+      }}
+    >
+      <MyApp />
+    </ThemeProvider>
+  );
+}
+```
+
+**Brand Color Options:**
+
+| Color     | Purpose                                    |
+| --------- | ------------------------------------------ |
+| `primary` | Main actions, links, primary buttons       |
+| `success` | Positive states, confirmations             |
+| `warning` | Caution messages, warnings                 |
+| `error`   | Error states, destructive actions          |
+
+**Color Value Formats:**
+
+- **String** (e.g., `'#6366F1'`): Same color for both light and dark modes
+- **Object** (e.g., `{ light: '#059669', dark: '#34D399' }`): Different colors per mode
+
+The library automatically validates color contrast ratios and warns about potential accessibility issues.
 
 ## 📘 TypeScript Support
 

packages/ui/README.md

@@ -306,6 +306,50 @@ function MyApp() {
 - `defaultTheme` - Initial theme ('light' or 'dark'), default: 'light'
 - `storageKey` - LocalStorage key for persistence, default: 'ainativekit-theme'
 - `enableSystemTheme` - Detect system preference, default: true
+- `brandColors` - Custom brand color overrides (see Brand Color Customization below)
+
+### Brand Color Customization
+
+Override default brand colors to match your app's identity. Brand colors support both simple strings and light/dark mode variants:
+
+```tsx
+import { ThemeProvider } from '@ainativekit/ui';
+
+function App() {
+  return (
+    <ThemeProvider
+      defaultTheme="light"
+      brandColors={{
+        // Simple: Same color for both light and dark modes
+        primary: '#6366F1', // Indigo
+
+        // Light/dark variants: Different colors per mode
+        success: { light: '#059669', dark: '#34D399' },
+        warning: { light: '#D97706', dark: '#FBBF24' },
+        error: { light: '#DC2626', dark: '#F87171' },
+      }}
+    >
+      <MyApp />
+    </ThemeProvider>
+  );
+}
+```
+
+**Brand Color Options:**
+
+| Color     | Purpose                                    |
+| --------- | ------------------------------------------ |
+| `primary` | Main actions, links, primary buttons       |
+| `success` | Positive states, confirmations             |
+| `warning` | Caution messages, warnings                 |
+| `error`   | Error states, destructive actions          |
+
+**Color Value Formats:**
+
+- **String** (e.g., `'#6366F1'`): Same color for both light and dark modes
+- **Object** (e.g., `{ light: '#059669', dark: '#34D399' }`): Different colors per mode
+
+The library automatically validates color contrast ratios and warns about potential accessibility issues.
 
 ## 📘 TypeScript Support
 

packages/ui/src/tokens/TOKEN_USAGE.md

@@ -156,6 +156,48 @@ import { colors, cssVar } from '@ainativekit/ui/tokens';
 'outline' | 'border-light' | 'border-default' | 'border-heavy';
 ```
 
+#### Customizing Brand Colors
+
+You can override default brand colors via ThemeProvider. Brand colors support both simple strings and light/dark mode variants:
+
+```tsx
+import { ThemeProvider } from '@ainativekit/ui';
+
+function App() {
+  return (
+    <ThemeProvider
+      brandColors={{
+        // Simple: Same color for both light and dark modes
+        primary: '#6366F1', // Indigo
+
+        // Light/dark variants: Different colors per mode
+        success: { light: '#059669', dark: '#34D399' },
+        warning: { light: '#D97706', dark: '#FBBF24' },
+        error: { light: '#DC2626', dark: '#F87171' },
+      }}
+    >
+      <MyApp />
+    </ThemeProvider>
+  );
+}
+```
+
+**Available Brand Color Keys:**
+
+| Key       | CSS Variable          | Purpose                            |
+| --------- | --------------------- | ---------------------------------- |
+| `primary` | `--ai-brand-primary`  | Main actions, links                |
+| `success` | `--ai-brand-success`  | Positive states                    |
+| `warning` | `--ai-brand-warning`  | Caution messages                   |
+| `error`   | `--ai-brand-error`    | Error states                       |
+
+**Color Value Formats:**
+
+- **String** (e.g., `'#6366F1'`): Same color for both light and dark modes
+- **Object** (e.g., `{ light: '#059669', dark: '#34D399' }`): Theme-aware colors
+
+Custom brand colors are automatically validated for contrast ratios and accessibility.
+
 ### Typography
 
 Apply complete typography styles with font size, line height, weight, and letter spacing.