@telia/styleguide

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 or import '@telia/styleguide/dist/components.css'; if you only need the components themselves without the global styles. If you are using the business components, you need import '@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

Prerequisities

Node v16 should be used.

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 in src/atoms|molecules|organisms

• In the new folder, create a new file YourComponentName.tsx React component file

• Write 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
• Component modifiers should be preceded with "--"
  • Example: "telia-[component-name]--compact"

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 folder

• Run 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

Use npm link to test a modified Telia Norge Styleguide component locally in telia-no-min-side project.

#  in Telia Norge Styleguide directory
npm run build:icons
npm run build
cd dist
npm link

# in your project directory
npm link @telia/styleguide
npm start

Now whenever you change anything in Telia Norge Styleguide, rerun npm run build and your project should pick up the changes.

When you're finished, unlink the Telia Norge Styleguide:

# in your project directory
npm unlink --no-save @telia/styleguide
npm install

# in Telia Norge Styleguide directory
npm unlink -g

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

• The styleguide
• Telia Company full guidelines
• Telia Company styleguide

Versioning

Notify all "breaking changes" or major changes in the #styleguide Slack Channel and update VERSIONS.md..