This page will provide best practices for some issues encountered when using atomic style libraries such as TailwindCSS with Semi.
These problems are often encountered when other component libraries are used with Tailwind, but Semi provides official solutions. It is recommended to follow the instructions in this article to configure the project correctly.
Note
Semi does not rely on any third-party style libraries and can run without installing Tailwind. If you do not use atomic libraries such as Tailwind, please close this page directly.
1. Solve the problem of style override priority
Problem performance
There is no effect or component library style exception when using some atomic classes in components.
Cause Analysis
When using Tailwind, Tailwind modifies the dom style through className, which also affects the Semi component library. At the same time, Tailwind enables Preflight by default to reset the browser's default style.
At this time, depending on the configuration of your project and the import of the entry, there are two possibilities:
Tailwind is introduced before Semi style, and Semi has higher priority
Semi style was introduced before Tailwind, and Tailwind has a higher priority.
If it is 1, it will appear that when Tailwind adds certain atomic classes, if the component style has defined a certain css attribute, the priority of the atomic class is lower than that of Semi, and the atomic class becomes invalid.
For example, under the premise of 1, setting padding on the Button component will cause failure.
If it is 2, because Tailwind has a higher priority, its Preflight overwriting the browser's default style will also override Semi's style.
For example, under the premise of 2, the background color of the light Button will be overwritten as transparent, causing the style to behave abnormally.
Solution
No matter which side of Tailwind or the component library has higher priority, problems will occur, so the solution lies in correctly handling the relationship between the priority of Preflight and the atomic classes required by users in the Tailwind style relative to the priority of the component library.
1. Enable Semi plugin (>= 2.59.0)
yarn add -D @douyinfe/semi-webpack-plugin
2. In the configuration file of the project (webpack.config.js, etc.), import the Semi webpack plug-in and enable cssLayer (users who use non-webpack builds, please refer to the principle to wrap the semi css layer by yourself)
new SemiWebpackPlugin({
cssLayer:true,
/* ...options */
});
3. Modify Tailwind entry configuration
The CSS of Tailwind entry is usually a file containing the following three lines
And import the above modified file at the top of the project's JS entry file (i.e. App.tsx or index.js). (Usually a Tailwind project has already processed the import of the above files, just put the import statement before all import statements)
Compatible with lower version browsers
CSS Layer requires a browser version higher than Chromium 99 (compatibility table), if you The website requires a lower version browser to access and needs to add CSS Layer Polyfill. Please refer to this Polyfill's PostCSS plugin documentation
Principle
Through the CSS Layer feature, priority setting of styles from different sources is achieved.
After enabling the plugin, all Semi styles will be wrapped by @layer {xxxx}. In addition, we also manually set the layers of various types of Tailwind styles in the project.
In addition, we configured the priority order of various Layers:
@layer tailwind-base,semi,components,utils;
The meaning of the above CSS is that base (including Preflight) has the lowest priority, followed by Semi. The atomic class styles set by the user (padding-[xxx], etc.) have the highest priority, which can solve the above problems.
2. Solve the problem of using Semi Token in Tailwind atomic class (optional)
Tailwind supports users to configure their own Token to implement themes. At the same time, Semi also provides its own theme solution and corresponding Token
If you want to use Semi Token directly in the project, for example, set the text color of a span to --semi-color-text-0 to automatically switch between light and dark colors to be consistent with the theme, you need to set the css color separately: var(--semi-color-text-0), very inconvenient.
Semi provides Tailwind's theme configuration file, which is used to map Semi's Token to atomic Token. For the above requirements, you can directly set text-semi-color-text-0 for span.
Just configure the following content in the Tailwind configuration (i.e. tainwind.config.js):