Here are some guidelines we gathered related to this project that you may be interested in following if you build your own library.
Stylable enables you to author a component library, that can be themed, and easily consumed and styled, by other Stylable projects.
Stylable is the styling, CSS side of working with components. For the Stylable CSS to be fully useful, it must integrate with a component library from another source, for example React.
As a best practice, we recommend following this folder structure:
- a project stylesheet describing the project CSS API
- a folder for each component with its stylable stylesheet
src/themesfolder contains the relevant theme files.
Although you may think the project file should be at the
src level, we recommend you to create the
project.st.css file at the same level as your components because there are many links between this file and your component files.
As a first step, create a project commons stylesheet named
project.st.css in the
src/components directory. This exposes the API for the project.
It is recommended to leave the project's CSS rulesets empty with no declarations. These should be defined in a theme file.
Your components should be as easy to style as possible. We recommend following these guidelines when planning:
- Expose a good style API and its custom states.
- The component API should contain the minimum styling required for the component to function. For example some components may require layout.
- The effect of CSS combinations is not always easy to understood and styles are generally less tested, therefore, we recommend adding comments that explain the reason for unclear CSS.
- Reusable vars should be declared outside of the component. The component can use vars for common values that are less likely to be override-able.
- Use component variants and shared classes from the project file (
More best practices for themable components can be found in the Stylable component best practices guide.
In the following code, you can see a component described with:
- 2 colors used from project
- 1 shared class
The Stylable library can include multiple theme files that render a different look and feel per theme. A theme imports the
project.st.css file as a theme base to override variables, variants and classes from the library.
In the following code, you can see a theme file customizing the library:
- CSS for
- CSS for
Read more about using themes in theme an application.