thematic/README.md

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 opencode@microsoft.com with any additional questions or comments.