Skip to content

Commit 9fdcbff

Browse files
authored
🎨 docs: Document the Remaining Theme Appearance Keys (#813)
* docs: Document the Remaining Theme Appearance Keys * docs: Drop the Canary Availability Notes From the Theme Docs * docs: Mark the Theme Page as Pending Instead of Canary
1 parent 946d854 commit 9fdcbff

1 file changed

Lines changed: 42 additions & 7 deletions

File tree

  • content/docs/configuration/librechat_yaml/object_structure

‎content/docs/configuration/librechat_yaml/object_structure/theme.mdx‎

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,11 @@ A name that is not one of these is ignored: the server logs it and drops `interf
5454

5555
`interface.theme: clickhouse` changes both color and shape:
5656

57-
- **Palette.** Every color token is defined in both modes from Click UI's light and dark tokens, so nothing falls back to the LibreChat palette. A few values are moved along their Click UI ramps where the verbatim value missed WCAG AA contrast.
57+
- **Palette.** Every color token is defined in both modes from Click UI's light and dark tokens, so nothing falls back to the LibreChat palette. Values are Click UI's own, even where a pairing falls below WCAG AA contrast. Users who need more contrast can pick a high-contrast mode, which always uses the built-in accessible palette (see [How the theme is chosen](#how-the-theme-is-chosen)).
5858
- **Accent.** Near-black `#151515` in light mode and the ClickHouse yellow `#faff69` in dark mode, used for the accent and submit button. The focus ring is Click UI's outline color: blue `#437eef` in light mode, `#faff69` in dark.
5959
- **Buttons.** The primary button is `#302e32` in light mode and `#faff69` in dark, with Click UI's hover steps.
60-
- **Radii.** A tighter scale taken from Click UI's `border.radii`: controls, menus, tooltips, tabs and `sm` through `lg` at `0.25rem`, surfaces and `xl`/`2xl` at `0.5rem`, large surfaces and `3xl` at `0.75rem`.
60+
- **Radii.** A tighter scale taken from Click UI's `border.radii`: controls, menus, popovers, tooltips, tabs, the composer's action buttons and `sm` through `lg` at `0.25rem`, surfaces and `xl`/`2xl` at `0.5rem`, large surfaces and `3xl` at `0.75rem`.
61+
- **Borders.** Decorative outlines on controls and chips and the hairlines inside stroked surfaces are hidden (`chromeBorderAlpha` and `insetBorderAlpha` at `0`), so surfaces are separated by fill; field edges and the neutral button's border stay. Destructive actions use the `soft` style.
6162
- **Shadows.** Click UI's single elevation shadow on every raised surface, menus and dragged items, at 0.15 opacity in light mode and 0.6 in dark, with a hairline shadow for the `2xs` through `sm` steps. Tooltips have no shadow.
6263
- **Controls.** Buttons and fields are 2rem tall, controls are padded `1rem` with a `0.5rem` icon gap and a regular (`400`) label weight. Fields are filled (`fieldFillStyle: fill`) and swap their edge color on focus (`fieldFocusStyle: border`); labels are `0.75rem` at weight `500`. Disabled controls use the `fill` style with their own disabled colors, the switch is a compact 2rem by 1rem, and table rows get a 1px rule.
6364
- **Dialogs.** A 1px edge, `2rem` side padding, and titles at `1.25rem`, weight `700`, in the Inter stack. Every dialog scrim is at 0.75 opacity.
@@ -172,7 +173,7 @@ A few tokens follow a related token you did set when you leave them out, so a pa
172173

173174
### Appearance
174175

175-
Appearance values are set **per mode**, and a mode without them uses the defaults below. The defaults are the same in both modes except `menuShadow` and `tooltipShadow`, which are heavier in dark mode. To change shape in both modes, repeat the values under `light` and `dark`, as in the example above.
176+
Appearance values are set **per mode**, and a mode without them uses the defaults below. The defaults are the same in both modes except `menuShadow` and `tooltipShadow`, which are heavier in dark mode, and `buttonNeutralBorderOpacity`, which is opaque in dark mode. To change shape in both modes, repeat the values under `light` and `dark`, as in the example above.
176177

177178
| Key | Controls | Default |
178179
| --- | --- | --- |
@@ -181,8 +182,17 @@ Appearance values are set **per mode**, and a mode without them uses the default
181182
| `surfaceRadius` | Radius of surfaces such as cards and menus | `1rem` |
182183
| `largeSurfaceRadius` | Radius of large surfaces such as dialogs | `1.5rem` |
183184
| `menuRadius` | Corner radius of menu panels | `0.7rem` |
185+
| `menuPanelRadius` | Corner radius of the model selector menu, hover cards and the composer's menus; follows `radiusXl` when unset | `0.75rem` |
186+
| `popoverRadius` | Corner radius of the composer's popovers, such as the prompts, skills and mention lists; follows `radius2xl` when unset | `1rem` |
187+
| `composerActionRadius` | Corner radius of the composer's send and stop buttons and its other round action buttons; follows `roundControlRadius` when unset | `9999px` |
184188
| `tooltipRadius` | Corner radius of tooltips | `0.275rem` |
189+
| `tooltipPaddingX` | Inline padding of tooltips | `0.5rem` |
190+
| `tooltipPaddingY` | Vertical padding of tooltips | `0.25rem` |
191+
| `tooltipTextSize` | Font size of tooltip text | `1rem` |
185192
| `tabRadius` | Corner radius of tab triggers | `0.185rem` |
193+
| `tabMinWidth` | Minimum width of a tab trigger | `100px` |
194+
| `listMinWidth` | Minimum width of a Select list; `0` sizes it by its trigger | `8rem` |
195+
| `listMaxHeight` | Height after which a Select list scrolls | `24rem` |
186196
| `radiusSm` | The `rounded-sm` step used across the app | `calc(0.5rem - 4px)` |
187197
| `radiusMd` | The `rounded-md` step | `calc(0.5rem - 2px)` |
188198
| `radiusLg` | The `rounded-lg` step | `0.5rem` |
@@ -191,11 +201,20 @@ Appearance values are set **per mode**, and a mode without them uses the default
191201
| `radius3xl` | The `rounded-3xl` step | `1.5rem` |
192202
| `controlHeight` | Height of standard controls | `2.25rem` |
193203
| `controlPaddingX` | Inline padding of theme-sized controls; follows `spaceNormal` when unset | `0.75rem` |
204+
| `buttonPaddingX` | Inline padding of the default Button size | `1rem` |
194205
| `controlGap` | Gap between a control's icon and label; follows `spaceCompact` when unset | `0.375rem` |
206+
| `iconSize` | Size of standard icons (`size-theme-icon`) | `1rem` |
207+
| `iconSizeMd` | Size of medium icons (`size-theme-icon-md`) | `1.25rem` |
208+
| `iconSizeLg` | Size of large icons, such as a dialog's close button (`size-theme-icon-lg`) | `1.5rem` |
195209
| `controlFontWeight` | Label weight of theme-sized controls | `500` |
196210
| `buttonHeight` | Height of the default Button | `2.5rem` |
197211
| `buttonHeightSm` | Height of the `sm` Button | `2.25rem` |
212+
| `buttonHeightXs` | Height of the `xs` Button | `1.75rem` |
213+
| `buttonHeightLg` | Height of the `lg` Button | `2.75rem` |
214+
| `buttonHeightCompact` | Height of compact Buttons | `2rem` |
215+
| `iconButtonSizeSm` | Width and height of the `icon-sm` Button | `2rem` |
198216
| `fieldHeight` | Height of form fields | `2.5rem` |
217+
| `fieldHeightLg` | Height of large form fields, such as title inputs | `3rem` |
199218
| `fieldPaddingY` | Vertical padding of form fields | `0.5rem` |
200219
| `fieldFocusStyle` | How a focused field shows focus: `ring` draws the focus ring, `border` swaps the field's edge to `rgb-border-field-focus` | `ring` |
201220
| `fieldFillStyle` | Whether fields stay `transparent` or paint `rgb-field-fill` (`fill`) | `transparent` |
@@ -206,6 +225,7 @@ Appearance values are set **per mode**, and a mode without them uses the default
206225
| `focusRingOffset` | Distance of the focus outline from the element's edge | `2px` |
207226
| `switchWidth` | Width of the switch | `2.75rem` |
208227
| `switchHeight` | Height of the switch; the knob is this minus the track's 4px border | `1.5rem` |
228+
| `checkboxSize` | Size of the checkbox and its check mark | `1rem` |
209229
| `tableCellSpaceY` | Vertical padding of table cells | `1rem` |
210230
| `tableRowStroke` | Thickness of the rule between table rows | `0px` |
211231
| `spaceCompact` | Compact spacing step | `0.375rem` |
@@ -220,12 +240,19 @@ Appearance values are set **per mode**, and a mode without them uses the default
220240
| `textLg` | The `text-lg` size | `1.125rem` |
221241
| `textXl` | The `text-xl` size | `1.25rem` |
222242
| `text2xl` | The `text-2xl` size | `1.5rem` |
243+
| `text3xl` | The `text-3xl` size | `1.875rem` |
244+
| `text3xs` | The `text-3xs` size (10px by default) | `0.625rem` |
245+
| `text2xs` | The `text-2xs` size (11px by default) | `0.6875rem` |
246+
| `text1xs` | The `text-1xs` size (13px by default) | `0.8125rem` |
247+
| `text1sm` | The `text-1sm` size (15px by default) | `0.9375rem` |
223248
| `leadingXs` | Line height paired with `text-xs` | `calc(1 / 0.75)` |
224249
| `leadingSm` | Line height paired with `text-sm` | `calc(1.25 / 0.875)` |
225250
| `leadingBase` | Line height paired with `text-base` | `calc(1.5 / 1)` |
226251
| `leadingLg` | Line height paired with `text-lg` | `calc(1.75 / 1.125)` |
227252
| `leadingXl` | Line height paired with `text-xl` | `calc(1.75 / 1.25)` |
228253
| `leading2xl` | Line height paired with `text-2xl` | `calc(2 / 1.5)` |
254+
| `leading3xl` | Line height paired with `text-3xl` | `calc(2.25 / 1.875)` |
255+
| `inlineCodeWeight` | Weight of inline code in messages | `600` |
229256
| `dialogStroke` | Width of the dialog's edge stroke | `0px` |
230257
| `dialogPaddingX` | Inline padding of dialogs | `1.5rem` |
231258
| `dialogHeaderGap` | Gap between a dialog's title and description | `0.375rem` |
@@ -236,6 +263,7 @@ Appearance values are set **per mode**, and a mode without them uses the default
236263
| `scrimOpacity` | Strength of the scrim behind standard dialogs | `0.8` |
237264
| `alertScrimOpacity` | Strength of the scrim behind confirmation dialogs | `0.9` |
238265
| `modalScrimOpacity` | Strength of the scrim behind other modal dialogs | `0.65` |
266+
| `buttonNeutralBorderOpacity` | Opacity of the neutral button's border | Light: `0.1`; dark: `1` |
239267
| `elevationSurface` | Shadow of raised theme surfaces | `0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)` |
240268
| `elevationDrag` | Shadow of a badge while it is dragged | `0 10px 25px rgb(0 0 0 / 0.1)` |
241269
| `shadow2xs` | The `shadow-2xs` step | `0 1px rgb(0 0 0 / 0.05)` |
@@ -249,28 +277,35 @@ Appearance values are set **per mode**, and a mode without them uses the default
249277
| `tooltipShadow` | Shadow of tooltips | Light: `0 2px 4px 0 rgb(0 0 0 / 0.25)`; dark: `0 1px 2px 0 rgb(0 0 0 / 0.35)` |
250278
| `motionFast` | Duration of fast transitions | `150ms` |
251279
| `motionNormal` | Duration of normal transitions | `200ms` |
280+
| `chromeBorderAlpha` | How much of the border color the outlines of controls and chips keep; `0` hides them without moving anything | `1` |
281+
| `insetBorderAlpha` | How much of the border color the hairlines inside a stroked surface keep; `0` hides them | `1` |
282+
| `destructiveStyle` | How destructive actions are painted: `fill` uses the solid destructive surface, `soft` a tint of it | `fill` |
252283

253284
The defaults reproduce LibreChat's look, so a theme that sets none of these keys changes no shape.
254285

255286
Accepted values:
256287

257-
- **Radii, `controlHeight`, `controlPaddingX`, `controlGap`, button and field sizes, spacing, text and label sizes, and the dialog lengths (`dialogStroke`, `dialogPaddingX`, `dialogHeaderGap`, `dialogTitleSize`):** `0`, or a number in `px`, `rem` or `em` (such as `0.25rem`), or a single `calc()` of two such lengths (such as `calc(0.5rem - 2px)`).
288+
- **Radii, `controlHeight`, `controlPaddingX`, `buttonPaddingX`, `controlGap`, `buttonHeight`, `buttonHeightSm`, `fieldHeight`, `fieldPaddingY`, spacing, tooltip padding and text size, text and label sizes, and the dialog lengths (`dialogStroke`, `dialogPaddingX`, `dialogHeaderGap`, `dialogTitleSize`):** `0`, or a number in `px`, `rem` or `em` (such as `0.25rem`), or a single `calc()` of two such lengths (such as `calc(0.5rem - 2px)`).
289+
- **`buttonHeightXs`, `buttonHeightLg`, `buttonHeightCompact`, `iconButtonSizeSm` and `fieldHeightLg`:** a length in `px` or `rem` of at least `24px` (`1.5rem`), the minimum pointer target size.
290+
- **`iconSize`:** `12px` to `20px` (`0.75rem` to `1.25rem`). **`iconSizeMd`:** `20px` to `24px`. **`iconSizeLg`:** `16px` to `32px`. **`checkboxSize`:** `16px` to `24px`. **`listMaxHeight`:** `128px` to `640px` (`8rem` to `40rem`). Each is a length in `px` or `rem`.
291+
- **`tabMinWidth` and `listMinWidth`:** `0`, or a length in `px` or `rem`.
258292
- **`switchWidth` and `switchHeight`:** a positive length in `px` or `rem`. Both must use the same unit (a side you leave out uses its `rem` default), the width must exceed the height so the knob can travel, and the height must clear the 4px track border (more than `4px`, or at least `0.5rem`).
259293
- **`tableCellSpaceY` and `tableRowStroke`:** `0`, or a length in `px` or `rem`.
260294
- **`focusRingWidth`:** a positive length in `px` or `rem`, so the focus indicator never disappears.
261295
- **`focusRingOffset`:** `0`, or a length in `px` or `rem` that may be negative (drawing the outline inside the element's edge).
262296
- **`disabledStyle`:** `dim` or `fill`.
263297
- **`fieldFocusStyle`:** `ring` or `border`.
264298
- **`fieldFillStyle`:** `transparent` or `fill`.
265-
- **Font weights (`controlFontWeight`, `dialogTitleFontWeight`):** a whole number from `1` to `1000`. `labelFontWeight` also accepts `inherit`.
299+
- **Font weights (`controlFontWeight`, `dialogTitleFontWeight`, `inlineCodeWeight`):** a whole number from `1` to `1000`. `labelFontWeight` also accepts `inherit`.
266300
- **Line heights (the `leading*` steps, `labelLeading` and `dialogTitleLeading`):** a unitless number (such as `1.5`), a single `calc()` dividing two numbers (such as `calc(1.25 / 0.875)`), or a length.
267-
- **Scrim opacities:** a number from `0` to `1`.
301+
- **Scrim opacities, `buttonNeutralBorderOpacity`, `chromeBorderAlpha` and `insetBorderAlpha`:** a number from `0` to `1`.
302+
- **`destructiveStyle`:** `fill` or `soft`.
268303
- **Font families:** any non-empty `font-family` list without `;`, `{` or `}`. The font must be available to the browser: LibreChat bundles Inter, Roboto Mono and Inconsolata, so any other family has to be installed on the viewer's machine or served by your deployment, or the next family in the list is used.
269304
- **Shadow steps (`shadow2xs` through `shadow2xl`), `menuShadow`, `tooltipShadow` and `elevationDrag`:** a concrete `box-shadow` list, or `none`. `var()`, `env()`, `attr()` and `url()` are rejected.
270305
- **`elevationSurface`:** any non-empty `box-shadow` value without `;`, `{`, `}` or `url()`.
271306
- **Motion:** a duration in `ms` or `s`, such as `120ms`.
272307

273-
Every appearance value must be a string. Quote numbers such as font weights, line heights and scrim opacities (`'500'`, `'1.5'`, `'0.8'`); an unquoted YAML number is rejected.
308+
Every appearance value must be a string. Quote numbers such as font weights, line heights and opacities (`'500'`, `'1.5'`, `'0.8'`); an unquoted YAML number is rejected.
274309

275310
### Brands
276311

0 commit comments

Comments
 (0)