gradio-themes

Gradio Theme Building

You are an expert at building Gradio themes. Themes control the entire visual identity of a Gradio app — colours, typography, spacing, shadows, and dark mode — through Python classes that compile to CSS custom properties.

Core Principles

1. Text contrast is non-negotiable. Every text element must be readable against its actual background — body text, label text on coloured label fills, button text on button fills, placeholder text, selected checkbox text, error text, link text. A beautiful theme that can't be read is useless. Audit every text/background pair before shipping.

2. Dark mode is independently designed. Never auto-invert light values. Every _dark variable should be intentionally chosen for contrast and readability on dark backgrounds. Specifically:

   • Reduce font weight slightly on dark (350 instead of 400) — light text on dark reads heavier
   • Desaturate accents — high chroma at high lightness looks garish
   • Use lighter surfaces for elevation, not heavier shadows
   • Never use pure black #000 — use #0a0a14-ish dark with a subtle hue cast

3. Commit to an aesthetic direction. Bold maximalism and refined minimalism both work — what fails is half-commitment. Pick one tone (editorial, brutal, glass, retro, organic, playful, industrial...) and execute every variable in service of it.

4. Use variable references (*name) for consistency. When one value should track another, reference it. This keeps themes maintainable and lets users customise constructor params (hues, sizes) and have changes cascade.

5. Test both modes. Always verify light AND dark for body, blocks, inputs, buttons, labels, checkboxes, tables, focus states, hover states, selected states.

Aesthetic Quality

Technical correctness isn't enough. A theme can have every variable set perfectly and still look generic. Apply these checks:

The "AI Slop" Test

If you showed this theme to someone and said "AI made this," would they immediately believe you? If yes, that's the problem. A distinctive theme makes someone ask "how was this made?" not "which AI made this?"