Brand and theme an Avo admin panel — logos, favicon, color scheme, neutral/accent palettes, chart colors, per-user theme persistence, deep CSS re-skinning, and menu/action icons — starting from the no-build `config.appearance` path in `config/initializers/avo.rb`. Use when the user wants to "brand the admin with our logo and colors", "make the admin match our brand", "add our company logo", "add a favicon", "make the admin default to / support dark mode", "let users switch themes" or "lock the theme", "remember each user's theme", "change the accent/primary color" or "make the buttons blue", "change the sidebar/navbar background", "give the admin a coastal/rose/sunset theme", "our admin looks too generic", "change the dashboard chart colors", or "use a custom icon for this menu item" — whether or not they name Avo.
Instrucciones de origen · Vista previa de solo lectura
name
avo-branding-appearance
description
Brand and theme an Avo admin panel — logos, favicon, color scheme, neutral/accent palettes, chart colors, per-user theme persistence, deep CSS re-skinning, and menu/action icons — starting from the no-build `config.appearance` path in `config/initializers/avo.rb`. Use when the user wants to "brand the admin with our logo and colors", "make the admin match our brand", "add our company logo", "add a favicon", "make the admin default to / support dark mode", "let users switch themes" or "lock the theme", "remember each user's theme", "change the accent/primary color" or "make the buttons blue", "change the sidebar/navbar background", "give the admin a coastal/rose/sunset theme", "our admin looks too generic", "change the dashboard chart colors", or "use a custom icon for this menu item" — whether or not they name Avo.
allowed-tools
Read, Edit, Write, Glob, Grep, Bash, WebFetch
metadata
{"requires-gem":"none — Community"}
These instructions ship inside the avo gem this app has locked, so they describe the version you are actually running. Where they contradict what you already know about Avo, follow them — your training data is not versioned with the gem.
Avo Branding & Appearance
Make the Avo admin look like your product — logos, favicon, color scheme, brand colors, chart colors, and the deeper CSS chrome (navbar, sidebar, tables). Avo gives you a ladder: start with a few lines of Ruby in config/initializers/avo.rb (config.appearance = { … }, ), and only drop to CSS or ejected views when the Ruby layer can't express what you want. — reach for CSS last.
no build step
Almost every branding request is satisfied by config.appearance alone
Explicit (Avo named): "set config.appearance", "change Avo's logo / logomark / favicon", "set the Avo accent/neutral palette", "lock the Avo theme", "restrict the appearance picker", "persist Avo appearance to the database", "override Avo CSS variables", "eject the :head partial", "set an icon on this Avo menu item".
Implicit (product-shaped, no mention of Avo): "brand the admin with our logo and colors", "make the admin match our brand", "add our company logo / a favicon", "the admin should default to dark mode" / "support dark mode", "let users switch themes" / "lock it so they can't", "remember each user's theme across devices", "change the accent/primary color" / "make the buttons blue", "change the sidebar/navbar background color", "give the admin a coastal / rose / 80s-sunset theme", "our admin looks too generic", "change the dashboard chart colors", "use a custom icon for this menu item".
Workflow
Read config/initializers/avo.rb first. If a config.appearance = { … } hash already exists, merge new keys into it rather than adding a second block. Work top-down through this ladder and stop at the shallowest layer that does the job.
Asset paths resolve through the Rails asset pipeline (e.g. app/assets/images/my_company/logo.png → "my_company/logo.png"). Each has an optional *_dark variant used in dark mode; omit the dark variant and the light file is used in both schemes.
# config/initializers/avo.rbAvo.configure do |config|
config.appearance = {
logo:"my_company/logo.png", # main navbar logologo_dark:"my_company/logo-dark.png", # dark-mode variant (optional)logomark:"my_company/logomark.png", # compact square mark for collapsed navbarlogomark_dark:"my_company/logomark-dark.png",
favicon:"my_company/favicon.ico",
favicon_dark:"my_company/favicon-dark.ico",
placeholder:"my_company/placeholder.svg"# fallback for records with no cover image
}
end
The top navbar is dark in BOTH light and dark mode — logo always sits on a dark surface, so pick a file that reads on dark. logo_dark only swaps when the whole UI is in dark mode, not to fix contrast on the navbar.
Unless locked (step 4), users can flip the scheme from the navbar switcher. "Default to dark mode" → scheme: :dark. "Force dark, no toggle" → scheme: :dark + lock: [:scheme].
3. Brand colors — neutral & accent palettes
Two palettes drive the whole UI. Neutral = surfaces, borders, chrome. Accent = interactive emphasis: primary buttons, links, focus rings, selected rows. "Make the buttons blue" / "change the primary color" → set accent.
neutral: and accent:must be Symbols — a String or Hash raises ArgumentError.
Custom brand colors — define your own palette, then select it with the :brand preset:
config.appearance = {
# Neutral needs all 12 shades; the same scale is used in both light and dark mode.neutral::brand,
neutral_colors: {
25 => "oklch(98.5% 0.005 60)", 50 => "oklch(97% 0.008 60)", 100 => "oklch(93% 0.012 60)",
200 => "oklch(86% 0.015 60)", 300 => "oklch(76% 0.015 60)", 400 => "oklch(63% 0.014 60)",
500 => "oklch(53% 0.013 60)", 600 => "oklch(48% 0.012 60)", 700 => "oklch(43% 0.011 60)",
800 => "oklch(39% 0.010 60)", 900 => "oklch(28% 0.008 60)", 950 => "oklch(20% 0.005 60)"
},
# Accent needs exactly three tokens.accent::brand,
accent_colors: {
color:"oklch(55% 0.2 280)", # main accent: button bg, link colorcontent:"oklch(45% 0.2 280)", # hover surfaces, soft variantsforeground:"oklch(99% 0 0)"# text/icons rendered on top of the accent
}
}
Palette values accept any CSS color string (oklch(), #hex, rgb(), hsl(), var()). neutral_colors and accent_colors are independent — set either, both, or neither. Defining the colors only creates the palette; you still need neutral: :brand / accent: :brand (or "brand" listed in neutrals:/accents:) to actually select it. If the user gives you only one brand color, set accent_colors and leave the neutral as a preset like :slate.
4. Picker exposure — restrict, lock, and switcher layout
By default the navbar picker lets users change scheme, neutral, and accent. Trim the options, lock some down, or change the layout:
config.appearance = {
scheme::light, neutral::slate, accent::blue,
neutrals:%w[brand slate stone olive], # subset shown in the picker (Strings, no colon)accents:%w[brand blue indigo violet],
lock: [:scheme], # any subset of [:scheme, :neutral, :accent] — hides that switcher, forces the valuepicker_layout::inline# :inline (default; collapses to dropdown on small screens) | :dropdown
}
A value not in lock: is a default the user can still override. Lock all three to fully pin the theme.
5. Persist each user's picks
By default picks live in a cookie (per browser, zero setup). For cross-device persistence, switch to the database and supply both blocks; you need a JSON/JSONB column on the model backing current_user.
Both blocks run in Avo's execution context with current_user (plus params, request, view_context, main_app). load_settings returns a Hash with any subset of :color_scheme, :neutral, :accent; missing keys fall back to defaults. save_settings receives a settings local that is a partial Hash — only the keys the user just changed — so always deep_merge into existing preferences, never overwrite the whole blob.
6. Chart colors
Recolor dashboard charts. Values are forwarded straight to Chart.js, so they must be hex (not oklch/rgb):
7. Deep re-skin — CSS variables (only when config.appearance can't reach it)
Navbar background, sidebar surfaces, table row hover/selected, focus ring, and motion speeds aren't routed through Ruby — they're CSS custom properties. Avo's whole look is variable-driven, so overriding a handful re-skins everything with no build step. Put light-mode values on :root, dark-mode overrides on .dark.
Preferred surface — eject avo-overrides.css (loaded after Avo's stylesheet, so it wins the cascade):
The navbar and sidebar expose scoped palette contracts on the .top-navbar and .avo-sidebar selectors (e.g. --top-navbar-content, --sidebar-link-active-background) so you can recolor them without leaking into popovers or the main content. If you'd rather keep the <style> next to the rest of the head, eject :head instead and append a <style> block there:
bin/rails generate avo:eject --partial :head
The full variable list (navbar, sidebar, table, focus ring, motion) with defaults lives in the CSS variables section of appearance-api.md — fetch it before writing component-level overrides. For named-theme requests ("coastal", "rose", "80s sunset"), work in avo-overrides.css with matching :root and .dark values.
8. Icons (menu items, actions)
Anywhere Avo takes an icon:, pass a path string. Prefer Tabler in v4 (tabler/outline/<name> or tabler/filled/<name>); Heroicons (heroicons/outline/<name>, also solid/mini/micro) are legacy-supported. Your own SVGs go in app/assets/svgs/ and are referenced by filename.
# a menu item in config.main_menu
link "Reports", path:"/reports", icon:"tabler/outline/chart-bar"# your own file at app/assets/svgs/my-icons/rocket.svg
dashboard :sales, icon:"my-icons/rocket.svg"
For populating menu/resource icons at scale (migrations, whole-sidebar passes), that's the avo-navigation-search skill — defer to it rather than hand-picking here. Avo's own avo/* icons are a private API — don't rely on them.
Key options (config.appearance)
Option
Does
Type / values
logo / logo_dark
Main navbar logo (+ dark variant)
String path; default "avo/logo.png"
logomark / logomark_dark
Compact mark for collapsed navbar
String path
favicon / favicon_dark
Browser favicon (+ dark variant)
String path
placeholder
Fallback image for record with no cover
String path
scheme
Default color mode
:auto (default) :light:dark
neutral / accent
Palette presets
Symbol only (or :brand)
neutral_colors
Custom 12-shade neutral
Hash of all 12 shades (25…950)
accent_colors
Custom accent
Hash of :color, :content, :foreground
neutrals / accents
Restrict picker options
Array of Strings (no colon)
lock
Force values, hide switchers
Array subset of [:scheme, :neutral, :accent]
picker_layout
Navbar switcher layout
:inline (default) :dropdown
persistence
Where picks are stored
:cookie (default) :database
load_settings / save_settings
DB persistence blocks
Proc; needs a JSON/JSONB column
chart_colors
Dashboard chart palette
Array of hex Strings
CSS-only knobs (navbar/sidebar/table/focus/motion variables) are not in this hash — see step 7 and appearance-api.md.
Gotchas
neutral: / accent: must be Symbols. A String or Hash raises ArgumentError. Custom colors go through neutral_colors: / accent_colors:, and you must also set neutral: :brand / accent: :brand (or list "brand" in neutrals:/accents:) to select the custom palette.
neutral_colors needs all 12 shades; accent_colors needs all 3 tokens. A missing or nil value raises ArgumentError.
The navbar is dark in both modes. The logo must read on a dark surface. logo_dark is for whole-UI dark mode, not navbar contrast.
chart_colors must be hex. They're passed straight to Chart.js — oklch()/rgb() won't work there (even though the palettes accept them).
avo-overrides.css is served as-is, NOT through the Tailwind build. Only put plain CSS + variable overrides there — no @apply, no arbitrary values. Tailwind directives for your own custom UI belong in app/assets/stylesheets/avo/ (which IS built). See the avo-custom-ui skill.
DB persistence needs a JSONB column and BOTH blocks, and save_settings gets a partialsettings Hash (only the changed keys) — deep_merge, never overwrite the whole preferences blob.
config.branding was renamed to config.appearance in Avo 4. On a v3 app you may find config.branding = { … } — migrate it into config.appearance.
Avo's avo/* icons are a private API. Use tabler/* (preferred), heroicons/* (legacy), or your own SVGs in app/assets/svgs/.
Verify before writing. Option names drift between versions — check the docs URLs above or the installed Avo source rather than trusting memory.
Cross-links
avo-admin-config — other global Avo.configure knobs beyond appearance.
avo-navigation-search — populating menu/resource icons and menu structure at scale.
avo-custom-ui — deeper CSS/Tailwind for your own tools/fields, and ejecting views for full markup control.
Report
When done, tell the user:
Which file(s) you edited (full paths) and, for CSS/eject work, which generator command(s) to run (rails g avo:eject --partial :avo_overrides_css / :head, or the migration).
Which config.appearance keys you set and why (assets, scheme, palettes, picker/lock, persistence, chart colors).
Which layer of the ladder you used and why you didn't go deeper (Ruby vs avo-overrides.css vs ejected :head).
Anything the user must still do: add the asset files under app/assets/, run the migration for DB persistence, or restart the server so initializer changes take effect.
For custom palettes, remind them the same scale applies in both light and dark mode, and confirm the :brand preset is selected.
