Saturn

This topic describes how to implement theme color and appearance. The micro applications built based on templates support these two features by default.

Overview

Theme color

Changes to the theme color apply to the color of the text button.

After you apply the theme color feature to a micro application, you can set the theme color on the SaaS No-Code Platform.

Appearance

Users can click the sun/moon icon to toggle between light and dark mode.

After you apply the light/dark toggle feature for the SaaS and micro applications, there will be an icon in the top right corner of your SaaS to toggle between light and dark mode.

To apply theme color to micro application, make sure not to set the color properties of components to fixed values. The following section will describe how to set the color properties.

Local development

Open micro.config.js. Find debuggerConfig and configure the field themeConfig. Assume that we want the theme color to be green. For more information about this field, see debuggerConfig.

module.exports = {
  debuggerConfig: {
    themeConfig: {
      primaryColor: 'green';
    }
  },
};

Restart the service. The edited theme color should take effect.

Dark mode

To preview the effect of the micro applications in dark mode, we need to edit the command yarn start to specify an environment variable.

{
  "scripts": {
    "start": "micro-script start --main", // Check out here.
    "start:proxy": "micro-script start --main --proxy",
    "build": "micro-script"
  }
}

Add environment variable:

{
  "scripts": {
    "start": "MICRO_THEME=dark micro-script start --main", // After modification
    "start:proxy": "micro-script start --main --proxy",
    "build": "micro-script"
  }
}

Then, exit the service and run yarn start. The appearance should become dark.

Principle

The theme color and appearance are implemented with the css variables and less variables of antd.

Reference

styles/

.micro-theme is made up of three files: global.less, dark.less, and light.less. These three files work for different purposes.

global.less

Declaration of global class names.

Basic code

@entry-name: light;
@galaxy-theme-entry-name: variable;

@import './@{entry-name}.less';

dark.less

less variables in dark mode.

Basic code

@import './light.less';

light.less

less variables in light mode.

Basic code

@import '~@tuya-sat/galaxy/es/style/theme/index.less';

Add custom color

To add custom colors, such as text color #666, you need to write the value in the styles file instead of the less file in the same directory. This way, the custom color can be applied to both the dark and light modes.

First, declare the less variable in light.less to #666.

@c-text-color: #666;

Since color #666 might not go well with the dark mode, we need to declare a color specific to the dark mode. Add the following code in dark.less.

@c-text-color: #fff;

To apply the less declaration to dom, declare global class names in global.less. To avoid the pollution from global variables of the main application, the class name .micro-theme is recommended.

.micro-theme-text {
  color: @c-text-color;
}

Then, add a global class name to dom. Take react as an example.

function Text() {
  return <div className="micro-theme-text">Custom Text</div>;
}

Now, the text color can be rendered differently depending on the appearance.

For example, if we want the color of the secondary text to be rgba(3, 10, 26, 0.45), we can directly use the less variable in @tuya-sat/galaxy instead of customizing the less variable. The less variable of this color is N3, so we add a global class to global.less.

.micro-theme-text {
  color: @N3;
}

If you want the color of the specific text to change based on the theme color, implement it as instructed below. Get the less variable of theme color. Find the following code snippet in @tuya-sat/galaxy/es/style/theme/color/theme/variable.less.

@M1: ~'var(--@{ant-prefix}-primary-color)'; // Theme color
@M1_1: ~'var(--@{ant-prefix}-primary-1)'; // Background color or ghost button hover
@M1_5: ~'var(--@{ant-prefix}-primary-color-hover)'; // Hover state
@M1_7: ~'var(--@{ant-prefix}-primary-color-active)'; // Click state

These are theme color-related less variables. Use @M1 to create an atom class.

.micro-theme-primary-color {
  color: @M1;
}

The color of the text to which this class is applied will change based on the theme color.

antd.less.overwrite.js

To modify the value of the less variables in antd or to achieve compatibility with different antd versions, you can edit this file. For example, in antd@5, @new-less-variable is a new less variable in variable.less. This new variable is not included in your variable-dark.less. Get the value of @new-less-variable from dark in antd and add the value to variable-dark.less, as shown below.

module.exports = {
  light: {},
  dark: {
    'new-less-variable': Specific value,
  },
};

babel.config.json

manifest.json

In manifest.json, take care of a theme color-related field.

{
  "annotations": {
    "sdf.cli:microFramework": "REACT_TS",
    "sdf.feat:colorTheme": true // Check out here.
  }
}

This property is used to enable theme color bundling. If this property does not exist, the application packaged in build and dev will not support theme color.