![Streamlit 主题模板：12 套可直接复用的 `[theme]` 配置与自定义指南](http://pic.xiahunao.cn/yaotu/Streamlit 主题模板：12 套可直接复用的 `[theme]` 配置与自定义指南)
Streamlit 主题模板12 套可直接复用的[theme]配置与自定义指南【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit导读本文以 Streamlit 仓库中developing-with-streamlit技能包附带的12 套现成主题模板Dracula、Nord、VS Code、Material UI、Ubuntu 等为核心系统讲解如何通过.streamlit/config.toml的[theme]配置块快速套用这些主题并结合仓库源码与完整主题指南深入剖析配色、字体、圆角、明暗双模式等全部可配置项。读完本文你将能够一键为应用换肤也能从零定制出一套符合品牌规范、满足 WCAG AA 对比度要求的高质量 Streamlit 主题。主题模板速览12 套开箱即用的配置在仓库目录 lib/streamlit/.agents/skills/developing-with-streamlit/assets/templates/themes/configs/ 下每一份.toml文件都是一段完整的[theme]配置块可直接粘贴进应用根目录下的.streamlit/config.toml中。模板不依赖任何本地字体文件——所有字体均通过 Google Fonts 在线加载。主题基准base主色Primary Color字体FontsdraculaDark#BD93F9紫Fira Sans, JetBrains Monofinancial-dashboardDark#60A5FA蓝Inter, JetBrains MonofluentLight#0078D4蓝Segoe UI, Cascadia CodejupyterLight#F37626橙Source Sans 3, Source Code Promaterial-uiLight#6750A4紫罗兰Roboto, Roboto MonominimalDark#6366F1靛蓝Inter, JetBrains MononordDark#88C0D0霜蓝Inter, JetBrains Monoone-dark-proDark#61AFEF蓝IBM Plex Sans, JetBrains MonoshadcnLight#18181B锌灰Inter, JetBrains Monosolarized-lightLight#268BD2蓝Source Sans 3, Source Code ProubuntuLight#E95420橙Ubuntu, Ubuntu MonovscodeDark#0078D4蓝Segoe UI, Fira Code这些模板覆盖了开发者社区最流行的配色体系既有 Dracula、One Dark Pro、VS Code 这类程序员熟悉的编辑器深色主题也有 FluentWindows 11、Material UIMaterial Design 3这类现代设计语言以及 Nord 极地霜蓝、Solarized 高可读性配色的经典之作。使用方式一分钟套用任意主题每个模板文件的头部都有简明的用途注释例如 dracula.toml# Dracula Theme for Streamlit # Popular dark theme with vibrant colors on dark background [theme] base dark primaryColor #bd93f9 backgroundColor #282a36 secondaryBackgroundColor #21222c # ... 其余配置将整个[theme]块连同[theme.sidebar]复制到你的应用中mkdir -p .streamlit # 将所选模板内容粘贴到 .streamlit/config.toml保存config.toml后刷新页面即可看到效果。绝大多数主题选项会在保存后实时生效只需重新运行应用仅与字体相关的fontFaces选项需要重启服务器。主题继承从已有主题出发base选项决定主题继承的基准支持三种取值源码定义见 lib/streamlit/config.py[theme] base light # 或 dark # base ./my-base-theme.toml # 本地主题文件 # base https://example.com/theme.toml # 远程主题 URL使用base时只需覆盖你想修改的值未覆盖的自动继承。注意外部主题文件本地或远程中只能包含单个[theme]段不支持[theme.light]/[theme.dark]变体。模板内部结构读懂一份主题配置以功能最全的 financial-dashboard.toml 为例一份专业主题通常包含以下层次[theme] base dark primaryColor #60A5FA # 主色按钮、链接、激活元素 backgroundColor #0F172A # 主内容背景 secondaryBackgroundColor #1E293B # 组件背景、代码块 textColor #F1F5F9 # 正文文字 linkColor #60A5FA # Markdown 链接默认继承 primaryColor codeTextColor #CBD5E1 # 行内代码文字 borderColor #334155 # 组件边框 # 字体族 font Inter:https://fonts.googleapis.com/css2?familyInter:wght400;500;600;700displayswap headingFont Inter:https://fonts.googleapis.com/css2?familyInter:wght600;700displayswap codeFont JetBrains Mono:https://fonts.googleapis.com/css2?familyJetBrainsMono:wght400;500displayswap # 语义色状态指示、Markdown 文字着色、迷你趋势图 greenColor #34D399 # 涨/正 redColor #F87171 # 跌/负 yellowColor #FBBF24 # 警告 orangeColor #FB923C # 提示 blueColor #60A5FA # 信息 violetColor #A78BFA # 强调/高亮 grayColor #94A3B8 # 中性/次级文字 # 图表色 chartCategoricalColors [#60A5FA, #34D399, #A78BFA, #F87171, #FBBF24, #38BDF8, #94A3B8, #FB923C] chartSequentialColors [#0C4A6E, #075985, #0369A1, #0284C7, #0EA5E9, #38BDF8, #7DD3FC, #BAE6FD, #E0F2FE, #F0F9FF] # 数据表样式 dataframeBorderColor #334155 dataframeHeaderBackgroundColor #1E293B [theme.sidebar] backgroundColor #0F172A secondaryBackgroundColor #1E293B textColor #F1F5F9 borderColor #334155 primaryColor #60A5FA这份配置的典型结构被 12 个模板一致遵循体现了完整的 Streamlit 主题维度。接下来逐一解读这些维度。配色体系从主色到语义色核心颜色[theme] primaryColor #0969da # 按钮、链接、激活元素 backgroundColor #ffffff # 主内容背景 secondaryBackgroundColor #f6f8fa # 组件背景、代码块 textColor #1F2328 # 正文文字 # 可选微调项 linkColor #0969da # Markdown 链接默认取 primaryColor codeTextColor #1F2328 # 行内代码文字 codeBackgroundColor #f6f8fa # 代码块背景 borderColor #d0d7de # 组件边框设计要点primaryColor必须足够深、能与白色文字形成对比——Streamlit 主按钮的文字固定为白色渲染在primaryColor之上。语义色调色板用于状态指示器、Markdown 文字着色和迷你趋势图sparkline[theme] redColor #cf222e orangeColor #bf8700 yellowColor #dbab09 greenColor #1a7f37 blueColor #0969da violetColor #8250df grayColor #57606a每种颜色还支持背景色与文字色变体未显式设置时自动从基础色派生[theme] greenColor #1a7f37 greenBackgroundColor #dafbe1 # 徽章等浅色底 greenTextColor #116329 # 加深以保证可读性图表颜色为 Plotly、Altair、Vega-Lite、ECharts 图表定义颜色可分别设置在[theme]、[theme.light]、[theme.dark]及对应的 sidebar 段中未设置的段自动继承[theme][theme] # 分类数据柱状、饼图、系列 chartCategoricalColors [#0969da, #1a7f37, #bf3989, #8250df, #cf222e, #bf8700, #57606a] # 连续/渐变数据热力图—— 必须恰好 10 个颜色 chartSequentialColors [#f0f6fc, #c8e1ff, #79c0ff, #58a6ff, #388bfd, #1f6feb, #1158c7, #0d419d, #0a3069, #04244a] [theme.dark] # 深色背景下更明亮的调色板 chartCategoricalColors [#58a6ff, #3fb950, #db61a2, #a371f7, #f85149, #d29922, #8b949e]数据表样式[theme] dataframeBorderColor #d0d7de dataframeHeaderBackgroundColor #f6f8fa注意数据表表头使用主文字色渲染需确保textColor在dataframeHeaderBackgroundColor上清晰可读。字体配置内置字体、Google Fonts 与自托管字体族三选一[theme] # 内置选项 font sans-serif # 或 serif / monospace # Google Fontsfamily:stylesheet_url 语法 font Inter:https://fonts.googleapis.com/css2?familyInter:wght300;400;500;600;700displayswap # 名称含空格的字体需要引号 font IBM Plex Sans:https://fonts.googleapis.com/css2?familyIBMPlexSans:wght400;500;600displayswap12 个模板全部采用font family:stylesheet_url语法加载 Google Fonts因此无需在本地存放任何字体文件开箱即用。自托管自定义字体通过[[theme.fontFaces]]表借助 Streamlit 的静态文件服务加载字体。字体文件必须放在应用的static/目录中并通过应用提供不能引用任意本地路径。在写入 config.toml 之前务必确认字体文件确实存在于 static 目录[[theme.fontFaces]] family CustomFont url app/static/CustomFont-Regular.woff2 weight 400 [[theme.fontFaces]] family CustomFont url app/static/CustomFont-Bold.woff2 weight 700 [theme] font CustomFont各属性说明family字体名、urlOTF/TTF/WOFF/WOFF2 路径、weight400、200 800或bold、stylenormal/italic/oblique、unicodeRange如U0000-00FF。fontFaces的修改需要重启服务器才能生效。标题与代码字体、字号与字重[theme] headingFont Inter:https://fonts.googleapis.com/css2?familyInter:wght600;700displayswap codeFont JetBrains Mono:https://fonts.googleapis.com/css2?familyJetBrainsMono:wght400;500displayswap baseFontSize 14 # 根字号像素默认 16 baseFontWeight 400 # 常规字重 codeFontSize 0.875rem # 相对基础字号或用 13px codeFontWeight 400 # 标题层级 h1~h6也可用单个值统一设置 headingFontSizes [32px, 24px, 20px, 16px, 14px, 12px] headingFontWeights [600, 600, 600, 500, 500, 500] linkUnderline false # 移除链接下划线观感更干净以 vscode.toml 为例它用codeFontSize 13px、baseFontSize 14复刻了 VS Code 编辑器的紧凑排版并显式定义了headingFontSizes/headingFontWeights两个 6 元素数组。圆角与边框[theme] baseRadius 8px # 所有组件none/small/medium/large/full/px/rem buttonRadius 8px # 按钮单独设置默认继承 baseRadius showWidgetBorder true # 未聚焦组件是否显示边框 showSidebarBorder true # 侧边栏与主内容之间是否显示分隔线圆角关键字none0、small4px、medium8px、large12px、full胶囊形。不同模板在圆角上风格迥异material-ui 使用baseRadius 16px、buttonRadius full表达 Material 3 的圆润感jupyter 则用2px贴近笔记本风格的锐利边缘。侧边栏独立定制[theme.sidebar]允许侧边栏与主内容区使用完全不同的配色[theme.sidebar] backgroundColor #f6f8fa secondaryBackgroundColor #eaeef2 codeBackgroundColor #eaeef2 textColor #1F2328 borderColor #d0d7de primaryColor #0969da # 侧边栏内激活元素ubuntu.toml 是侧边栏深色化的典型——主内容区为白色浅色主题侧边栏却使用#2C001E深紫底色与#FFFFFF白色文字形成强烈的品牌对比。明暗双模式[theme.light]与[theme.dark]同时定义[theme.light]和[theme.dark]后用户可在应用设置菜单中自由切换明暗模式只定义[theme]会把应用锁定为单一模式。[theme.light] primaryColor #0969da backgroundColor #ffffff secondaryBackgroundColor #f6f8fa textColor #1F2328 chartCategoricalColors [#0969da, #1a7f37, #bf3989, #8250df, #cf222e, #bf8700, #57606a] [theme.dark] primaryColor #58a6ff backgroundColor #0d1117 secondaryBackgroundColor #161b22 textColor #e6edf3 chartCategoricalColors [#58a6ff, #3fb950, #db61a2, #a371f7, #f85149, #d29922, #8b949e] [theme.light.sidebar] backgroundColor #f6f8fa [theme.dark.sidebar] backgroundColor #010409侧边栏也支持各自的明暗变体[theme.light.sidebar]/[theme.dark.sidebar]。源码层面这些配置段在 lib/streamlit/config.py 中统一注册——theme、theme.sidebar、theme.light、theme.dark及嵌套的theme.light.sidebar、theme.dark.sidebar六个段均可承载全部主题选项。在代码中感知当前主题使用st.context.theme.type让应用适配当前主题典型场景为特定图表微调颜色以提升对比度按模式切换 Logo 图片浅色模式用深色 Logo反之亦然为不自动适配主题的第三方组件补样式if st.context.theme.type dark: # 深色模式下的处理逻辑 pass设计原则对比度、配色协调与视觉层级颜色对比度遵循 WCAG AA 规范正文对比度 ≥ 4.5:1浅色主题深色文字#1F2328配浅色背景#ffffff深色主题浅色文字#e6edf3配深色背景#0d1117primaryColor必须能与白色按钮文字形成对比三种配色策略单色系单一色相、不同明度如 shadcn 的锌灰系primaryColor #18181B textColor #09090B borderColor #E4E4E7 grayColor #71717A品牌点缀中性基底 单一品牌色primaryColor #635bff # 品牌紫 backgroundColor #ffffff textColor #425466 # 中性灰互补搭配品牌主色 辅助强调色primaryColor #0969DA # 品牌蓝 textColor #1F2328 # 近黑文字 greenColor #36B37E # 成功态 redColor #DE350B # 错误态排版与视觉层级正文14–16px字重 400标题h128–40px到 h612–14px递减代码等宽字体比正文略小0.85–0.875rem字体搭配正文与标题同字体更统一也可配对互补字体如衬线标题 无衬线正文代码必须始终使用独立的等宽字体背景分层主内容最浅 → 次级元素略深 → 侧边栏独立或品牌色 → 代码块匹配次级背景完整示例从模板到自定义以 VS Code 深色主题为例theme.md 中给出了一份完整的 VS Code 深色主题配置与模板 vscode.toml 完全一致——这也是将模板作为起点、再做品牌化微调的最佳范本[theme] base dark primaryColor #0078d4 backgroundColor #1e1e1e secondaryBackgroundColor #252526 codeBackgroundColor #1e1e1e textColor #cccccc linkColor #3794ff borderColor #3c3c3c showWidgetBorder true showSidebarBorder true baseRadius 4px buttonRadius 4px font Segoe UI, Open Sans:https://fonts.googleapis.com/css2?familyOpenSans:wght300;400;500;600;700displayswap codeFont Fira Code:https://fonts.googleapis.com/css2?familyFiraCode:wght400;500displayswap codeFontSize 13px codeTextColor #d4d4d4 baseFontSize 14 baseFontWeight 400 headingFontSizes [28px, 22px, 18px, 16px, 14px, 12px] headingFontWeights [600, 600, 600, 600, 600, 600] linkUnderline false chartCategoricalColors [#0078d4, #4ec9b0, #dcdcaa, #ce9178, #c586c0, #569cd6, #6a9955] blueColor #569cd6 greenColor #6a9955 yellowColor #dcdcaa orangeColor #ce9178 violetColor #c586c0 [theme.sidebar] backgroundColor #252526 secondaryBackgroundColor #333333 codeBackgroundColor #1e1e1e borderColor #3c3c3c常见错误与排查错误类型错误示例正确做法主色太浅primaryColor #FFEB3B黄底白字不可读用更深色如#F59E0B对比度不足textColor #CCCCCC配白色背景深色文字#1F2328配浅背景背景层级颠倒backgroundColor #f6f8fa、secondaryBackgroundColor #ffffff次级背景应更深/更显著侧边栏对比度遗漏只改backgroundColor其余颜色未调深色侧边栏需同步调整secondaryBackgroundColor、textColor、borderColor等全部颜色重要约束优先使用原生主题而非自定义 CSS主题开发中有一条硬性约束——除非用户明确要求不要使用自定义 CSS 或 HTML 做主题包括st.markdown(..., unsafe_allow_htmlTrue)内嵌style、st.html()写样式块等。品牌色、背景、字体等视觉身份一律使用config.toml原生主题完成它更干净、更易维护且不会因 Streamlit 版本升级而失效。若用户明确要求 CSS例如加自定义 CSS可通过key生成可定位的类名st.button(Submit, keysubmit) # 生成类名.st-key-submit st.html(style.st-key-submit button { width: 100%; }/style)主题开发工作流与验收清单用streamlit config show查看当前版本完整的主题配置选项及说明主题选项分组在[theme]、[theme.sidebar]及明暗变体之下从模板 configs/ 复制一份到.streamlit/config.toml或设置base继承后覆盖差异项保存后重新运行应用观察实时生效效果fontFaces除外需重启依次验收按钮主色对比、表单边框与聚焦态、数据表表头、代码块、各类图表、侧边栏。相关参考主题模板 README完整主题指南 theme.md主题配置源码 lib/streamlit/config.py开发技能入口 SKILL.md设计规范 design.md【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Streamlit 主题模板：12 套可直接复用的 `[theme]` 配置与自定义指南
Streamlit 主题模板12 套可直接复用的[theme]配置与自定义指南【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit导读本文以 Streamlit 仓库中developing-with-streamlit技能包附带的12 套现成主题模板Dracula、Nord、VS Code、Material UI、Ubuntu 等为核心系统讲解如何通过.streamlit/config.toml的[theme]配置块快速套用这些主题并结合仓库源码与完整主题指南深入剖析配色、字体、圆角、明暗双模式等全部可配置项。读完本文你将能够一键为应用换肤也能从零定制出一套符合品牌规范、满足 WCAG AA 对比度要求的高质量 Streamlit 主题。主题模板速览12 套开箱即用的配置在仓库目录 lib/streamlit/.agents/skills/developing-with-streamlit/assets/templates/themes/configs/ 下每一份.toml文件都是一段完整的[theme]配置块可直接粘贴进应用根目录下的.streamlit/config.toml中。模板不依赖任何本地字体文件——所有字体均通过 Google Fonts 在线加载。主题基准base主色Primary Color字体FontsdraculaDark#BD93F9紫Fira Sans, JetBrains Monofinancial-dashboardDark#60A5FA蓝Inter, JetBrains MonofluentLight#0078D4蓝Segoe UI, Cascadia CodejupyterLight#F37626橙Source Sans 3, Source Code Promaterial-uiLight#6750A4紫罗兰Roboto, Roboto MonominimalDark#6366F1靛蓝Inter, JetBrains MononordDark#88C0D0霜蓝Inter, JetBrains Monoone-dark-proDark#61AFEF蓝IBM Plex Sans, JetBrains MonoshadcnLight#18181B锌灰Inter, JetBrains Monosolarized-lightLight#268BD2蓝Source Sans 3, Source Code ProubuntuLight#E95420橙Ubuntu, Ubuntu MonovscodeDark#0078D4蓝Segoe UI, Fira Code这些模板覆盖了开发者社区最流行的配色体系既有 Dracula、One Dark Pro、VS Code 这类程序员熟悉的编辑器深色主题也有 FluentWindows 11、Material UIMaterial Design 3这类现代设计语言以及 Nord 极地霜蓝、Solarized 高可读性配色的经典之作。使用方式一分钟套用任意主题每个模板文件的头部都有简明的用途注释例如 dracula.toml# Dracula Theme for Streamlit # Popular dark theme with vibrant colors on dark background [theme] base dark primaryColor #bd93f9 backgroundColor #282a36 secondaryBackgroundColor #21222c # ... 其余配置将整个[theme]块连同[theme.sidebar]复制到你的应用中mkdir -p .streamlit # 将所选模板内容粘贴到 .streamlit/config.toml保存config.toml后刷新页面即可看到效果。绝大多数主题选项会在保存后实时生效只需重新运行应用仅与字体相关的fontFaces选项需要重启服务器。主题继承从已有主题出发base选项决定主题继承的基准支持三种取值源码定义见 lib/streamlit/config.py[theme] base light # 或 dark # base ./my-base-theme.toml # 本地主题文件 # base https://example.com/theme.toml # 远程主题 URL使用base时只需覆盖你想修改的值未覆盖的自动继承。注意外部主题文件本地或远程中只能包含单个[theme]段不支持[theme.light]/[theme.dark]变体。模板内部结构读懂一份主题配置以功能最全的 financial-dashboard.toml 为例一份专业主题通常包含以下层次[theme] base dark primaryColor #60A5FA # 主色按钮、链接、激活元素 backgroundColor #0F172A # 主内容背景 secondaryBackgroundColor #1E293B # 组件背景、代码块 textColor #F1F5F9 # 正文文字 linkColor #60A5FA # Markdown 链接默认继承 primaryColor codeTextColor #CBD5E1 # 行内代码文字 borderColor #334155 # 组件边框 # 字体族 font Inter:https://fonts.googleapis.com/css2?familyInter:wght400;500;600;700displayswap headingFont Inter:https://fonts.googleapis.com/css2?familyInter:wght600;700displayswap codeFont JetBrains Mono:https://fonts.googleapis.com/css2?familyJetBrainsMono:wght400;500displayswap # 语义色状态指示、Markdown 文字着色、迷你趋势图 greenColor #34D399 # 涨/正 redColor #F87171 # 跌/负 yellowColor #FBBF24 # 警告 orangeColor #FB923C # 提示 blueColor #60A5FA # 信息 violetColor #A78BFA # 强调/高亮 grayColor #94A3B8 # 中性/次级文字 # 图表色 chartCategoricalColors [#60A5FA, #34D399, #A78BFA, #F87171, #FBBF24, #38BDF8, #94A3B8, #FB923C] chartSequentialColors [#0C4A6E, #075985, #0369A1, #0284C7, #0EA5E9, #38BDF8, #7DD3FC, #BAE6FD, #E0F2FE, #F0F9FF] # 数据表样式 dataframeBorderColor #334155 dataframeHeaderBackgroundColor #1E293B [theme.sidebar] backgroundColor #0F172A secondaryBackgroundColor #1E293B textColor #F1F5F9 borderColor #334155 primaryColor #60A5FA这份配置的典型结构被 12 个模板一致遵循体现了完整的 Streamlit 主题维度。接下来逐一解读这些维度。配色体系从主色到语义色核心颜色[theme] primaryColor #0969da # 按钮、链接、激活元素 backgroundColor #ffffff # 主内容背景 secondaryBackgroundColor #f6f8fa # 组件背景、代码块 textColor #1F2328 # 正文文字 # 可选微调项 linkColor #0969da # Markdown 链接默认取 primaryColor codeTextColor #1F2328 # 行内代码文字 codeBackgroundColor #f6f8fa # 代码块背景 borderColor #d0d7de # 组件边框设计要点primaryColor必须足够深、能与白色文字形成对比——Streamlit 主按钮的文字固定为白色渲染在primaryColor之上。语义色调色板用于状态指示器、Markdown 文字着色和迷你趋势图sparkline[theme] redColor #cf222e orangeColor #bf8700 yellowColor #dbab09 greenColor #1a7f37 blueColor #0969da violetColor #8250df grayColor #57606a每种颜色还支持背景色与文字色变体未显式设置时自动从基础色派生[theme] greenColor #1a7f37 greenBackgroundColor #dafbe1 # 徽章等浅色底 greenTextColor #116329 # 加深以保证可读性图表颜色为 Plotly、Altair、Vega-Lite、ECharts 图表定义颜色可分别设置在[theme]、[theme.light]、[theme.dark]及对应的 sidebar 段中未设置的段自动继承[theme][theme] # 分类数据柱状、饼图、系列 chartCategoricalColors [#0969da, #1a7f37, #bf3989, #8250df, #cf222e, #bf8700, #57606a] # 连续/渐变数据热力图—— 必须恰好 10 个颜色 chartSequentialColors [#f0f6fc, #c8e1ff, #79c0ff, #58a6ff, #388bfd, #1f6feb, #1158c7, #0d419d, #0a3069, #04244a] [theme.dark] # 深色背景下更明亮的调色板 chartCategoricalColors [#58a6ff, #3fb950, #db61a2, #a371f7, #f85149, #d29922, #8b949e]数据表样式[theme] dataframeBorderColor #d0d7de dataframeHeaderBackgroundColor #f6f8fa注意数据表表头使用主文字色渲染需确保textColor在dataframeHeaderBackgroundColor上清晰可读。字体配置内置字体、Google Fonts 与自托管字体族三选一[theme] # 内置选项 font sans-serif # 或 serif / monospace # Google Fontsfamily:stylesheet_url 语法 font Inter:https://fonts.googleapis.com/css2?familyInter:wght300;400;500;600;700displayswap # 名称含空格的字体需要引号 font IBM Plex Sans:https://fonts.googleapis.com/css2?familyIBMPlexSans:wght400;500;600displayswap12 个模板全部采用font family:stylesheet_url语法加载 Google Fonts因此无需在本地存放任何字体文件开箱即用。自托管自定义字体通过[[theme.fontFaces]]表借助 Streamlit 的静态文件服务加载字体。字体文件必须放在应用的static/目录中并通过应用提供不能引用任意本地路径。在写入 config.toml 之前务必确认字体文件确实存在于 static 目录[[theme.fontFaces]] family CustomFont url app/static/CustomFont-Regular.woff2 weight 400 [[theme.fontFaces]] family CustomFont url app/static/CustomFont-Bold.woff2 weight 700 [theme] font CustomFont各属性说明family字体名、urlOTF/TTF/WOFF/WOFF2 路径、weight400、200 800或bold、stylenormal/italic/oblique、unicodeRange如U0000-00FF。fontFaces的修改需要重启服务器才能生效。标题与代码字体、字号与字重[theme] headingFont Inter:https://fonts.googleapis.com/css2?familyInter:wght600;700displayswap codeFont JetBrains Mono:https://fonts.googleapis.com/css2?familyJetBrainsMono:wght400;500displayswap baseFontSize 14 # 根字号像素默认 16 baseFontWeight 400 # 常规字重 codeFontSize 0.875rem # 相对基础字号或用 13px codeFontWeight 400 # 标题层级 h1~h6也可用单个值统一设置 headingFontSizes [32px, 24px, 20px, 16px, 14px, 12px] headingFontWeights [600, 600, 600, 500, 500, 500] linkUnderline false # 移除链接下划线观感更干净以 vscode.toml 为例它用codeFontSize 13px、baseFontSize 14复刻了 VS Code 编辑器的紧凑排版并显式定义了headingFontSizes/headingFontWeights两个 6 元素数组。圆角与边框[theme] baseRadius 8px # 所有组件none/small/medium/large/full/px/rem buttonRadius 8px # 按钮单独设置默认继承 baseRadius showWidgetBorder true # 未聚焦组件是否显示边框 showSidebarBorder true # 侧边栏与主内容之间是否显示分隔线圆角关键字none0、small4px、medium8px、large12px、full胶囊形。不同模板在圆角上风格迥异material-ui 使用baseRadius 16px、buttonRadius full表达 Material 3 的圆润感jupyter 则用2px贴近笔记本风格的锐利边缘。侧边栏独立定制[theme.sidebar]允许侧边栏与主内容区使用完全不同的配色[theme.sidebar] backgroundColor #f6f8fa secondaryBackgroundColor #eaeef2 codeBackgroundColor #eaeef2 textColor #1F2328 borderColor #d0d7de primaryColor #0969da # 侧边栏内激活元素ubuntu.toml 是侧边栏深色化的典型——主内容区为白色浅色主题侧边栏却使用#2C001E深紫底色与#FFFFFF白色文字形成强烈的品牌对比。明暗双模式[theme.light]与[theme.dark]同时定义[theme.light]和[theme.dark]后用户可在应用设置菜单中自由切换明暗模式只定义[theme]会把应用锁定为单一模式。[theme.light] primaryColor #0969da backgroundColor #ffffff secondaryBackgroundColor #f6f8fa textColor #1F2328 chartCategoricalColors [#0969da, #1a7f37, #bf3989, #8250df, #cf222e, #bf8700, #57606a] [theme.dark] primaryColor #58a6ff backgroundColor #0d1117 secondaryBackgroundColor #161b22 textColor #e6edf3 chartCategoricalColors [#58a6ff, #3fb950, #db61a2, #a371f7, #f85149, #d29922, #8b949e] [theme.light.sidebar] backgroundColor #f6f8fa [theme.dark.sidebar] backgroundColor #010409侧边栏也支持各自的明暗变体[theme.light.sidebar]/[theme.dark.sidebar]。源码层面这些配置段在 lib/streamlit/config.py 中统一注册——theme、theme.sidebar、theme.light、theme.dark及嵌套的theme.light.sidebar、theme.dark.sidebar六个段均可承载全部主题选项。在代码中感知当前主题使用st.context.theme.type让应用适配当前主题典型场景为特定图表微调颜色以提升对比度按模式切换 Logo 图片浅色模式用深色 Logo反之亦然为不自动适配主题的第三方组件补样式if st.context.theme.type dark: # 深色模式下的处理逻辑 pass设计原则对比度、配色协调与视觉层级颜色对比度遵循 WCAG AA 规范正文对比度 ≥ 4.5:1浅色主题深色文字#1F2328配浅色背景#ffffff深色主题浅色文字#e6edf3配深色背景#0d1117primaryColor必须能与白色按钮文字形成对比三种配色策略单色系单一色相、不同明度如 shadcn 的锌灰系primaryColor #18181B textColor #09090B borderColor #E4E4E7 grayColor #71717A品牌点缀中性基底 单一品牌色primaryColor #635bff # 品牌紫 backgroundColor #ffffff textColor #425466 # 中性灰互补搭配品牌主色 辅助强调色primaryColor #0969DA # 品牌蓝 textColor #1F2328 # 近黑文字 greenColor #36B37E # 成功态 redColor #DE350B # 错误态排版与视觉层级正文14–16px字重 400标题h128–40px到 h612–14px递减代码等宽字体比正文略小0.85–0.875rem字体搭配正文与标题同字体更统一也可配对互补字体如衬线标题 无衬线正文代码必须始终使用独立的等宽字体背景分层主内容最浅 → 次级元素略深 → 侧边栏独立或品牌色 → 代码块匹配次级背景完整示例从模板到自定义以 VS Code 深色主题为例theme.md 中给出了一份完整的 VS Code 深色主题配置与模板 vscode.toml 完全一致——这也是将模板作为起点、再做品牌化微调的最佳范本[theme] base dark primaryColor #0078d4 backgroundColor #1e1e1e secondaryBackgroundColor #252526 codeBackgroundColor #1e1e1e textColor #cccccc linkColor #3794ff borderColor #3c3c3c showWidgetBorder true showSidebarBorder true baseRadius 4px buttonRadius 4px font Segoe UI, Open Sans:https://fonts.googleapis.com/css2?familyOpenSans:wght300;400;500;600;700displayswap codeFont Fira Code:https://fonts.googleapis.com/css2?familyFiraCode:wght400;500displayswap codeFontSize 13px codeTextColor #d4d4d4 baseFontSize 14 baseFontWeight 400 headingFontSizes [28px, 22px, 18px, 16px, 14px, 12px] headingFontWeights [600, 600, 600, 600, 600, 600] linkUnderline false chartCategoricalColors [#0078d4, #4ec9b0, #dcdcaa, #ce9178, #c586c0, #569cd6, #6a9955] blueColor #569cd6 greenColor #6a9955 yellowColor #dcdcaa orangeColor #ce9178 violetColor #c586c0 [theme.sidebar] backgroundColor #252526 secondaryBackgroundColor #333333 codeBackgroundColor #1e1e1e borderColor #3c3c3c常见错误与排查错误类型错误示例正确做法主色太浅primaryColor #FFEB3B黄底白字不可读用更深色如#F59E0B对比度不足textColor #CCCCCC配白色背景深色文字#1F2328配浅背景背景层级颠倒backgroundColor #f6f8fa、secondaryBackgroundColor #ffffff次级背景应更深/更显著侧边栏对比度遗漏只改backgroundColor其余颜色未调深色侧边栏需同步调整secondaryBackgroundColor、textColor、borderColor等全部颜色重要约束优先使用原生主题而非自定义 CSS主题开发中有一条硬性约束——除非用户明确要求不要使用自定义 CSS 或 HTML 做主题包括st.markdown(..., unsafe_allow_htmlTrue)内嵌style、st.html()写样式块等。品牌色、背景、字体等视觉身份一律使用config.toml原生主题完成它更干净、更易维护且不会因 Streamlit 版本升级而失效。若用户明确要求 CSS例如加自定义 CSS可通过key生成可定位的类名st.button(Submit, keysubmit) # 生成类名.st-key-submit st.html(style.st-key-submit button { width: 100%; }/style)主题开发工作流与验收清单用streamlit config show查看当前版本完整的主题配置选项及说明主题选项分组在[theme]、[theme.sidebar]及明暗变体之下从模板 configs/ 复制一份到.streamlit/config.toml或设置base继承后覆盖差异项保存后重新运行应用观察实时生效效果fontFaces除外需重启依次验收按钮主色对比、表单边框与聚焦态、数据表表头、代码块、各类图表、侧边栏。相关参考主题模板 README完整主题指南 theme.md主题配置源码 lib/streamlit/config.py开发技能入口 SKILL.md设计规范 design.md【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考