LibreChat/packages/client/src/theme/allowlist.md
Marco Beretta a2b184b231
🖍️ fix: Read Theme Roles for the Last Artifact and Agent Chip Colours (#16705)
* fix: Read Theme Roles for the Last Artifact and Agent Chip Colours

The artifact mobile backdrop now reads surface-overlay like the dialog scrims, the refresh overlay over the rendered preview reads surface-media-overlay, and the agent builder's provider chip reads surface-primary and text-primary like the conversation icon chip. Monaco's built-in vs-dark canvas joins the third-party surfaces allowlist entry, and the allowlist no longer points at a closed sweep issue.

* test: Cover Theme Roles on the Provider Chip and Artifact Overlays
2026-10-03 12:56:45 +02:00

7.7 KiB

Colours outside the theme

Every colour in client/src and packages/client/src comes from a semantic theme role, except the entries below. Each entry is one kind of colour that must not follow the theme, with the files that hold it and why the theme does not own it. Scrims, chips and progress drawn over the user's own media are not exceptions: they read surface-media-overlay and text-on-media, which every bundled theme keeps black and white. The drop zone's artwork reads the illustration roles, file-type tiles the file-* roles, the default avatar's hairline avatar-edge, and a dragged badge's lift elevationDrag.

A literal the design lint can see stays recorded in eslint-suppressions.json (inline disables of the design rules are rejected by the static checks), so its count there is the exception, not debt; the file-scoped allow entry for these paths belongs in eslint.config.mjs. Everything else is invisible to the lint (CSS, strings passed to a canvas or an iframe), so this list is the record.

Adding an entry needs the same bar: if a theme author would reasonably want to recolour it, it is a role, not an exception. Keep the list to ten entries or fewer; a new kind of exception that does not fit an entry below is a sign it should be a role.

# Entry Files Why
1 Theme definitions packages/client/src/theme/themes/*.ts, themes/clickui.json, packages/client/src/theme/registry.ts, packages/client/src/theme/defaults.css, packages/client/src/theme/tokens.css The palettes and appearance values themselves: these are the values roles resolve to.
2 Third-party brand marks packages/client/src/svgs/GoogleIcon.tsx, FacebookIcon.tsx, DiscordIcon.tsx, GeminiIcon.tsx, PaLMIcon.tsx; client/src/mobile.css (.azure-bg-color); client/src/components/Chat/Input/Files/SourceIcon.tsx (the OpenAI chip) Fixed by each company's brand guidelines: the Google, Facebook, Discord, Gemini and PaLM marks, the Azure file-source chip's blue gradient, and the OpenAI file-source chip (white/75, black/65 in dark) behind OpenAI's mark.
3 Provider brand colours packages/client/src/icons/provider/registry.ts, icons/provider/Avatar.tsx Each provider colour is already behind a --provider-* variable a deployment can override; the literal is only its fallback.
4 Opt-in decorative palettes packages/client/src/svgs/BirthdayIcon.tsx, packages/client/src/components/PixelCard.tsx A multicolour illustration, and the blue, yellow and pink PixelCard presets a caller opts into like its colors prop. The app renders only PixelCard's default, which reads theme roles.
5 Documents that leave the app client/src/utils/markdown.ts, client/src/utils/richtext.ts The downloaded HTML document's GitHub Primer stylesheet, and inline styles on HTML copied to the clipboard; both are read outside the app, where no theme variables exist and the sender's theme must not travel. The markdown high-contrast branch reads the roles.
6 Sandboxed iframe documents client/src/utils/mermaid.ts, client/src/utils/artifacts.ts The mermaid document and its zoom controls, and the artifact document's scrollbar thumb, render in their own iframe without theme variables; the token reads' fallbacks and the luminance repair ink are literals by necessity.
7 Third-party surfaces client/src/hooks/Files/useSharePointPicker.ts, client/src/components/Artifacts/ArtifactCodeEditor.tsx Background of Microsoft's SharePoint file picker iframe, matched to that third party's own surface, and the canvas of Monaco's built-in vs-dark editor theme, painted behind the editor while it loads so the Code tab does not flash; Monaco owns that colour, and the high-contrast editor themes already read the roles.
8 Library stylesheet elevation packages/client/src/components/Dropdown.css, packages/client/src/components/Tooltip.css Popover and tooltip shadows in black alpha. The app paints .popover-ui from its own copy of the Dropdown rules in client/src/style.css, so both copies move to --theme-shadow-lg together; the tooltip shadow is smaller than any shadow step.
9 Fallbacks for a role read at runtime client/src/utils/officePreview.ts, client/src/hooks/ScreenshotContext.tsx Used only when the role's variable is unset; the value painted otherwise is the role, read with readThemeColor or from the bundled palette.