@synergy-design-system/styles
v1.4.0
Published
Utility classes and helpers for applications using the Synergy Design System
Downloads
147
Readme
@synergy-design-system/styles
This package provides easy to use standalone helper classes based on the Synergy Design Tokens.
The included styles use CSS features supported by the latest two versions of all major browsers (as defined by browserslist) and is actively linted and tested against those targets.
1. Installation
Please make sure to install the package as a dependency:
npm install --save @synergy-design-system/styles
# Install the required design tokens
# (only needed if you do not install peerDeps automatically)
npm install --save @synergy-design-system/tokens
2. Loading the provided stylesheets
2.1 Loading all styles (Recommended)
To load all provided css classes at once, just include the default export into your application.
It contains all styles found in the src
directory.
<!DOCTYPE html>
<head>
<link rel="stylesheet" href="/node_modules/@synergy-design-system/styles/dist/index.css" />
</head>
<body>
</body>
</html>
We also provide a default export that points to the created dist/index.css
file.
This will be picked up and served when using a bundler (e.g. webpack or vite).
For this to work, import the module directly in your project like this.
import "@synergy-design-system/styles";
2.2 Loading single modules
It is also possible to load only parts of the provided css files.
For a list of available modules, please have a look at the available modules section below.
<!DOCTYPE html>
<head>
<!-- Loading typography only -->
<link rel="stylesheet" href="/node_modules/@synergy-design-system/styles/dist/typography.css" />
</head>
<body>
</body>
</html>
// Loading typography only
import "@synergy-design-system/styles/typography.css";
3. Available modules
- link.css
- tables.css
- table-cell.css
- table.css
- typography.css
- body.css
- heading.css
- weight.css
Development
Building the styles
This package makes use of postcss
for creating a unified bundle for easier consumption in applications. Please run pnpm build
in the root of this package to recreate the bundle file dist/index.css
.
How it works
- The build will walk through the
src
directory and process all files namedindex.css
. It automatically moves those files to the rootdist
directory, with the name of the folder it resides in.src/typography/index.css
will automatically becomedist/typography.css
. - All css files not named
index.css
will get copied over to thedist
directory to make them available in the bundle.src/typography/body.css
will get copied todist/typography/body.css
, howeverdist/typography/index.css
will get renamed todist/typography.css
for easier inclusion.
Creating new modules
- Create a new folder
src/[MODULE_NAME]
. - Create a new file
src/[MODULE_NAME]/index.css
. - Add CSS statements to your liking. Hint: You may also split your code into multiple css files residing in the
src/[MODULE_NAME]
folder. Make sure to import them into yoursrc/[MODULE_NAME]/index.css
file to make them part of the build. - Add js doc comments to your code to create controls for storybook automatically. This can be done by creating comments, as seen below.
- Run
pnpm build
. You should now see the a new filedist/[MODULE_NAME].css
that holds all your previous code, as well as your created submodules (if you have splitted your code into multiple files).
Bonus: Documenting your module with css comments
When adding comments to your modules, please add a list of all variants of your module to your css file. Comments like this will take care that storybooks documentation is automatically updated:
/**
* The "variant" syn-fieldset takes care that two classes will exist in documentation. The first variant value will be the selected one:
* - syn-fieldset-small and
* - syn-fieldset-large
* @variant {small | large } syn-fieldset
*
* The "variant" syn-shadow takes care that 4 classes will exist in documentation. There will be no default value selected via the NO_DEFAULT option:
* @variant { NO_DEFAULT | bottom | top | start | end } syn-shadow
*
* The "boolean" syn-boolean-false will display as a boolean value in storybook with 'false' as default value
* @variant syn-boolean-false This value will also be available as a class.
*
* The "boolean" syn-boolean-true will display as a boolean value in storybook with 'true' as default value
* @boolean { true } syn-boolean-true This value will also be available as a class.
*
*/