Theme Specification

A Theemo theme is an NPM package with a bit of metadata to recognize a theme. That helps bundlers to load them and runtime to manage features at runtime.

You can use theemo build to generate the required spec. Then publish the package to a registry or use it as part of your monorepo.

Specification

A Theemo theme needs minimal information in package.json:

1. Add theemo-theme to keywords.
2. Add theemo field with information about your theme

theemo Field

The theemo field contains information about:

• name of your theme
• file the CSS file for your theme
• features available to your theme

Features

An array of features available to either the product integrating the theme or even for end-users.

Features are ColorSchemeFeature | ColorContrastFeature | MotionFeature | CustomFeature and can be summarized as:

interface Feature {
  name: string;
  options: string[];
  defaultOption?: string;
  browserFeature?: 'color-scheme' | 'color-contrast' | 'motion';
}

Browser Features

Browsers have bulit-in mechanics to support a couple of features in which they act as agents or principals for the browser or operating system. Thus they are supported by the theemo ThemeManager (see Vanilla Example).

Browser Features are ColorSchemeFeature, ColorContrastFeature and MotionFeature and must be denoted by the browserFeature field for theemo to recognize.

Here is an example to define a color scheme feature:

{
  "name": "color-scheme",
  "browserFeature": "color-scheme",
  "options": [
    "light",
    "dark"
  ]
}

Custom Features

Other features not supported by special browser mechanics are custom features, for example different font sizes or density you may offer to your end users.

Here is an example for density:

{
  "name": "density",
  "options": [
    "compact",
    "comfortable",
    "spacious"
  ],
  "defaultOption": "comfortable"
}

Example

Here is a minimal package example, with sync and build:* scripts present

{
  "name": "package-name",
  "keywords": [
    "theemo-theme"
  ],
  "theemo": {
    "name": "theemo",
    "file": "dist/theemo.css",
    "features": [
      {
        "name": "color-scheme",
        "browserFeature": "color-scheme",
        "options": [
          "light",
          "dark"
        ]
      },
      {
        "name": "density",
        "options": [
          "compact",
          "comfortable",
          "spacious"
        ],
        "defaultOption": "comfortable"
      }
    ],
  },
  "scripts": {
    "sync": "theemo sync",
    "build:css": "style-dictionary build",
    "build:theme": "theemo build"
  },
  "devDependencies": {
    "@theemo/cli": "^1.0.0",
    "@theemo/figma": "^1.0.0",
    "@theemo/build": "^1.0.0",
    "@theemo/sync": "^1.0.0",
    "@theemo/style-dictionary": "^1.0.0",
    "@theemo/tokens": "^1.0.0",
    "style-dictionary": "^5.0.0"
  }
}