README
Telia Styleguide
This is a React component library of the Atomic Design components found in the Telia Styleguide. This is a living styleguide, showing the components which should be used in Telia Norway's web applications to achieve a common look & feel, and therefore user experience.
- The styleguide can be found on the web.
- The React component library can be found on NPM as a JavaScript module.
Usage
Install the styleguide package:
npm install --save @telia/styleguide
Import the CSS styles. Use
import '@telia/styleguide/dist/index.css';
for the full CSS orimport '@telia/styleguide/dist/components.css';
if you only need the components themselves without the global styles. If you are using the business components, you needimport '@telia/styleguide/business.css';
. If you only use the business components, you don't need the other CSS files.Import and use a component:
import { Button } from '@telia/styleguide';
and<Button text="Default button" />
.
Development
Getting started
- Install dependencies:
npm install
- Start Storybook:
npm run storybook
- Open a browser at
http://localhost:6006/
Adding a new component
All new components should employ TypeScript.
Add a folder called
YourComponentName
insrc/atoms|molecules|organisms
In the new folder, create a new file
YourComponentName.tsx
React component fileWrite thorough docblocks above the function itself and all the parameters/props.
Optionally add React PropTypes as well if the component is to be used in a non-TypeScript environment.
Export the new component from
src/index.ts
.If the new component requires CSS, add a new file
YourComponentName.pcss
alongside the TSX source file. This will be included automatically.Add a new storybook file
YourComponentName.stories.tsx
with detailed examples of the new component in use (look at the existing components for examples).
CSS classes
All classes should be prefixed with "telia
"
We also use the BEM-pattern: block__elements--modifiers
- Component elements should be preceded with "
__
"- Example:
telia-[component-name]__header
- Example:
- Component modifiers should be preceded with "
--
"- Example: "
telia-[component-name]--compact
"
- Example: "
Add new icons
NOTE: This section needs revision
Copy the new icons into the folder
assets/icons/dropHereNewIcons
Build the library:
npm run icons
. Note that the original icons are optimized and moved from the drop here folder. The files that cannot be processed successfully remain in the drop folderRun
npm run build
,npm run storybook
and check if your icon appears here: http://localhost:6006/?path=/docs/component-library-atoms-icon--default
Consuming the local, development styleguide in other local web apps
NOTE: This section was written for the old styleguide and needs revision. Maybe something about npm link?
- Install
http-server
globally with npm (https://www.npmjs.com/package/http-server) - Go to you local styleguide folder in your terminal and type
http-server ./ --cors
- Include stylesheet in your project
<link rel="stylesheet" href="http://local-styleguide:8080/css/bundle.components.css">
To publish locally
- Local test:
npm run publish:local-test
Deployment
We use Github Actions for build and deploy and the pipelines can be found at https://github.com/TeliaSoneraNorge/styleguide/actions.
If you do not have access here and think you should have, post in the #styleguide
channel on slack.
When a new feature/branch is merged to master, a new build of Storybook is automatically deployed.
TODO: Add step in pipeline to post message to the Slack channel #styleguide-deploy
to verify when the deploy has completed.
React component library package
After the deploy of the website is complete you can in the "Publish to npm" action trigger a version
update. You can choose between major, minor and patch version update. See VERSIONS.md
for more
details on which to choose.
Remember to write a description in VERSIONS.md
if it is a noteworthy change.
Other
Useful links
Versioning
Notify all "breaking changes" or major changes in the #styleguide Slack Channel and update VERSIONS.md.