@lansforsakringar/components

Länsförsäkringar Components

Accessible and feature rich front-end framework for Länsförsäkringar web development.

Design system →      Storybook website →

Table of contents

• Getting started
• Usage
• Documentation
• Bugs and feature requests
• Contributing
• Making a release

Getting started

To install Components in your project, you will need to configure your environment for GitHub Packages.

First, authenticate npm with GitHub Packages. To do that, generate a personal access token which you use as your password. Make sure to give the token access rights to both repo and read:packages scopes.

npm login --scope=@lf-digitala-kanaler --registry=https://npm.pkg.github.com

Add a .npmrc file in your project root folder.

@lf-digitala-kanaler:registry=https://npm.pkg.github.com

Install the package as you normally would.

npm install @lf-digitala-kanaler/lfui-components

Usage

You have two alternatives for getting started with the framework; either by importing the source files into a SCSS build, or by adding the precompiled files to your HTML document.

Source alternative

Importing the source code gives you access to the full SCSS suit including our variables and mixins – increasing your flexibility when extending the framework with your own styles and layouts.

Import LFUI.scss at the very beginning of your main SCSS file:

@import "@lf-digitala-kanaler/lfui-components/src/scss/LFUI.scss";

The JavaScript bundle can be imported as a whole.

import '@lf-digitala-kanaler/lfui-components'

Some components are also exported, both as part of the bundle as well as individual modules.

// Extract from bundle
import { select } from '@lf-digitala-kanaler/lfui-components'

// Import only the specific component
import select from '@lf-digitala-kanaler/lfui-components/select'

Compiled alternative

In the /dist folder provided, you will find: lfui.css, lfui.js and a fonts directory. These files can be used as-is. Simply add jQuery along with lfui.js and lfui.css to your HTML document.

Fonts

Web fonts are included as an external dependency, so the font urls will need to be rebased and the source files copied to the build directory. A tool such as postcss-url or the Webpack file-loader can help you with that.

See the fonts documentation on loading and preloading techniques for optimal performance and accessibility.

Icons

Icons are not part of this package. Please see the Länsförsäkringar Icons for documentation on how to install and use.

Favicon

See the designated Länsförsäkringar Favicon repo for all the assets and documentation you might need.

Documentation

Each component is documented, with examples, on the LFDS website. This is our go-to for documentation.

Along with that, because our code is based on Bootstrap, the documentation from Bootstrap version four and five does provide a good overview of how components are structured, along with listing all the available utility classes.

Bugs and feature requests

If you with to report a bug or submit a feature request, feel free to open an issue. The more information that you provide, the better.

Contributing

We rely on Storybook for serving and testing during development.

After cloning this repo, install the dependencies and start the server.

npm install
npm start

Along with starting Storybook, npm start will also rebuild and refresh the page as you work, allowing for quick changes and previews.

Project structure

.
├── .storybook                # Storybook config
├── dist
│  ├── docs                   # Component examples used in LFDS
│  ├── lfui.css               # CSS bundle
│  ├── lfui.js                # JS bundle
│  └── fonts                  # Font files (referenced in CSS bundle)
└── src
    ├── data
    ├── docs
    │   ├── *
    │   │   ├── *.html        # HTML example
    │   │   │── *.js          # JS used only for the example markup
    │   │   └── *.stories.js  # Storybook config
    │   │   ...
    │   └── index.js          # Exporting JS/CSS that's needed for examples in LFDS
    ├── js
    │   │── index.js          # Entry point for JS (sans CSS)
    │   └── components        # Component JS
    ├── scss                  # CSS for components
    │   └── LFUI.scss         # Entry point for CSS
    └── index.js              # Entry point for JS/CSS bundles

Working with branches and pull requests

The latest and stable version is always in the main branch. New features and patches are then added through dedicated branches and pull requests.

When working on a new feature, begin by creating a new branch from main. After finishing your work, squash merge main into your branch and then create a pull request.

Please document the changes that you make in the pull request, along with potential changes to existing classes or variables that should be added to a migration guide later on.

Linting

The project uses standard and stylelint. There are no automated tests beyond that.

npm test

Making a release

• Update (componentStatus.json)[src/data/componentsStatus.json] with changes that have been made to the respective components in this release. This information will be visible on LFDS later on.
• Bump the version number npm version <major|minor|patch>
• Push the changes to GitHub
• Create a new release from the tag list on Github and add your release notes. Note that this will also be visible to the public. Take extra care to document any breaking changes.
  • Tag version example: v5.0.0
  • Release Title example: Components 5.0.0
• Creating a new release will automatically publish a new package version to GitHub Packages.
• Update the version of Components that LFDS depends on by updating package.json in the LFDS repo.
• If any components have been added or changed, now is the time to document that in LFDS. See the LFDS repository readme.
• Deploy the new version of LFDS.

Deploying the Storybook website

When creating a release, a Github Action will automatically deploy the changes to our Storybook Github page.

Github actions secrets

Since the package depends on private GitHub packages, a private access token is set up to authenticate the GitHub actions. The PACKAGE_TOKEN secret needs to be updated when expired.