Elvis CSS library
Elvis CSS library offers classes and variables for styling components as well other styling utilities like
layout and typography classes.
📚 How to use
Read our get started guide at design.elvia.io to get started
using our CSS library and components.
Usage example:
<button class="e-btn">Button</button>
💻 Development
Read about the
philosophy behind Elvis here.
Technology
- We use SCSS for our classes. With ABEM as our
class naming convention.
- We use Percy for visual regression testing for our CSS library.
- We use Figma for sketching the components. Use
Elvia Figma
to get sketches of how the component should be styled and work.
Create or change the CSS library
NOTE! The web project will not work properly before the
setup in main project has been done.
Rules
- Follow the
naming conventions
for all classes.
- Update Percy tests for the classes at
packages/elvis/percy/components
.
How Percy works - Follow the
versioning guidelines
for publishing to NPM.
- For colors always use our color tokens. If something custom is needed define a new CSS variable at root with
the naming convention: --e-componentName-color-purpose':
@include helpers.custom-light-theme-tokens {
--e-tag-color-neutral-background: var(--e-light-theme-black);
}
@include helpers.custom-dark-theme-tokens('tag') {
--e-tag-color-neutral-background: var(--e-dark-theme-white);
}
.e-tag {
background: var(--e-tag-color-neutral-background);
}
Good to know
-
Figma: Use the
Elvia Figma
to get sketches of how the component should be styled and work.
-
Deprecating outdated classes:
- To deprecate an Elvis class, add it to the
deprecated-classes.json
file located at
packages/elvis/.internal/deprecated-classes.json
. Do not include the period prefix in the deprecated
class name. - Set the sunset dates to a date at least 6 months in the future and then every 6th month remove the classes
that are deprecated from the deprecated file as well as the actual classes and code dependencies.
Do
not remove the class from the library before the sunset date.
- To get started quickly, copy an existing entry and change the values. Place new additions as the first
element within the JSON object.
- Bump major and list the classes in the changelog when removing the classes.
"e-deprecated-class": {
"deprecateChildren": true,
"requiredAncestor": "e-deprecated-class-ancestor",
"version": "2.0.0",
"replacement": {
"name": "e-better-replacement",
"type": "class",
"documentation": "https://design.elvia.io/e-better-replacement"
},
"sunset": "March 2023"
}
Glossary:
-
deprecateChildren
: If true, all other Elvis classes that include the name specified above will be
deprecated (optional).
-
requiredAncestor
: If specified, the requiredAncestor class will only cause a warning if the specified
'requiredAncestor' class is present as an ancestor in the DOM (optional).
-
sunset
: An approximate date of when classes will be removed from Elvis (optional).
Lastly, remember to remove any Percy tests for the deprecated class. They can be found in
packages/elvis/percy
.
Step 0 - Before you begin
- Make sure you have done the
main project setup.
- Navigate to
packages/elvis
Step 1 - Running project
- Run
yarn build
to build the classes. - Run
yarn start
to start/watch for changes while developing - Test your changes by running the main project at the same
time and using the classes in the doc-pages in
packages/web
. E.g.
packages/web/src/app/doc-pages/components/button-doc
Step 2 - Create the classes / component
- In
packages/elvis/src
choose between the components
, utilities
and variables
folders depending on
what you are creating. - Create your classes, utilities, or variables with the rules explained over in mind.
Step 3 - Document the classes
The classes should be documented in the packages/web
folder so that users of the design system can find
information on how to use them.
- Navigate to
packages/web/src/app/doc-pages/components
and find the component you want to add documentation
to or create a new module (like the ones existing already).
Step 4 - Pull request and publish
NOTE! You will need to set up two-factor authentication with NPM to manually publish your changes.
Elvia NPM.
-
Update version: When doing updates to Elvis remember to always update the version in
packages/elvis/package.json
.
-
Document: the changes / removal or new classes in the CHANGELOG.json
file as well as at the correct
documentation-page. E.g. packages/web/src/app/doc-pages/components/button-doc
. Example of an update in
CHANGELOG.json:
{
"version": "8.3.1",
"date": "April 20, 2022",
"changelog": [
{
"type": "breaking_changes",
"changes": ["Fixed a class not working properly."],
"fixes": [
"Change something to fix something",
"Another step"
],
"components": [{ "displayName": "Table", "url": "https://design.elvia.io/components/table" }],
"pages": []
}
]
},
The type should be "breaking_changes", "bug_fix", "new_feature" or "patch". Changes describes what changes
have been done, while fixes describes steps the user has to do to fix their code to be up to date.
Components links to all related components, and pages links to all related pages.
-
Commit & push: to your branch.
-
Pull request: Create a pull request with all the changes at the
Design system Github repo.
-
Preview: Netlify will generate a preview link when the pull request is created. The link can be used to
send a preview of the changes e.g. to designers or other developers. Find the link at the bottom of the
checkpoint-list in the pull request.
-
Merge branch: When the branch has been approved by one other member of the team, merge the changes into
master.
-
Publish to NPM: Whenever something is merged or pushed to master, any packages with a new version in
their package.json
will be automatically published to NPM. If you for some reason need to manually
publish a version (e.g. publishing a beta-version) this can be done by navigating to packages/elvis
and
running the command npm publish --otp=<OTP-code>
.