[Feat] Make themes public #1482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft

huong-li-nguyen wants to merge 29 commits into main from feat/make-themes-public

...core/changelog.d/20251110_152146_90609403+huong-li-nguyen_make_themes_public.md

-Original file line number
+Diff line change
@@ -0,0 +1,48 @@
+    <!--
+    A new scriv changelog fragment.
+    Uncomment the section that is right (remove the HTML comment wrapper).
+    -->
+    ### Highlights ✨
+    - The `vizro.themes` module is now public, providing direct access to Vizro's carefully designed, colorblind-safe color system and palettes. Users can import individual colors via `vizro.themes.colors` and access pre-configured color scales through `vizro.themes.palettes`, including qualitative, sequential, and diverging palettes. See the [themes user guide](https://vizro.readthedocs.io/en/stable/pages/user-guides/themes/#vizro-colors-and-palettes) and [API reference](https://vizro.readthedocs.io/en/stable/pages/API-reference/themes/) for details. ([#1482](https://github.com/mckinsey/vizro/pull/1482))
+    <!--
+    ### Removed
+    - A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+    -->
+    <!--
+    ### Added
+    - A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+    -->
+    <!--
+    ### Changed
+    - A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+    -->
+    <!--
+    ### Deprecated
+    - A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+    -->
+    <!--
+    ### Fixed
+    - A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+    -->
+    <!--
+    ### Security
+    - A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
+    -->

vizro-core/docs/assets/user_guides/themes/colors.png

Sorry, something went wrong. Reload?

Sorry, we cannot display this file.

Sorry, this file is invalid so it cannot be displayed.

vizro-core/docs/assets/user_guides/themes/palettes.png

Sorry, something went wrong. Reload?

Sorry, we cannot display this file.

Sorry, this file is invalid so it cannot be displayed.

vizro-core/docs/pages/API-reference/themes.md

-Original file line number
+Diff line change
@@ -0,0 +1,27 @@
+    <!-- vale off -->
+    # Themes
+    The `vizro.themes` module provides `colors` and `palettes` that can be imported and used independently, without requiring a Vizro dashboard. These can be used directly in standalone Plotly charts, Jupyter notebooks, or any other visualization context. The how-to guide on [themes](../user-guides/themes.md#vizro-colors-and-palettes) contains more information.
+    ::: vizro.themes
+        options:
+          filters: ["!^_"]  # Don't show dunder methods as well as single underscore ones
+          members:
+            - colors
+            - palettes
+    **Visual reference**
+    Below is a visual reference of all available Vizro colors and palettes. Each color and palette is labeled with its access name, e.g. `colors.cyan_100` for individual colors or `palettes.sequential_cyan` for complete palettes.
+    **Colors**
+    ![Color reference](../../assets/user_guides/themes/colors.png)
+    **Palettes**
+    ![Palette reference](../../assets/user_guides/themes/palettes.png)
+    <!-- vale on -->

vizro-core/docs/pages/user-guides/assets.md

Original file line number	Diff line number	Diff line change
Expand Up		@@ -69,4 +69,4 @@ Within each of these categories, individual files are served in alphanumeric ord

		While the `assets` folder is perfect for adding your own files and [overriding specific styles via custom CSS](custom-css.md), you may also want to completely replace Vizro's default Bootstrap theme with a different one. For comprehensive theme changes, you can use the `external_stylesheets` argument to load third-party Bootstrap themes that will replace Vizro's default styling entirely.

		For detailed instructions on how to implement Bootstrap themes, see our guide on [themes](themes.md#custom-bootstrap-themes).
		For detailed instructions on how to implement Bootstrap themes, see our guide on [themes](themes.md#bootstrap-themes-in-vizro).

vizro-core/docs/pages/user-guides/themes.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,8 +1,10 @@
  
    # How to use themes

    # How to use themes and colors

    This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.

    ## Built-in Vizro themes (dark/light)

    ## Dashboard themes

    ### Built-in Vizro themes

    The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.

    @@ -57,7 +59,7 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argu
  
            [![Dark]][dark]

    ## Custom Bootstrap themes

    ### Bootstrap themes in Vizro

    If you would like to change the default Vizro styling, you have two options:

    @@ -114,9 +116,28 @@ Vizro is primarily built out of [Dash Bootstrap components](https://www.dash-boo
  
            [![BootstrapDark]][bootstrapdark]

    ## Vizro themes in plotly charts

    ### Vizro theme in Dash

    Vizro apps use the [Dash Bootstrap Components](https://www.dash-bootstrap-components.com/) library of Bootstrap components for Dash. If you have a pure Dash app and want to use Vizro's themes, you can apply Vizro's Bootstrap stylesheet in a [similar way to other Dash Bootstrap themes](https://www.dash-bootstrap-components.com/docs/themes/) through the `vizro.bootstrap` variable:

    ```python

    import vizro

    from dash import Dash

    You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:

    app = Dash(external_stylesheets=[vizro.bootstrap])

    ```

    Vizro uses some extra CSS in addition to the Bootstrap stylesheet to style some Dash components that are used in Vizro but are not part of Bootstrap (for example, [`DatePicker`][vizro.models.DatePicker] is based on [Dash Mantine Components](https://www.dash-mantine-components.com/)). If you would like your pure Dash app to look as close to Vizro as possible then you will also need [this extra CSS](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css).

    ??? note "Apply Vizro Bootstrap theme to charts and other components"

        To apply the Vizro theme to Plotly charts, refer to the above section [Vizro themes in Plotly charts](#vizro-plotly-templates). This is possible with or without Vizro Bootstrap.

        If you want to style your entire Dash app with Vizro Bootstrap so that your Plotly figures automatically match, we recommend [`dash-bootstrap-templates`](https://github.com/AnnMarieW/dash-bootstrap-templates). You can find examples in the [documentation about styling Plotly figures with a Bootstrap theme](https://hellodash.pythonanywhere.com/adding-themes/figure-templates).

    ## Vizro Plotly templates

    You can also use our templates for Plotly charts outside the dashboard. This is useful in a few contexts:

    - Creation of standalone charts to be used independently of a Vizro dashboard.

    - Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.

    @@ -125,7 +146,7 @@ You can also use our templates for plotly charts outside the dashboard. This is
  
        Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.

    Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).

    Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the Plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).

    By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.

    @@ -163,24 +184,87 @@ px.scatter_matrix(
  
    )

    ```

    ## Vizro Bootstrap for pure Dash app

    ## Vizro colors and palettes

    Vizro apps use the [Dash Bootstrap Components](https://www.dash-bootstrap-components.com/) library of Bootstrap components for Dash. If you have a pure Dash app and want to use Vizro's themes, you can apply Vizro's Bootstrap stylesheet in a [similar way to other Dash Bootstrap themes](https://www.dash-bootstrap-components.com/docs/themes/) through the `vizro.bootstrap` variable:

    The `vizro.themes` module provides direct access to Vizro's color system. Each color has been carefully selected by our design team to ensure visual consistency, professional aesthetics, and accessibility. All color palettes are colorblind-safe, making your visualizations accessible to a wider audience.

    ```python

    import vizro

    from dash import Dash

    For a complete list of available colors and palettes, refer to the [API reference for themes](../API-reference/themes.md).

    app = Dash(external_stylesheets=[vizro.bootstrap])

    ```

    ### Colors

    Vizro uses some extra CSS in addition to the Bootstrap stylesheet to style some Dash components that are used in Vizro but are not part of Bootstrap (for example, [`DatePicker`][vizro.models.DatePicker] is based on [Dash Mantine Components](https://www.dash-mantine-components.com/)). If you would like your pure Dash app to look as close to Vizro as possible then you will also need [this extra CSS](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css).

    Individual colors can be accessed through `vizro.themes.colors`. These include:

    ??? note "Apply Vizro Bootstrap theme to charts and other components"

    - **Qualitative colors**: Used for categorical data (e.g., `cyan`, `orange`, `indigo`, `red`, `teal`, `yellow`, `green`, `purple`, `pink`, `dark_green`)

    - **Sequential colors**: Organized in shades from light (100) to dark (900) for ordinal data (e.g., `cyan_100` through `cyan_900`)

    - **Special colors**: Including `white`, `black`, and `transparent`

        To apply the Vizro theme to plotly charts, refer to the above section [Vizro themes in plotly charts](#vizro-themes-in-plotly-charts). This is possible with or without Vizro Bootstrap.

    Sequential colors are available in multiple families: cyan, orange, indigo, yellow, teal, red, and grey. Each family contains 9 shades numbered from 100 (lightest) to 900 (darkest).

    !!! example "Use Vizro colors"

        === "Single color"

            ```python

            from vizro.themes import colors

            import plotly.express as px

            df = px.data.gapminder().query("year == 2007")

            fig = px.bar(df.nlargest(10, "pop"), x="country", y="pop", color_discrete_sequence=[colors.indigo])

            fig.show()

            ```

    **Color reference** ![Color reference](../../assets/user_guides/themes/colors.png)

    ### Palettes

    Pre-configured color palettes can be accessed through `vizro.themes.palettes`. These are ready-to-use color scales ideal for different data visualization needs:

    - **Qualitative palette**: Distinct colors for categorical data (`palettes.qualitative`)

    - **Sequential palettes**: Sequential color gradients for ordered data (e.g. `palettes.sequential_cyan`)

    - **Diverging palettes**: Diverging color scales for data with a meaningful midpoint (e.g. `palettes.diverging_red_cyan`)

    !!! note "Default palettes in Vizro themes"

        When using Vizro's `vizro_dark` or `vizro_light` themes in Plotly charts, the `palettes.qualitative` is automatically applied to categorical data, and the `palettes.sequential_cyan` is used for all numerical sequences. You can override these defaults by explicitly specifying `color_discrete_sequence` or `color_continuous_scale` in your Plotly chart.

    !!! example "Use Vizro palettes"

        === "Qualitative palette"

            ```python

            from vizro.themes import palettes

            import plotly.express as px

            df = px.data.iris()

            fig = px.scatter(df, x="sepal_length", y="petal_width", color="species", color_discrete_sequence=palettes.qualitative)

            fig.show()

            ```

        === "Sequential palette"

            ```python

            from vizro.themes import palettes

            import plotly.express as px

            df = px.data.tips()

            fig = px.density_heatmap(df, x="total_bill", y="tip", color_continuous_scale=palettes.sequential_red)

            fig.show()

            ```

        === "Diverging palette"

            ```python

            from vizro.themes import palettes

            import plotly.express as px

            import numpy as np

            # Create data with positive and negative values

            data = np.random.randn(20, 20)

            fig = px.imshow(data, color_continuous_scale=palettes.diverging_red_cyan, color_continuous_midpoint=0)

            fig.show()

            ```

        If you want to style your entire Dash app with Vizro Bootstrap and have your plotly figures automatically match then we recommend [`dash-bootstrap-templates`](https://github.com/AnnMarieW/dash-bootstrap-templates). You can find examples of how to do this in their [documentation on styling plotly figures with a Bootstrap theme](https://hellodash.pythonanywhere.com/adding-themes/figure-templates).

    **Palette reference** ![Palette reference](../../assets/user_guides/themes/palettes.png)

    [bootstrapdark]: ../../assets/user_guides/themes/bootstrap_dark.png

    [bootstraplight]: ../../assets/user_guides/themes/bootstrap_light.png

vizro-core/docs/pages/user-guides/visual-formatting.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -4,7 +4,7 @@ Vizro has a default styling to help users with no design experience get started.
  
    - **[Configure the layout](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.

    - **[Apply a theme](themes.md)**: Choose between a dark or light theme.

    - **[Apply themes and colors](themes.md)**: Choose between dark or light dashboard themes, use Vizro's Plotly templates for charts, and access colorblind-safe colors and palettes.

    - **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Feat] Make themes public #1482

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

[Feat] Make themes public #1482

Are you sure you want to change the base?

Uh oh!

[Feat] Make themes public #1482

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!