* 📱 fix: Fit the Tool Library and Skills Pickers to Small Screens The Tool Library dialog assumed a viewport wide enough for its 224px navigation rail: below `md` the rail took more than half of a 390px screen and the card grid was squeezed into the remainder. The rail is now `md`-only, and the same kind and view navigation renders as a horizontally scrollable chip row under the search field. Card and row actions were hover-only, so Configure, Favorite and Remove were unreachable on a touch screen. They stay hidden until hover only where hover exists (`@media (hover: hover)`), and are always visible otherwise. The Skills picker header put the create button, the filter field and the view radio on one row, where the field collapsed to 50px beside a `shrink-0` radio. The view radio and the create button now sit on the title row, the create button flush right, and the filter field owns the row below them. The dialogs fill the viewport below `md` and switch `vh` to `dvh`, so mobile browser chrome no longer cuts off the bottom of the panel. * ♿ fix: Gate Hidden Tool Actions on Touch, Not on Hover Hiding an action until hover has to ask whether a finger can reach it, and `(hover: hover)` does not answer that: on a 2-in-1 it is true because it describes the trackpad, while the touchscreen sits right next to it. Tool cards and tool rows gated their Configure, Favorite and Remove controls on that query, so a finger user of such a device saw no actions at all. `packages/client/tailwind.preset.cjs` already carries `touch` for this exact distinction, `(any-pointer: coarse)` rather than `(pointer: coarse)`. This adds its inverse, `no-touch`, and gates the hidden state on it, so the hide applies only where no coarse pointer exists at all and hover no longer takes part in the decision. * 📐 fix: Split the Skills Header Onto Two Rows Below md The Skills header put the create button, the filter field and the view radio on one row. The radio's segments are `whitespace-nowrap`, so the group never narrows below 261px, and the field — `flex-1`, basis 0 — absorbed the shortfall and measured 50px on a 390px screen. Below md the radio and the create button now take the first line, the create button flush right, and the field takes the second. From md the row is exactly what it was: create button, field, category, radio. One DOM order serves both through `order-*`, so the radio and the create button each exist once. * 🧷 fix: Let the Skills View Radio Wrap Instead of Clipping The three view segments carry `whitespace-nowrap` and `px-4`, so the group has a hard 261px minimum in English and more in longer locales. On a 360px phone that group and the 42px create button exceed the dialog, which is `overflow-hidden`, and the trailing option becomes unreachable. The group now uses the primitive's `wrap` variant and may shrink, so the segments flow onto a second row; at 390px they still occupy one. `wrap` reproduced `inset-y-1` by assuming the group had no vertical padding, so turning it on for a `p-1` group shrank the moving indicator by 8px and left it floating inside its segment. It now measures that padding from the first row's offset, which leaves an unpadded group's geometry unchanged. * 🧪 test: Cover the Small-Screen Tool Library and Skills Header Ten mock-harness scenarios for the behaviour this branch changes, one per acceptance scenario id, asserting rendered geometry and computed styles rather than class strings. The tool library file covers a phone viewport (the dialog fills it, the rail is gone, the chip row filters, and no card crosses the viewport edge — the 744px grid-column overflow), the action gate on all three pointer profiles (visible with a coarse pointer, hover-gated with a mouse, revealed by keyboard focus), the selected tool row, and the unchanged desktop rail. The skills file covers the two-row header below md, the wrapped view radio at 320 and 280 CSS px with every option inside the dialog and the indicator on its checked segment, and the single desktop row. * 🧪 test: Pin the Scenario Contexts and Settle Their Geometry The verifier runs every tagged test in three projects, one of which is a touch phone, so the mouse scenarios asserted a mouse on a device that reports a coarse pointer, and the desktop rail on a 412px screen. They now pin their own viewport and pointer instead of inheriting the project. Geometry and opacity were also read mid-animation: the dialog scales as it opens, which put its left edge at 1.5px rather than 0, and the actions fade over the shared motion duration, which caught keyboard focus at 0.84. Both now poll for the resting value. With nothing selected the skills section offers only the dashed empty-state card, whose accessible name carries the hint line, so the exact-name locator for Add skill never matched. * 📏 fix: Keep the Tool Library Shell and Its Body the Same Height Giving the shell an explicit `md:h-[88vh]` while the body kept its 840px ceiling let the two disagree: on a viewport taller than about 955px the difference became dead space below the catalog, 216px at 1280x1200, and below `md` the full-height sheet left 293px on a 744x1133 tablet. The body carries the height from `md` again, the way it did before this change, so the shell wraps it. Below `md` the shell stays the full-bleed sheet and the body is capped to the same `100dvh`, which it needs because its `h-full` resolves against a grid area sized to the whole catalog. Measured shell and body heights now agree exactly: 840 at 1280x1200, 757 at 1280x860, 1133 at 744x1133 and 844 at 390x844, with the catalog still scrolling inside its own container. * 🎯 fix: Keep the Search Field Clear of the Dialog Close Button `md:px-6` on the search row is a responsive variant, so it is emitted after the base utilities and reset the `pr-12` that reserves room for the close button: on desktop the row's right padding dropped from 48px to 24px and the field ran 16px underneath the button. It now sets only the left side at `md`. Measured gap between the field's right edge and the button: 8px at 1280x860 and at 390x844, with no vertical overlap. Asserted inside the phone-viewport and desktop-rail scenarios rather than as a new id, since it is the same surface. * ⌨️ fix: Read the Skills Header in Tab Order and Keep the Chip Row Draggable Two defects with the same shape: a control that the eye can reach and the keyboard or the mouse cannot. The Skills header used `order-*` to serve both layouts from one DOM order, which left tab order disagreeing with the visual order from `md`: focus went from the rightmost radio group back to the create button and then into the middle. The breakpoint now selects the DOM order instead, the way the marketplace dialog already selects its rail, so each layout reads in the order it renders. Every control is still built once, so there is one radio group and one create button at any width. The mobile chip row hid its scrollbar unconditionally. A narrow desktop window is below `md` as well, and there a wheel scrolls the page rather than the row, so Made by you and Favorites could not be reached with a mouse at all. The hiding is now gated on `touch`, the same `(any-pointer: coarse)` query the rest of this branch uses. Measured: desktop DOM order create, field, radio and mobile radio, create, field, each matching its layout; `scrollbar-width` resolves to `auto` in a 520px mouse window whose row overflows, and to `none` on a touch phone. * 👆 fix: Give the Touch Layout Touch Geometry Two findings with one cause: the coarse-pointer layout inherited the mouse layout's geometry after this branch changed what it shows and in what order. Card actions no longer fade out where a finger can reach them, but they are absolutely positioned over the card's content, so on touch they covered the last line of a three-line description for as long as the card was on screen - an overlap that used to be transient. The card now reserves a strip for them there, `touch:h-36` with `touch:pb-9` on the content, which keeps all three lines. The chip row is that layout's primary navigation and exists only where a finger is what reaches it, yet its chips were about 30px tall and its create control 32px, while the repository already exposes the 44px `theme-control-touch` size for this. Both now carry that floor through `touch:`, and the mouse layout keeps its compact sizing. Measured on a 390x844 touch profile: all eight chips 44px, the card 144px, and the description's box clear of the action cluster. Both are asserted in the phone-viewport and touch-action scenarios. |
||
|---|---|---|
| .. | ||
| atoms | ||
| context | ||
| themes | ||
| types | ||
| utils | ||
| highContrast.css | ||
| index.ts | ||
| README.md | ||
| registry.spec.ts | ||
| registry.ts | ||
| semanticTokens.spec.ts | ||
| tailwind.spec.js | ||
Dynamic Theme System for @librechat/client
Versioned theme definitions
New themes should use the versioned ThemeDefinition interface. Definitions are data-only, may
provide separate light and dark overrides, and resolve missing values against LibreChat's bundled
defaults before any CSS variables are applied.
const compactTheme: ThemeDefinition = {
version: 1,
name: 'compact',
modes: {
light: {
appearance: {
controlRadius: '0.25rem',
roundControlRadius: '9999px',
surfaceRadius: '0.5rem',
largeSurfaceRadius: '0.75rem',
controlHeight: '2rem',
},
},
},
};
<ThemeProvider themeDefinition={compactTheme}>{children}</ThemeProvider>;
The initial appearance registry intentionally covers only shared control shape, surface shape,
control height, compact/normal spacing, UI typography, surface elevation, and fast/normal motion.
themeRGB, REACT_APP_THEME_*, and the existing localStorage keys remain supported through legacy
adapters. Theme application removes only variables owned by the theme module when a theme is reset.
This theme system allows you to dynamically change colors in your React application using CSS variables and Tailwind CSS. It combines dark/light mode switching with dynamic color theming capabilities.
Table of Contents
- Overview
- How It Works
- Basic Usage
- Available Theme Colors
- Creating Custom Themes
- Environment Variable Themes
- Dark/Light Mode
- Migration Guide
- Implementation Details
- Troubleshooting
Overview
The theme system provides:
- Dark/Light Mode Switching - Automatic theme switching based on user preference
- Dynamic Color Theming - Change colors at runtime without recompiling CSS
- CSS Variable Based - Uses CSS custom properties for performance
- Tailwind Integration - Works seamlessly with Tailwind CSS utilities
- TypeScript Support - Full type safety for theme definitions
How It Works
The theme system operates in three layers:
- CSS Variables Layer: Default colors defined in your app's CSS
- ThemeProvider Layer: React context that manages theme state and applies CSS variables
- Tailwind Layer: Maps CSS variables to Tailwind utility classes
Default Behavior (No Custom Theme)
- CSS variables cascade from your app's
style.cssdefinitions - Light mode uses variables under
htmlselector - Dark mode uses variables under
.darkselector - No JavaScript intervention in color values
Custom Theme Behavior
- Prefer the versioned
themeDefinitionprop; the legacythemeRGBprop remains supported - Overrides CSS variables with bare
R G Bchannel triplets - Resolves missing
themeDefinitionvalues against the bundled light/dark defaults - Leaves colors omitted by legacy
themeRGBunset so consumer CSS continues to cascade
Basic Usage
1. Install the Component Library
npm install @librechat/client
2. Wrap Your App with ThemeProvider
import { ThemeProvider } from '@librechat/client';
function App() {
return (
<ThemeProvider initialTheme="system">
<YourApp />
</ThemeProvider>
);
}
3. Set Up Your Base CSS
Ensure your app has CSS variables defined as fallbacks. Every theme variable must
hold a bare R G B channel triplet, not a complete CSS color, because the
Tailwind color map wraps them as rgb(var(--x) / <alpha-value>) so that opacity
modifiers such as bg-surface-primary/50 work:
/* style.css */
:root {
--white: 255 255 255;
--gray-800: 33 33 33;
--gray-100: 236 236 236;
/* ... other color definitions */
}
html {
--text-primary: var(--gray-800);
--surface-primary: var(--white);
/* ... other theme variables */
}
.dark {
--text-primary: var(--gray-100);
--surface-primary: var(--gray-900);
/* ... other dark theme variables */
}
Any direct use of these variables in hand-written CSS must wrap the triplet
itself: color: rgb(var(--text-primary));.
Breaking change: earlier versions accepted complete colors (
--text-primary: #212121). Hex,rgb(...), and named colors now produce invalid declarations and must be converted to channel triplets.
4. Configure Tailwind
Update your tailwind.config.js:
const libreChatTailwindPreset = require('@librechat/client/tailwind-preset');
module.exports = {
presets: [libreChatTailwindPreset],
content: [
'./src/**/*.{js,jsx,ts,tsx}',
// Include component library files
'./node_modules/@librechat/client/dist/**/*.js',
],
darkMode: ['class'],
theme: {
extend: {
colors: {
// Wrap each channel triplet so opacity modifiers keep working
'text-primary': 'rgb(var(--text-primary) / <alpha-value>)',
'surface-primary': 'rgb(var(--surface-primary) / <alpha-value>)',
'brand-purple': 'rgb(var(--brand-purple) / <alpha-value>)',
// ... other colors
},
},
},
};
The published preset supplies the semantic appearance utilities used by theme-aware component
variants, including h-theme-control, rounded-theme-control, gap-theme-compact, and
duration-theme-fast. Keep the preset enabled even when defining additional project utilities.
5. Use Theme Colors in Components
function MyComponent() {
return (
<div className="border border-border-light bg-surface-primary text-text-primary">
<h1 className="text-text-secondary">Hello World</h1>
<button className="bg-surface-submit text-text-on-status hover:bg-surface-submit-hover">
Submit
</button>
</div>
);
}
Available Theme Colors
Text Colors
text-text-primary- Primary text colortext-text-secondary- Secondary text colortext-text-secondary-alt- Alternative secondary texttext-text-tertiary- Tertiary text colortext-text-warning- Warning text colortext-text-destructive- Destructive/error text colortext-text-on-status- Text color for strong status surfaces
Surface Colors
bg-surface-primary- Primary backgroundbg-surface-secondary- Secondary backgroundbg-surface-tertiary- Tertiary backgroundbg-surface-submit- Submit button backgroundbg-surface-destructive- Destructive action backgroundbg-surface-dialog- Dialog/modal backgroundbg-surface-overlay- Dialog/modal scrim, adapted per themebg-surface-chat- Chat interface background
Border Colors
border-border-light- Light borderborder-border-medium- Medium borderborder-border-heavy- Heavy borderborder-border-xheavy- Extra heavy borderborder-border-destructive- Destructive action border
Status Colors
Each status family has a foreground, a -subtle background, a -border, and a
-strong surface for high-contrast notifications:
text-status-success/bg-status-success-subtle/border-status-success-bordertext-status-info/bg-status-info-subtle/border-status-info-bordertext-status-warning/bg-status-warning-subtle/border-status-warning-bordertext-status-error/bg-status-error-subtle/border-status-error-bordertext-status-neutral/bg-status-neutral-subtle/border-status-neutral-borderbg-status-success-strong/bg-status-info-strong/bg-status-warning-strong/bg-status-error-strongtext-status-verified— fill of the verified markVerifiedIconpaints, carrying astroke-text-on-statuscheck. Seergb-status-verifiedintypes/index.tsfor why it is its own role and what a pre-token theme gets.
Other Colors
bg-brand-purple- Brand purple colorbg-presentation- Presentation backgroundring-ring-primary- Focus ring color
Creating Custom Themes
1. Define Your Theme
import { IThemeRGB } from '@librechat/client';
export const customTheme: IThemeRGB = {
'rgb-text-primary': '0 0 0', // Black
'rgb-text-secondary': '100 100 100', // Gray
'rgb-surface-primary': '255 255 255', // White
'rgb-surface-submit': '0 128 0', // Green
'rgb-brand-purple': '138 43 226', // Blue Violet
// ... define other colors
};
2. Use Your Custom Theme
import { ThemeProvider } from '@librechat/client';
import { customTheme } from './themes/custom';
function App() {
return (
<ThemeProvider themeRGB={customTheme} themeName="custom">
<YourApp />
</ThemeProvider>
);
}
Environment Variable Themes
Load theme colors from environment variables:
1. Create Environment Variables
# .env.local
REACT_APP_THEME_BRAND_PURPLE=171 104 255
REACT_APP_THEME_TEXT_PRIMARY=33 33 33
REACT_APP_THEME_TEXT_SECONDARY=66 66 66
REACT_APP_THEME_SURFACE_PRIMARY=255 255 255
REACT_APP_THEME_SURFACE_SUBMIT=4 120 87
REACT_APP_THEME_LINK=37 99 235
REACT_APP_THEME_ACCENT_PRIMARY=18 110 107
REACT_APP_THEME_STATUS_ERROR=185 28 28
REACT_APP_THEME_STATUS_ERROR_SUBTLE=254 226 226
REACT_APP_THEME_STATUS_ERROR_BORDER=252 165 165
Every IThemeRGB key is configurable this way: drop the rgb- prefix and
upper-snake-case the rest, so rgb-status-error-border becomes
REACT_APP_THEME_STATUS_ERROR_BORDER.
The prefix must be listed in the bundler's envPrefix (Vite) or equivalent, and
values are inlined at build time, so the client has to be rebuilt after changing
them.
2. Create a Theme Loader
function getThemeFromEnv(env = import.meta.env): IThemeRGB | undefined {
const theme = {
'rgb-text-primary': env.REACT_APP_THEME_TEXT_PRIMARY,
'rgb-brand-purple': env.REACT_APP_THEME_BRAND_PURPLE,
// ... other colors
};
const set = Object.fromEntries(Object.entries(theme).filter(([, value]) => value));
return Object.keys(set).length > 0 ? set : undefined; // Fall back to default themes
}
3. Apply Environment Theme
<ThemeProvider initialTheme="system" themeRGB={getThemeFromEnv()}>
<App />
</ThemeProvider>
Dark/Light Mode
The ThemeProvider handles dark/light mode automatically:
Using the Theme Hook
import { useTheme } from '@librechat/client';
function ThemeToggle() {
const { theme, setTheme } = useTheme();
return (
<button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
Current theme: {theme}
</button>
);
}
Theme Options
'light'- Force light mode'dark'- Force dark mode'system'- Follow system preference, for both colour scheme and contrast'high-contrast-light'- Accessibility mode: black on white, WCAG AAA'high-contrast-dark'- Accessibility mode: white on black, WCAG AAA
High contrast applies the built-in highContrastTheme definition
(themes/highContrast.ts), which outranks a deployment's custom theme, and adds
a high-contrast class to <html> for the CSS-only variables the token layer
cannot reach.
Three predicates, and they answer different questions:
isDark(theme)- which colour scheme to render.high-contrast-darkis dark.isHighContrast(theme)- did the user pick a contrast mode. This is what the theme toggle preserves when it flips the scheme, sosystemis never included.resolvesToHighContrast(theme)- will the contrast palette actually apply. True for the two explicit modes, and forsystemwhen the OS asks for more contrast through any ofprefers-contrast: more,prefers-contrast: customorforced-colors: active.
Because system resolves contrast from the OS, a user who has switched on
"Increase contrast" (macOS) or "Contrast themes" (Windows) gets the accessible
palette without first finding this setting. Windows is why the list has three
queries: a Contrast Theme surfaces as forced-colors: active with
prefers-contrast: custom, never more.
Migration Guide
If you're migrating from an older theme system:
1. Update Imports
Before:
import { ThemeContext, ThemeProvider } from '~/hooks/ThemeContext';
After:
import { ThemeContext, ThemeProvider } from '@librechat/client';
2. Update ThemeProvider Usage
The new ThemeProvider is backward compatible but adds new capabilities:
<ThemeProvider
initialTheme="system" // Same as before
themeRGB={customTheme} // New: optional custom colors
>
<App />
</ThemeProvider>
3. Existing Components
Components using ThemeContext continue to work without changes:
// This still works!
const { theme, setTheme } = useContext(ThemeContext);
Implementation Details
File Structure
packages/client/src/theme/
├── context/
│ └── ThemeProvider.tsx # Main theme provider
├── types/
│ └── index.ts # TypeScript interfaces
├── themes/
│ ├── default.ts # Light theme colors
│ ├── dark.ts # Dark theme colors
│ └── index.ts # Theme exports
├── utils/
│ ├── applyTheme.ts # Apply CSS variables
│ ├── tailwindConfig.ts # Tailwind helpers
│ └── createTailwindColors.js
├── README.md # This documentation
└── index.ts # Main exports
CSS Variable Format
The theme system uses RGB values in CSS variables:
- CSS Variable:
--text-primary: 33 33 33 - Theme Definition:
'rgb-text-primary': '33 33 33' - Tailwind Usage:
text-text-primary
RGB Format Requirements
All color values must be in space-separated RGB format:
- ✅ Correct:
'255 255 255' - ❌ Incorrect:
'#ffffff'or'rgb(255, 255, 255)'
This format allows Tailwind to apply opacity modifiers like bg-surface-primary/50.
Troubleshooting
Common Issues
1. Colors Not Applying
- Issue: Custom theme colors aren't showing
- Solution: Pass a valid
themeDefinition, or use the legacythemeRGBprop for color-only overrides - Check: CSS variables in DevTools should show a bare
R G Btriplet
2. Circular Reference Errors
- Issue:
--brand-purple: var(--brand-purple)creates infinite loop - Solution: Use direct channel values:
--brand-purple: 171 104 255
3. Dark Mode Not Working
- Issue: Dark mode doesn't switch
- Solution: Ensure
darkMode: ['class']is in your Tailwind config - Check: The
<html>element should haveclass="dark"in dark mode
4. TypeScript Errors
- Issue: Type errors when defining themes
- Solution: Import and use the
IThemeRGBinterface:
import { IThemeRGB } from '@librechat/client';
Debugging Tips
- Check CSS Variables: Use browser DevTools to inspect computed CSS variables
- Verify Theme Application: Look for inline styles on the root element
- Console Errors: Check for validation errors in the console
- Test Isolation: Try a minimal theme to isolate issues
Examples
Dynamic Theme Switching
import { ThemeProvider, defaultTheme, darkTheme } from '@librechat/client';
import { useState } from 'react';
function App() {
const [isDark, setIsDark] = useState(false);
return (
<ThemeProvider
initialTheme={isDark ? 'dark' : 'light'}
themeRGB={isDark ? darkTheme : defaultTheme}
themeName={isDark ? 'dark' : 'default'}
>
<button onClick={() => setIsDark(!isDark)}>Toggle Theme</button>
<YourApp />
</ThemeProvider>
);
}
Multi-Theme Selector
const themes = {
default: undefined, // Use CSS defaults
ocean: {
'rgb-brand-purple': '0 119 190',
'rgb-surface-primary': '240 248 255',
// ... ocean theme colors
},
forest: {
'rgb-brand-purple': '34 139 34',
'rgb-surface-primary': '245 255 250',
// ... forest theme colors
},
};
function App() {
const [selectedTheme, setSelectedTheme] = useState('default');
return (
<ThemeProvider themeRGB={themes[selectedTheme]} themeName={selectedTheme}>
<select onChange={(e) => setSelectedTheme(e.target.value)}>
{Object.keys(themes).map((name) => (
<option key={name} value={name}>
{name}
</option>
))}
</select>
<YourApp />
</ThemeProvider>
);
}
Using with the Main Application
When using the ThemeProvider in your main application with localStorage persistence:
import { ThemeProvider } from '@librechat/client';
import { getThemeFromEnv } from './utils';
function App() {
const envTheme = getThemeFromEnv();
return (
<ThemeProvider
// Only pass props if you want to override stored values
// If you always pass props, they will override localStorage
initialTheme={envTheme ? 'system' : undefined}
themeRGB={envTheme || undefined}
>
{/* Your app content */}
</ThemeProvider>
);
}
Important: The themeDefinition, themeRGB, and themeName props override stored values and
remain synchronized when they change. Only pass theme props when the parent should control those
values; otherwise use the context setters and allow stored preferences to remain authoritative.
Set persistThemeDefinition={false} when a parent controls a deployment or embedded theme that
must not replace the user's stored theme definition, legacy colors, name, or source. Appearance
mode changes remain independently persisted through color-theme; leave initialTheme undefined
when the stored light, dark, or system preference should remain authoritative.
Contributing
When adding new theme colors:
- Add the type definition in
types/index.ts - Add the color to default and dark themes
- Update the applyTheme mapping
- Add to Tailwind configuration
- Document in this README
License
This theme system is part of the @librechat/client package.