mistercrunch commented on issue #20159: URL: https://github.com/apache/superset/issues/20159#issuecomment-2614589671
Reporting here that I made great progress on https://github.com/apache/superset/pull/31590, and having tackled a path forward at the app-level, solving a lot of the core issues and solutions identified in this SIP. Now I'm starting to think more about some of the challenges around theming data visualizations and their respective plugins with a minimal set of tokens that cover most use cases. Me and GPT came up with a bit of a propose that expands from this SIP and the work in https://github.com/apache/superset/pull/31590 to try and tackle viz-specific use cases around theming. Pasting the output here: ### Proposal: Introducing Data Visualization Theming Tokens for Superset #### **Challenges** 1. **Ant Design as a Generic App Theming System** - Ant Design (AntD) provides an excellent foundation for app theming but lacks semantics specific to data visualization. While Superset relies on AntD for app-wide theming, there’s currently no support for visualization-specific themability. 2. **Intricacies of Data Visualization Theming** - Theming data visualizations is inherently complex. Different visualization libraries (e.g., ECharts, D3, Vega) offer overlapping yet nuanced theming capabilities for elements like axes, legends, tooltips, and markers. - It’s difficult to identify truly universal theming concepts that transcend library-specific implementations. 3. **Configurability vs. Implementation Feasibility** - Allowing for endless customization creates implementation challenges for plugin authors. Instead, we must focus on identifying the critical 10-20% of theming tokens that satisfy 80-90% of theming needs. 4. **Best Practices for Data Visualization** - A balanced approach to visualization styling is needed: - **Blend with the App**: Visualizations should harmonize with the host application’s styling, inheriting key design elements like font families and colors. - **Stand Out**: At the same time, visualizations should “pop” as distinct, interactive components. For example, using a distinct font family for visualizations can signal that interactions within the chart may differ from those in the host application. --- #### **Proposal: Universal Data Visualization Tokens** To address these challenges, we propose introducing a small, universal set of `viz*` tokens that: 1. **Provide a Prefix for Clarity** - All visualization-specific tokens will use the `viz` prefix to differentiate them from generic AntD tokens. 2. **Limit the Token Set to a Manageable Scope** - Focus on a core set of tokens that: - Are universally relevant to most visualizations. - Balance configurability with feasibility for plugin authors. ##### **Proposed Token List** | Token Name | Description | Default Coupling with AntD Token | |----------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------| | `vizFontFamily` | Font family for all text within visualizations. | `fontFamily` | | `vizAxisColor` | Color for axis lines, ticks, and labels. | `colorTextSecondary` | | `vizAxisFontSize` | Font size for axis labels. | `fontSizeBase` | | `vizGridColor` | Color for grid lines (muted to make visualizations pop). | `colorBorderSecondary` | | `vizLegendFontSize` | Font size for legend text. | `fontSizeBase` | | `vizLegendFontColor` | Font color for legend text. | `colorText` | | `vizMarkerFontSize` | Font size for marker/annotation text. | `fontSizeBase` | | `vizMarkerFontColor` | Font color for marker/annotation text. | `colorText` | | `vizColorPalette` | Primary color palette for visualization series (e.g., bar colors, line colors). | `colorPalette` | | `vizColorBgContainer`| Background color for visualizations. | `colorBgContainer` | --- #### **How Tokens Couple with AntD** - By default, `viz*` tokens inherit values from existing AntD tokens to ensure visual consistency. - Plugin authors are expected to use these tokens instead of directly coupling with AntD, allowing themer overrides for visualization-specific needs. - Example: - `vizAxisColor` defaults to `colorTextSecondary`, but a themer can override `vizAxisColor` to make axes more prominent. --- ### Not Supported Out of the Box by Design To maintain simplicity, clarity, and practicality, certain theming features are intentionally excluded from the proposed `viz*` token set: 1. **X-Axis and Y-Axis (and Z-Axis) Divergence** - Styling for X, Y, and Z axes cannot diverge. While some libraries allow separate configurations for each axis, this can lead to inconsistency, confusion, and poor visual practices. Managing divergent styles would also result in a matrix explosion of properties, making it impractical to support. 2. **Global Font-Family (`vizFontFamily`)** - The `vizFontFamily` token applies globally to all visualization text. Targeting different fonts for specific areas (e.g., axis labels, tooltips, or markers) is not supported to prevent unnecessary complexity and maintain a cohesive visual hierarchy. 3. **Tooltip Theming** - Tooltip styling aligns with the host application's look and feel by directly using AntD tokens for tooltips (e.g., `colorBgElevated`, `colorTextInverse`). No `viz*` tokens are introduced for tooltip-specific configurations. 4. **Titles within Visualizations** - Superset handles titling outside the visualization plugin (e.g., at the dashboard or chart metadata level). To avoid duplication, in-visualization titling is considered out of scope. 5. **Long-Tail Customizations** - Specific, detailed configurations (e.g., per-series styling, legend background colors, animation controls) are not included in the universal token set. These can be addressed via the `defaultVizOptions` mechanism, which allows library-specific configurations where applicable. By focusing on universal, high-impact theming tokens, this approach ensures clarity and avoids over-complication, while still allowing edge cases to be handled through targeted configuration. #### **Documentation for Plugin Authors** 1. **Use `viz*` Tokens** - Replace direct usage of AntD tokens with `viz*` tokens for any visualization-related styling. 2. **Maintain Consistency** - Avoid introducing visualization-library-specific tokens unless absolutely necessary. 3. **Respect Defaults** - Allow `viz*` tokens to fall back to their AntD counterparts if not explicitly overridden. --- #### **Supporting the Long Tail** For edge cases and specific needs, the theming framework could allow library-specific configuration objects. For example: ```js const theme = Theme(seed) theme.setEchartOptionsOverrides(echartOptionsOverrides) ``` In this case, the `Partial<echartOptions>` object would be merged into the `echartOptions` somewhere in the plugin's rendering pipeline. So somehwere in the plugin there's a `generateEchartOptionsFromSupersetTheme` function, and a way to `mergeEchartOptionsOverrides` from the theme object. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
