@lansforsakringar/core-components

v2.0.0

Published

6 days ago

Länsförsäkringar Design System Core Components

0High
0Medium
0Low

web-components Länsforsakringar design-system components

LFDS Core Components

LFDS is Länsförsäkringar's design system core components distributed as composable Web Components.

Scope of this README

This README describes this package only:

how to install and use @lansforsakringar/core-components
how to include required styles from @lansforsakringar/core-css
package-local tooling (bundler plugins/CLI)

For monorepo-level setup, use root README.md. For core package release/versioning operations, use packages/core/README.md.

Breaking changes and migrations

High-level migration summary: BREAKING_CHANGES_v3.md
Web component rename mapping: docs/migrations/web-components-rename.md
Rename codemod: scripts/migration/rename-web-components.js

Note: API naming for components follows lfds-* / Lfds*. Some tooling identifiers in examples (for example plugin/CLI names) may still use legacy lfui naming for compatibility.

Using Components

Bundling

Install

The design system is published on npm. It has a peer dependency on lit, so you need to install both packages. This avoids shipping duplicate Lit versions in the same application and lets you control the exact Lit version in your app.

npm install @lansforsakringar/core-css @lansforsakringar/core-components lit

Import the component bundle once in your application entrypoint:

import '@lansforsakringar/core-components'

Styles

You also need to import the global styles from @lansforsakringar/core-css. These include shared CSS variables, tokens, and fonts. With build tools like Vite or Webpack, import the CSS in your JavaScript/TypeScript entrypoint:

import '@lansforsakringar/core-css/index.css'

Or in your CSS (for example with PostCSS):

@import '@lansforsakringar/core-css/index.css';

If you are not using a build tool, see Script/Link Tag or CLI.

React

The package includes a React wrapper build. To use it, install @lit/react in addition to the base dependencies:

npm install @lansforsakringar/core-css @lansforsakringar/core-components lit @lit/react

import { LfdsButton } from '@lansforsakringar/core-components/react'

export default function App() {
  return (
    <LfdsButton onLfClick={() => console.log('clicked')}>Click me</LfdsButton>
  )
}

Bundler plugins

The package provides plugins for popular bundlers to copy and serve component assets.

Vite

The Vite plugin copies assets to assetDir relative to Vite's output directory. During development, assets are served as if they were local public files.

// vite.config.js
import { lfui } from '@lansforsakringar/core-components/vite'

export default {
  plugins: [lfui({ assetDir: 'lfui-assets' })]
}

Webpack

The Webpack plugin copies assets to assetDir relative to Webpack's output directory.

// webpack.config.js
const LFUIPlugin = require('@lansforsakringar/core-components/webpack')

module.exports = {
  plugins: [new LFUIPlugin({ assetDir: 'lfui-assets' })]
}

On build, assets are copied to the configured assetDir in the bundler output.

Self-hosted

If you are not using a bundler or want to serve the assets in a different way, you can copy them to your web server and serve them yourself, see CLI.

Script/Link Tag

If you are not using a bundler, export the distributable files first (for example to public/lfui) and then reference them directly in HTML:

lfui export --out public/lfui

<!doctype html>
<html>
  <head>
    <script type="module" src="/lfui/main.js"></script>
    <link rel="stylesheet" href="/lfui/main.css" />
  </head>
  <body>
    <lfds-button>Click me</lfds-button>
  </body>
</html>

CLI

This package ships with a CLI for common tasks such as exporting assets.

Export

The export command copies the distributable Lit build (main.js, main.css, related assets, and types) to a directory of your choice.

$ lfui export --out dist/lfui

Assuming the dist folder is publicly accessible on your server, reference the files like this:

<!doctype html>
<html>
  <head>
    <script type="module" src="/lfui/main.js"></script>
    <link rel="stylesheet" href="/lfui/main.css" />
  </head>
  <body>
    <lfds-button>Click me</lfds-button>
  </body>
</html>

Authoring Components in This Package

If you are building or modifying components here, start with these docs in the repo root:

docs/components-authoring.md — How we structure, style, and wire components (what and why).
docs/your-first-component.md — Step-by-step tutorial with full code.
docs/component-checklist.md — Minimal PR-ready checklist.