You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@superset.apache.org by "innovark37 (via GitHub)" <gi...@apache.org> on 2025/12/26 14:38:06 UTC
[I] Theming challenges - token usage and component theming limitations [superset]
innovark37 opened a new issue, #36842:
URL: https://github.com/apache/superset/issues/36842
### Bug description
# Context
While implementing custom themes for Superset I’m facing challenges that make customization more difficult than it should be, especially regarding how tokens are used across components.
# Current Problems
## Problem 1: Token Hierarchy Inconsistency
### Current Situation:
- Superset uses Ant Design GLOBAL tokens for theming
- Global tokens (`colorPrimary`, `colorText`, etc.) are properly exposed via SupersetTheme
- Component tokens (`components.Button.colorPrimary`, `components.Menu.itemColor`, etc.) are not consistently accessible
When Superset styles reference tokens, they often use global tokens where component tokens would be more appropriate.
### Example - Modal theming conflict:
```tsx
// Theme provides:
{
"token": {
"colorBgContainer": "#ffffff", // Global token ✓
},
"components": {
"Modal": {
"contentBg": "#f6f7f8", // Component token - NOT in SupersetTheme ❌
"contentPadding": "20px" // Component token - NOT in SupersetTheme ❌
}
}
}
// Superset overrides modal styles with:
const StyledModal = styled(Modal)`
${({ theme }) => css`
.ant-modal-content {
background-color: ${theme.colorBgContainer}; // Uses global, not component token
padding: 0; // Hardcoded, ignores theme.components.Modal.contentPadding
}
`}
`;
```
**Question:** Should `SupersetTheme` interface include Ant Design's component tokens?
## Problem 2: Custom Components Without Theming Support
### Example - `Toast` component:
```tsx
// Current implementation:
function Toast({ toast, onCloseToast }: ToastPresenterProps) {
...
return (
<ToastContainer
className={cx('alert', 'toast', visible && 'toast--visible', className)}
data-test="toast-container"
role="alert"
>
<div className="toast__content">
{icon}
<Interweave content={toast.text} noHtml={!toast.allowHtml} />
</div>
<Icons.CloseOutlined
iconSize="m"
className="toast__close pointer"
role="button"
tabIndex={0}
onClick={handleClosePress}
aria-label="Close"
data-test="close-button"
/>
</ToastContainer>
);
}
// Problem - can't theme via components tokens (Toast is custom, not Antd)
```
Other examples:
- Chart type selector (custom, not Antd.List)
- `PublishedLabel` component
- "View mode" control on dashboard
**Question:** Should we:
- Add custom tokens for Superset-specific components?
- Convert custom components to use Ant Design's theming system?
- Create a separate theming layer for Superset components?
## Problem 3: Style Override Conflicts
The override chain becomes unpredictable:
1. Ant Design default styles
2. Ant Design theme tokens (may or may not be exposed)
3. Superset global overrides (hardcoded CSS)
4. User's custom theme (only affects exposed tokens)
5. User's custom CSS (breaks with updates)
**Result:** Theming feels like "whack-a-mole" - fix one thing, break another.
# Proposal for Discussion
We need a systematic approach to theming. Possible directions:
### Option A: Extend SupersetTheme type
- Add tokens for Antd components
- Add tokens for custom Superset components
### Option B: Component Standardization
- Convert Superset-specific components to use Ant Design equivalent where possible
- For truly custom components, implement consistent theming pattern
- Avoid overriding Ant Design component styles unless absolutely necessary
- When styling is needed, use token-based approaches rather than hardcoded CSS
### Option C: Documentation + Tooling
- Document which components are themeable and how
- Create theme debugging tool (shows which tokens affect which elements)
- Provide migration path for users with custom themes
# Conclusion
### Current state: Theming requires deep knowledge of:
- Which tokens are exposed
- Which components override which styles
- Where hardcoded values bypass theme
- Workarounds for unthemeable components
### Desired state: Predictable, hierarchical theming where:
- All visual aspects controlled via tokens
- Component tokens > Global tokens hierarchy
- Custom components follow same pattern
- Overrides are intentional, not accidental
It would be really helpful to hear from the Superset authors and maintainers about these theming patterns. You built the system and know it best. Your thoughts could help us understand what changes would work and what might cause problems.
### Screenshots/recordings
_No response_
### Superset version
master / latest-dev
### Python version
3.9
### Node version
16
### Browser
Chrome
### Additional context
_No response_
### Checklist
- [x] I have searched Superset docs and Slack and didn't find a solution to my problem.
- [x] I have searched the GitHub issue tracker and didn't find a similar bug report.
- [ ] I have checked Superset's logs for errors and if I found a relevant Python stacktrace, I included it here as text in the "additional context" section.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org
Re: [I] Theming challenges - token usage and component theming limitations [superset]
Posted by "rusackas (via GitHub)" <gi...@apache.org>.
rusackas closed issue #36842: Theming challenges - token usage and component theming limitations
URL: https://github.com/apache/superset/issues/36842
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org
Re: [I] Theming challenges - token usage and component theming limitations [superset]
Posted by "rusackas (via GitHub)" <gi...@apache.org>.
rusackas commented on issue #36842:
URL: https://github.com/apache/superset/issues/36842#issuecomment-3745721246
Can you break this into separate issues with specific repro cases? We can tackle them one by one.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org
Re: [I] Theming challenges - token usage and component theming limitations [superset]
Posted by "dosubot[bot] (via GitHub)" <gi...@apache.org>.
dosubot[bot] commented on issue #36842:
URL: https://github.com/apache/superset/issues/36842#issuecomment-3692962713
<!-- Answer -->
You're right—Superset currently exposes only a limited set of global Ant Design tokens for theming, and does not support per-component overrides like `components.Modal` or `components.Button` in the theme config. The `SupersetTheme` interface ignores the `components` key and only applies a curated list of global tokens, which means you can't theme component internals (like Modal content padding or background) or custom components (like Toast) via tokens today. Instead, custom and many Ant Design-based components use global tokens or hardcoded values, which leads to the "whack-a-mole" theming experience you described [source](https://github.com/apache/superset/discussions/34574#discussioncomment-14018326).
For custom Superset components (Toast, chart type selector, PublishedLabel, etc.), there is currently no dedicated token system—they use styled-components and reference global theme tokens. There are no custom tokens for these components in the theme config, and no integration with Ant Design's component token system [source](https://github.com/apache/superset/blob/829e4d92d91ceae4b43b1ed3b063ffe45377799c/superset-frontend/src/components/MessageToasts/Toast.tsx).
**What’s next?**
Full support for per-component theming via tokens is planned as part of the ongoing Ant Design v5 upgrade (targeted for Superset 6.0 and later). The long-term goal is for the Superset theme object to essentially be an Ant Design ThemeConfig, augmented with a few Superset-specific tokens. This will allow you to use both global and component tokens (including for custom components, via namespacing) and will make hierarchical, predictable theming possible [source](https://github.com/apache/superset/issues/20159#issuecomment-2614589671).
**What you can do now:**
- For Ant Design components, use the allowed global tokens in your theme config. For more granular control, use targeted CSS overrides or extend Ant Design components with Emotion/styled-components [source](https://github.com/apache/superset/discussions/34574#discussioncomment-14018326).
- For custom Superset components, you’d need to add custom tokens to the theme and update the components to consume them, or standardize them to use Ant Design’s theming system once v5 support lands.
- Avoid hardcoded styles and standardize theme access across your codebase to prepare for the migration.
- Keep an eye on the Ant Design 5 migration and theming roadmap for when component tokens and better namespacing become available.
**On your proposals:**
- Extending `SupersetTheme` to include component tokens is the direction maintainers are taking, but it’s not available yet.
- Standardizing on vanilla Ant Design components and using their theming system is the preferred long-term solution.
- Improving documentation and tooling is recognized as a need, and a theme editor/debugger is on the roadmap [source](https://github.com/apache/superset/blob/master/docs/docs/configuration/theming.mdx).
If you need to theme custom components today, you’ll have to implement your own token pattern and wire it up, or use CSS overrides. The future state will be much more flexible and predictable once the Ant Design v5 migration is complete.
<!-- Dosu Comment Footer -->
*To reply, just mention [@dosu](https://go.dosu.dev/dosubot).*
---
<sup>How did I do? [Good](https://app.dosu.dev/response-feedback/31cf5b04-8b7e-4cca-88d6-569f430b801c?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/31cf5b04-8b7e-4cca-88d6-569f430b801c?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/31cf5b04-8b7e-4cca-88d6-569f430b801c?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/31cf5b04-8b7e-4cca-88d6-569f430b801c?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/31cf5b04-8b7e-4cca-88d6-569f430b801c?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/31cf5b04-8b7e-4cca-88d6-569f430b801c?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/31cf5b04-8b7e-4cca-88d6-569f430b801c?feedback_type=other)</sup>
[](https://app.dosu.dev/a28d3c7e-a9d3-459e-9fb6-3a6f9ff4f357/ask?utm_source=github) [](https://cursor.com/link/prompt?text=You%27re%20right%E2%80%94Superset%20currently%20exposes%20only%20a%20limited%20set%20of%20global%20Ant%20Design%20tokens%20for%20theming%2C%20and%20does%20not%20support%20per-component%20overrides%20like%20%60components.Modal%60%20or%20%60components.Button%60%20in%20the%20theme%20config.%20The%20%60SupersetTheme%60%20interface%20ignores%20the%20%60components%60%20key%20and%20only%20applies%20a%20curated%20list%20of%20global%20tokens%2C%20which%20means%20you%20can%27t%20theme%20component%20internals%20%28like%20Modal%20content%20padding%20or%20background%29%20or%20custom%20components%20%28like%20Toast%29%20via%20tokens%20today.%20Instead%2C%20custom%20and%20many%20Ant%20Design-based%20components%20use%20global%20tokens%20or%20hardcoded%20values%2C%2
0which%20leads%20to%20the%20%22whack-a-mole%22%20theming%20experience%20you%20described%20%5Bsource%5D%28https%3A//github.com/apache/superset/discussions/34574%23discussioncomment-14018326%29.%0A%0AFor%20custom%20Superset%20components%20%28Toast%2C%20chart%20type%20selector%2C%20PublishedLabel%2C%20etc.%29%2C%20there%20is%20currently%20no%20dedicated%20token%20system%E2%80%94they%20use%20styled-components%20and%20reference%20global%20theme%20tokens.%20There%20are%20no%20custom%20tokens%20for%20these%20components%20in%20the%20theme%20config%2C%20and%20no%20integration%20with%20Ant%20Design%27s%20component%20token%20system%20%5Bsource%5D%28https%3A//github.com/apache/superset/blob/829e4d92d91ceae4b43b1ed3b063ffe45377799c/superset-frontend/src/components/MessageToasts/Toast.tsx%29.%0A%0A%2A%2AWhat%E2%80%99s%20next%3F%2A%2A%20%20%0AFull%20support%20for%20per-component%20theming%20via%20tokens%20is%20planned%20as%20part%20of%20the%20ongoing%20Ant%20Design%20v5%20upgrade%20%28targeted%20f
or%20Superset%206.0%20and%20later%29.%20The%20long-term%20goal%20is%20for%20the%20Superset%20theme%20object%20to%20essentially%20be%20an%20Ant%20Design%20ThemeConfig%2C%20augmented%20with%20a%20few%20Superset-specific%20tokens.%20This%20will%20allow%20you%20to%20use%20both%20global%20and%20component%20tokens%20%28including%20for%20custom%20components%2C%20via%20namespacing%29%20and%20will%20make%20hierarchical%2C%20predictable%20theming%20possible%20%5Bsource%5D%28https%3A//github.com/apache/superset/issues/20159%23issuecomment-2614589671%29.%0A%0A%2A%2AWhat%20you%20can%20do%20now%3A%2A%2A%20%20%0A-%20For%20Ant%20Design%20components%2C%20use%20the%20allowed%20global%20tokens%20in%20your%20theme%20config.%20For%20more%20granular%20control%2C%20use%20targeted%20CSS%20overrides%20or%20extend%20Ant%20Design%20components%20with%20Emotion/styled-components%20%5Bsource%5D%28https%3A//github.com/apache/superset/discussions/34574%23discussioncomment-14018326%29.%0A-%20For%20custom%20Superset
%20components%2C%20you%E2%80%99d%20need%20to%20add%20custom%20tokens%20to%20the%20theme%20and%20update%20the%20components%20to%20consume%20them%2C%20or%20standardize%20them%20to%20use%20Ant%20Design%E2%80%99s%20theming%20system%20once%20v5%20support%20lands.%0A-%20Avoid%20hardcoded%20styles%20and%20standardize%20theme%20access%20across%20your%20codebase%20to%20prepare%20for%20the%20migration.%0A-%20Keep%20an%20eye%20on%20the%20Ant%20Design%205%20migration%20and%20theming%20roadmap%20for%20when%20component%20tokens%20and%20better%20namespacing%20become%20available.%0A%0A%2A%2AOn%20your%20proposals%3A%2A%2A%20%20%0A-%20Extending%20%60SupersetTheme%60%20to%20include%20component%20tokens%20is%20the%20direction%20maintainers%20are%20taking%2C%20but%20it%E2%80%99s%20not%20available%20yet.%0A-%20Standardizing%20on%20vanilla%20Ant%20Design%20components%20and%20using%20their%20theming%20system%20is%20the%20preferred%20long-term%20solution.%0A-%20Improving%20documentation%20and%20tooling%20is
%20recognized%20as%20a%20need%2C%20and%20a%20theme%20editor/debugger%20is%20on%20the%20roadmap%20%5Bsource%5D%28https%3A//github.com/apache/superset/blob/master/docs/docs/configuration/theming.mdx%29.%0A%0AIf%20you%20need%20to%20theme%20custom%20components%20today%2C%20you%E2%80%99ll%20have%20to%20implement%20your%20own%20token%20pattern%20and%20wire%20it%20up%2C%20or%20use%20CSS%20overrides.%20The%20future%20state%20will%20be%20much%20more%20flexible%20and%20predictable%20once%20the%20Ant%20Design%20v5%20migration%20is%20complete.) [](https://go.dosu.dev/discord-bot) [](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/apache/superset/issues/36842)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org
Re: [I] Theming challenges - token usage and component theming limitations [superset]
Posted by "rusackas (via GitHub)" <gi...@apache.org>.
rusackas commented on issue #36842:
URL: https://github.com/apache/superset/issues/36842#issuecomment-4748730922
Heya! This bundles several distinct theming limitations together. Could you split them into separate issues with specific repro cases so we can tackle them one by one? Closing this umbrella issue for now, as we try to thin the herd, even if the result here grows the issue count even more :P
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org