Maintenance mode
Gaia design system (@gaiads/telia-react-component-library) is now in maintenance mode, and DS team focuses fully on Global DS.
What does this mean in practice:
- New features - No new features such as new components or significant changes to existing ones will be done to the React library as they will be delivered as Web Components.
- Fixing - bugs and other abnormal functionality
Only when they are deemed critical (see below).
- Usage - guidance for components
Simple guidance can be provided to teams using the components, but no complex cases or onboarding are supported.
- Helping - with a contribution of improvements/fixes to existing complex components
Only when they are deemed critical (see below).
- Definition of Critical -
When a feature is missing or contains bugs that break existing systems and no workaround is available, they are considered critical. This is decided on a case-by-case basis by the Core Team.
You are free to ask questions and help each other in #design-system Slack channel! Please let us know if you have any questions about this.
~ DS team
Telia React Component Library
This is a react component library and living styleguide, showing the components which should be used in Telia Finland's web applications to achieve common look & feel, and therefore user experience.
How to use
- Install component library as a dependency
- Add component library styles to your bundle
- Done!
Installation
You can install component library as any node package
npm install @gaiads/telia-react-component-library --save
Alternative installation with Github
In case the artifactory for some reason is a no go for you, you can install the library using Github.
npm install --save https://{USER}:{ACCESS_TOKEN}@github.com/TeliaSoneraFinland/telia-react-component-library/archive/{VERSION}.tar.gz
Read how to create an access token
importing components from component library in your project
Component library supports three types of module format
- CommonJS
- ES modules
- Universal Module definition (UMD)
If you need to import UMD modules you need to target the UMD file explicity
import { button } from '@gaiads/telia-react-component-library/build/index.umd.js'
In case your project is typscript codebase currently UMD build doesn't support typescript.
Exporting multiple type declaration files are not supported in npm package so far and because of this
typescript will give error that corresponding type declaration file is missing.
To fix this issue do the following
- Create a new folder called
types
in same path as file which is importing component from component library - Create a file
index.umd.d.ts
in the types
folder
Add following contents inside the file:
declare module '@gaiads/telia-react-component-library/build/index.umd.js';
Add component library styles in your project
You should add the styles into your bundle. Usually this is done by importing them in your index.js
like so:
import '@gaiads/telia-react-component-library/build/index.css';
Typescript support
The component library supports Typescript by exposing the d.ts file with component type declarations. Projects don't have to make any settings for taking this feature in use, but it works automatically for typescript projects.
Design tokens support
The component library supports design tokens by exposing the css and scss variables files with. These files can be imported from build/tokens directory.
import '@gaiads/telia-react-component-library/build/tokens/css/_variables.css';
.my-class {
background-color: var(--gaia-color-black);
}
import '@gaiads/telia-react-component-library/build/tokens/scss/_variables.scss';
z-index support
With growing numnber of UI elements it is challenging to manage z-index. Defining set of rules for z-index makes them more manageable. Z index token can be used as follows
import '@gaiads/telia-react-component-library/build/tokens/css/_variables.css';
.my-class {
z-index: var(--gaia-z-index-default);
}
import '@gaiads/telia-react-component-library/build/tokens/scss/_variables.scss';
.my-class {
z-index: $gaia-z-index-default;
}
It is also possible to import z-index scss function file and use this function with z-index name.
import '@gaiads/telia-react-component-library/build/styles/zindex.scss';
.my-class {
z-index: z('default');
}
Development
Getting started
- Fork the repository
- Clone your own fork
- Set upstream repository with
git remote add upstream git@github.com:TeliaSoneraFinland/telia-react-component-library.git
- When pulling changes/rebasing from upstream, remember to use
git pull --rebase upstream master
- After this you should update your remote fork with
git push --force-with-lease origin master
- Install dependencies with
npm install
- Run storybook with
npm run storybook
- Run tests in terminal with
npm run test
- Access storybook in URL
http://localhost:6007
Viewing designs in Zeplin
- Register to Zeplin
- Ask designers to add your Zeplin account into the Telia design projects
Coding conventions
It's very important that you read the coding conventions which have been documented in here. See also our code review checklist
Creating new component
To create new files, you can use the 'plop' script included in devDependencies.
npm run plop
You can also manually add the files. Make sure to follow coding conventions of the repo!
- Create a directory called
YourComponentName
in src/components
- Inside the directory, create two files for your component:
YourComponentName.test.js
and YourComponentName.js
- Create also
YourComponentName.stories.js
file under src/styleguide
- In case you need custom CSS, create file called
YourComponentName.module.scss
to same directory - Update component types accordingly in
@gaiads/telia-react-component-library.d.ts
file
Developing the component
When developing, make sure to:
- Have 100% unit test coverage
- Add PropTypes to your component with documentation and write a storybook story for the component
- Expose your component in
src/index.js
and add test to src/index.test.js
- Update component types accordingly in
@gaiads/telia-react-component-library.d.ts
file
Getting your component to the library
- Push your changes to your own fork
- Create descriptive pull request to the upstream repository
- Wait until code and design reviews are done and make changes if asked to
Developing your project with component library (npm linking)
For this, we have to utilize npm link
command. You have two options: either use the static build of the project or develop against running component library. When using the running component library you can test changes in command library's end and see the changes in our application immediately.
Remember that this is only for development and when you are deploying your own project then you should always use npm install
to get the latest version of component library
Develop with running component library
- Go to directory of your local copy of component library
- Run
sudo npm link ../<your_project_name>/node_modules/react
- Run
npm run start
- Open another terminal and go to your project where you use
@gaiads/telia-react-component-library
as a dependency - Run
npm link @gaiads/telia-react-component-library
- Component library is now running in different terminal and you can run your application in another. When you make changes in the component library the changes will update automatically on your application
- In case you get an error, you could try to run
npm install npm-link-shared
and npm-link-shared ./node_modules/@gaiads/telia-react-component-library/node_modules . react
from your project directory. npm-link-shared will enable your project to use react version from the telia-react-component.library package in order to avoid errors related to different React version. - NOTE: Running
npm i
will break the linking. - NOTE: If the changes are not shown, restarting the VS code should help.
Develop with static build
- Go to directory of component library
- Run
npm link
- Run
npm run build
- Go to the project where you use
@gaiads/telia-react-component-library
as a dependency - Run
npm link @gaiads/telia-react-component-library
- Now you can start making changes to the component library and after running
npm run build
it should be automatically updated in your project as well - In case you get an error, you could try to run
npm install npm-link-shared
and npm-link-shared ./node_modules/@gaiads/telia-react-component-library/node_modules . react
from your project directory. npm-link-shared will enable your project to use react version from the telia-react-component.library pacakge in order to avoid errors related to different React version. - NOTE: Running
npm i
will break the linking. - NOTE: If the changes are not shown, restarting the VS code should help.
Versioning
Component library uses Semantic versioning.
Artifactory
Setting up artifactory for component library development purpose
Run npm login
and when the command line asks, enter your deveo credentials and suiting email. After this you'll be logged in to artifactory and you are able to make actions such publishing into the artifactory.
Setting up artifactory for your project
Include .npmrc file into the root of your project. File should include:
registry=https://artifactory.verso.sonera.fi:443/api/npm/npm-registry-virtual/
always-auth = true
Then login to the artifactory by running npm login
. When the command line asks, enter your deveo credentials and suiting email. After this you'll be logged in to artifactory and you are able to install the dependencies.
Remember to include the credentials also to your CI!
How to create a Release
Prerequisites for release
- In order to create change log from github create github personal token. Create a file configToken.js in the root directory and copy/paste contents from configToken-template.js into configToken.js then add personal token in configToken.js
- Check that all the changes which should be included into the release are merged into the master branch
- Choose an increment based on Semantic versioning.
Release preparations:
- On Slack #gaia-core-team channel create a team editable document for release notes
- Copy & paste previous' content for placefolder
- Ping team members to modify and contribute to document
- Make sure all PRs related to today's release are merged into master
- Before starting release, checkout to the master branch and make sure, that you have taken the latest changes to your local master from origin/master
- Selecting between patch, minor and major releases:
- PATCH version when you make backwards compatible bug fixes.
- Run
npm run release-prep
to patch a version
- MINOR version when you add functionality in a backwards compatible manner.
- If you are releasing a minor version, run
SEMVER=minor npm run release-prep
- MAJOR version when you make incompatible API changes.
- If you are releasing a major version, run
SEMVER=major npm run release-prep
- Modify text to categorize changes in packages/telia-react-component-library/CHANGELOG_LATEST.md and prepend the text in packages/telia-react-component-library/CHANGELOG.md
- Run visual test
npm run visual-test
- Observe the breaking tests and update those if necessary.
- Commit changes to the
@gaiads/telia-react-component-library
repository with commit message Release preparations for <VERSION>
, for example Release preparations for v0.0.11
- After commiting, push your local release branch to GitHub.
- Run
git push --set-upstream origin release/<VERSION>
- For example
git push --set-upstream origin release/v6.14.1
- In GitHub create pull request out of
release/v<VERSION>
branch. - Assign someone to review and approve your pull request.
- ONLY AFTER pull request was approved merge it into origin master branch.
- MAKE SURE that after merging, you follow the releasing steps for GitHub.
Releasing in GitHub
WARNING
!!Before going further make sure that you pull request is approved by your collegue and merged into master!!
Once your release preparations are in the master go to the GitHub UI.
- Select Releases tab (usually on the right side of GitHub repository page under "About") and choose "Draft a new release"
- Tag number should be the version number which you just updated to the
package.json
- Release title is the version number
- Copy/Paste contents of CHANGELOG_LATEST.md in Write section
- Since we are still in pre-release phase remember to tick "This is a pre-release" checkbox
- Hit the "Publish release". This will create a tag commit
- Go to the master branch and fetch that commit
git fetch
and rebase git rebase origin/master
, with your local master
branch - Rename .npmrc-template file to .npmrc and Run
npm publish
in order to publish the package into the artifactory - Go to artifactory, login and use quick search with
@gaiads/telia-react-component-library
keyword to check if the latest version was indeed published.
- It should appear on the list quite soon. If not, you might have only read access to Artifactory. It will not throw any errors in terminal, if you have only read access.
- Make sure that designers and developers have modified and added their release notes to the document created at the very beginning of these release preparations.
- Notify everyone in the #design-system slack channel about the release with a brief release notes summary.
- Flush the cards in Jira by pressing Release button in full board kanban view specifying the release version
Adding new Icons
- Add new icon svg file into shared/icons folder
- Make sure your icon filename has no spaces nor umlauts
- Run
npm run process-icons
in order to add icon into allowed icons list. Parser takes the name from the icon's file name - Rollup optimizes icons automatically by running them through svgr. It removes the fill tags and compresses file. So you don't have to do anything additional optimization, just run
npm run build
or npm run storybook
- Create a new build and publish the new package, in order to get the icons available everywhere
Importing variables from the library
You can use colors, baseline, breakpoints, spacing and scalableTypography sass helpers.
Using Colors
Import colors from the library and refer them with color(color_name).
@import '@gaiads/telia-react-component-library/build/styles/colors.scss';
.myview {
color: color(purple500);
background-color: color(gray100);
}
Using breakpoints
Import breakpoint from the library and refer them with breakpoint name such "md".
@import '@gaiads/telia-react-component-library/build/styles/breakpoints.scss';
.myview {
width: 100%;
@include from('md') {
width: 80%
}
}
Using baseline
Import baseline from the library and refer it as $baseline or $typographyBaseline.
@import '@gaiads/telia-react-component-library/build/styles/baseline.scss';
.myview {
height: 10 * $baseline;
font-size: 3 * $typographyBaseline;
}
Using scalableTypography
Import fluidTypographyMixins from the library and define the font size scaling @include fluid-type(minSize, maxSize)
;
.
@import '@gaiads/telia-react-component-library/build/styles/fluidTypographyMixins.scss';
.myview {
@include fluid-type(10px, 20px);
}