microsoft / thematic

Thematic is a library and web application to aid designers in creating color palettes that unify application colors based on a desired look and feel (e.g., corporate branding) while also providing perceptually balanced color palettes and ramps for data visualization within the application. The primary goal is to provide several bindings to common application development and visualization frameworks, so theming across platforms and contexts is simple and consistent across platforms such as Power BI, Office, and web frameworks (React, Fabric, D3, Vega).

Thematic

This repository holds all of the packages for creating shareable, perceptually-balanced and tastefully complementary (hopefully!) application and data viz themes. There are adapter libraries and tools to apply themes across several environments, which will be detailed below. We briefly describe the intentions and usage of the library in a paper on visualizing workgroup collaboration.

This repository is structured as a yarn monorepo. It contains separate packages for all of the theme generation, management, and applications. To use thematic in your app, you should only need to install the relevant packages for your use case(s).

The webapp package is a guide for everything Thematic. In particular, it comprises:

• A running application for configuring theme parameters
• An example app using thematic itself, so you can see what controls and charts look like
• The ability to download theme JSON and text files that are compatible with a variety of platforms (Fluent, Office, Power BI, GIMP)
• A variety of code examples to explore showing how to use thematic in practice

This webapp is deployed as the github.io site for the repo, so you can use it directly without cloning anything yourself.

Organization

Our thematic packages are published under the @thematic scope.

These are the core Thematic libraries, see individual README.md files for greater detail:

• @thematic/color - this contains color conversion and scale generation logic. If you need functions to convert between color spaces, this is the place. This also has the color scheme compute logic that dictates how all of the color scales are generated from a few selected input parameters.
• @thematic/core - this is the main package for working with Themes. You can load them from a Theme JSON specification, then use the attributes directly in your app to apply the generated colors in a consistent way. We've used SVG notation for all of our mark properties (e.g., 'fill').
• @thematic/d3 - this package has helpers to apply the themes to viz created with d3. We provide a variety of SVG mark primitives that operate on a d3 Selection, so you can apply the theme elements using selection.call(fn, [params]) as needed.
• @thematic/fluent - helpers for applying Thematic to the Fluent UI library, including a React context provider that injects a Fluent-compatible theme instance.
• @thematic/react - helpers to bootstrap theming into React-based apps, particularly a provider and context hook (useThematic) for grabbing the theme anywhere it is needed.
• @thematic/vega - this has a helper that applies our theme spec as default configuration for Vega charts so they automatically adopt the theme.
• @thematic/webapp - this is the theme editor webapp that you can run or access at https://microsoft.github.io/thematic.

Getting Started

If you want to run locally and work on the app or any theme components, you can run the whole thing from the root folder. The web app will run using yarn start as with our typical development structure, and changes to any of the other packages will be reflected live. See the Available Scripts section below.

Publishing

Commits to main will automatically deploy to the hosted website. Pull requests should use yarn version check --interactive to create semantic versioning documents describing the impact of a PR. When a release is ready, run yarn release to publish packages to npm.

Available Scripts

In the project directory, you can run:

yarn start

Runs the app in the development mode. An available port will be selected automatically, such as 8080. Open http://localhost:8080 to view it in the browser.

The page will reload if you make edits. You will also see any lint errors in the console.

yarn test

Launches the test runner using Jest.

yarn build

Builds packages for production to their respective dist folders.

yarn clean

Cleans out the node_modules and built dist directories for every package.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

thematic's Issues

Add high contrast mode

Thematic is designed to generate subtle, somewhat pastel-like colors. Some users may prefer to turn on a high contrast mode - this should be a fairly straightforward transform, much like our color blindness modes.

Differentiate between main single chart color and scales

Right now thematic starts our nominal scales with the first color that is derives from the chosen accent. We also use this as the base for our main sequential and diverging scales. However, this is also the main color used for individual marks. This can lead to confusion because the main color used on many charts will also be incorporated in scales on categorical and continuous plots, which may lead users to believe that the accent color is more meaningful. We should reserve the accent-derived mark color as a "special" color, and not use it in our other scales.

Use clamping on color scales

Color scales use d3-scale under the hood, and can allow interpolation out of specified color endpoints. These should use the clamp option to prevent these color overflows.

Support for PowerBI?

There is no information on how this package is related to PowerBI, it would be helpful

Add github link to webapp

We have a link to MSFT privacy policy, should also include link to repo

Exported JSON should use 100 sequential colors in webapp

The JSON export currently uses the user-specified scale item count from the webapp. However, this should only apply to nominal scales. The sequential scales are always used to interpolate color with higher resolution, and should stay fixed at 100 to provide enough granularity.

Allow nominal scale creation with no size

Internally we default to 10 items for nominal scales, as this is really common. The length parameter on scale creation should be optional to allow fallback to this default.

Nominal scale items fixed to minimum of three items

The nominal compute requires an output of three items, even if less are asked for.

Issue appears with compute math here:

thematic/packages/color/src/HsluvColorLogic.ts

Line 325 in 18e2d8b

const initialHues =

Allow user to specify a color for lower pole of sequential scales

Right now we fade sequential scales from the upper color to a near-grey lower. Allowing an explicit color at the low end would give greater flexibility for matching existing dashboards or application designs.

Add secondary accent color

Many designers or corporate brands have a secondary color to feature in applications and charts.

Add semantic versioning to JSON spec

This would aid JSON consumers in aligning upgrades and expected breakages.

Allow more sequential scale endpoints

Currently we create two sequential scale options, based on the first two colors in the nominal series. An API method could be added that allows specification of any color for the upper pole, in particular cycling through further colors from the nominal scale.