Skip to content

Commit

Permalink
docs: update readmes (#3315)
Browse files Browse the repository at this point in the history
  • Loading branch information
@mimarz
mimarz authored Mar 6, 2025
1 parent 5dfaabd commit 0a4d5c7
Show file tree
Hide file tree
Showing 4 changed files with 90 additions and 108 deletions.
137 changes: 49 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,94 +11,64 @@

</div>

## 📖 About Designsystemet

Designsystemet is a collection of important design elements, components and patterns that can be used to build public services.
Designsystemet is a suite of tools used to create design systems.

Our goal is to create consistent and user-friendly experiences in digital solutions for public services, making them more efficient and reliable.

## 🔗 Links

[Storybook](https://storybook.designsystemet.no/) - Preview for React components.

[Storefront](https://designsystemet.no/) - General documentation about the design system.
[Storefront](https://designsystemet.no/) - General documentation.

[Theme](https://theme.designsystemet.no/) - Theme builder.
[Theme](https://theme.designsystemet.no/) - Themebuilder.

## 📦 Packages

[`@digdir/designsystemet`](https://www.npmjs.com/package/@digdir/designsystemet) - CLI for Designsystemet.

[`@digdir/designsystemet-theme`](https://www.npmjs.com/package/@digdir/designsystemet-theme) - Themes for Designsystemet.

[`@digdir/designsystemet-css`](https://www.npmjs.com/package/@digdir/designsystemet-css) - Styling for components.
[`@digdir/designsystemet-css`](https://www.npmjs.com/package/@digdir/designsystemet-css) - CSS implementation of Designsystemet components.

[`@digdir/designsystemet-react`](https://www.npmjs.com/package/@digdir/designsystemet-react) - React implementation of Designsystemet components.

[`@digdir/designsystemet-theme`](https://www.npmjs.com/package/@digdir/designsystemet-theme) - Digdir themes for Designsystemet.



## 🚀 Get started

Follow these steps to get started with the React components.
Follow these steps to get started with Designsystemet in code.

### 1. Install the packages
### 1. Install

Depending on your needs and technology stack install the relevant packages
Install the essential packages to get started with Designsystemet:

```sh
npm i @digdir/designsystemet
npm i @digdir/designsystemet-css
npm i @digdir/designsystemet-theme
npm i @digdir/designsystemet-react
@digdir/designsystemet-css
@digdir/designsystemet-theme # or custom theme
```

#### 1.1 Custom theme
Install `@digdir/designsystemet-theme` if you need any of the Digdir themes. Uses `digdir` theme by default.

#### 1.1 Custom theme

You can create your own theme to use with the Designsystemet packages by going to our [theme-builder](https://theme.designsystemet.no/).
Create your own theme for Designsystemet by going to our [theme-builder](https://theme.designsystemet.no/).

Designsystemet theming is defined using [design-tokens](https://www.uxpin.com/studio/blog/what-are-design-tokens).
This is done so that you can use [Token Studio](https://tokens.studio/) to sync your theme in code with [Designsystemet Figma UI kit](https://www.figma.com/community/file/1322138390374166141/designsystemet-core-ui-kit), in addition to provide future flexibility.

Run `npx @digdir/designsystemet tokens build` to build CSS files for your custom theme (from the design-tokens).
Using your own built CSS theme file you can skip using the `@digdir/designsystemet-theme` package.

### 2. Font

You are free to use any font-family with the components.

The components are designed and developed using the [Inter font](https://github.com/rsms/inter) so variations might occur if a different font is used.

#### Add the Inter font (optional)

Add the `<link>` tag in `<head>`, and set `font-family` to `Inter` in your global css file.

The `font-feature-settings` adds a tail to lowercase `L`'s.

##### HTML

```html
<link
rel="stylesheet"
href="https://altinncdn.no/fonts/inter/v4/inter.css"
/>
```
Run `npx @digdir/designsystemet tokens build` to build CSS files for your custom theme (from the design-tokens) which you can then import and use with Designsystemet.

##### CSS
Using a custom theme you can skip the `@digdir/designsystemet-theme`.

```css
body {
font-family: 'Inter', sans-serif;
font-feature-settings: 'cv05' 1; /* Enable lowercase l with tail */
}
```

If you choose to install the font in a different way, remember to include the `400`, `500` and `600` font weights.
#### 1.2 React

### 3. Use a React component
Install `@digdir/designsystemet-react` if you want to use the React components.

```jsx
import '@digdir/designsystemet-theme';
import '@digdir/designsystemet-css';
import '@digdir/designsystemet-theme'; // or custom theme CSS file

import { Button } from '@digdir/designsystemet-react';

Expand All @@ -107,12 +77,12 @@ import { Button } from '@digdir/designsystemet-react';

`@digdir/designsystemet-theme` and `@digdir/designsystemet-css` only needs to be imported once.

### 4. Add TypeScript types for colors
##### Typescript

Because color names depend on which theme is being used, you have to add the following to your `tsconfig.json` to
use all your colors in the components which have a `data-color` prop:
If you are using React and Typescript you can enable editor hints on any HTML elements for `data-color` based on your theme.

#### When using `@digdir/designsystemet-theme`
This requires augmenting React's built-in types, and is therefore opt-in.
If you want this, add the following to your `tsconfig.json`:

```jsonc
{
Expand All @@ -121,60 +91,51 @@ use all your colors in the components which have a `data-color` prop:
// ...other compilerOptions
"types": [
// ...other types
"@digdir/designsystemet-theme"
"@digdir/designsystemet-theme" or "<custom-theme>/colors.d.ts",
"@digdir/designsystemet-react/react-types",
]
},
}
```

#### When using a custom theme
The CLI `designsystemet tokens build` command will output a `colors.d.ts` file to your chosen output directory.
In the example, replace `<your-path>` with the actual path you used when running the command.
### 2. Font

```jsonc
{
// ...other settings
"compilerOptions": {
// ...other compilerOptions
"types": [
// ...other types
"<your-path>/colors.d.ts"
]
},
}
```
You are free to use any font-family.

### 5. Add editor hints for data-color & data-size on HTML elements (optional)
The components are designed and developed using the [Inter font](https://github.com/rsms/inter) so variations might occur if a different font is used.

You may want editor hints for `data-color` and `data-size` attributes on HTML elements
like `<span>` or `<div>`, since these attributes can affect components nested within
these elements.
#### 2.1 Use Inter font (optional)

This requires augmenting React's built-in types, and is therefore opt-in. If you want this,
add the following to your `tsconfig.json`:
Add the `<link>` tag in `<head>`, and set `font-family` to `Inter` in your global css file.

```jsonc
{
// ...other settings
"compilerOptions": {
// ...other compilerOptions
"types": [
// ...other types
"@digdir/designsystemet-react/react-types"
]
},
}
##### HTML

```html
<link
rel="stylesheet"
href="https://altinncdn.no/fonts/inter/v4/inter.css"
/>
```

##### CSS

```css
body {
font-family: 'Inter', sans-serif;
font-feature-settings: 'cv05' 1; /* Enable lowercase l with tail */
}
```

The `font-feature-settings` adds a tail to lowercase `L`'s.
If you install the font in a different way, remember to include the `400`, `500` and `600` font weights.

## 🫶 Contributing

Learn how you can contribute to this project by reading our [Code of Conduct](./CODE_OF_CONDUCT.md) and [Contributing Guide](./CONTRIBUTING.md).

## 💪 Contributors

We are lucky to have a great group of people who help with the design system.
We are lucky to have a great group of people who have contributed to Designsystemet

<a style="margin-top: 32px; display: block;" href="https://github.com/digdir/designsystemet/graphs/contributors">
<img src="https://contrib.rocks/image?repo=digdir/designsystem" />
Expand Down
28 changes: 26 additions & 2 deletions packages/css/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,32 @@
CSS implementation of the Designsystemet components

- Uses [@layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) `ds`
- Uses `@digdir/designsystemet-theme` for predefined themes
- Uses `@digdir/designsystemet-theme` or CSS file generated from `@digdir/designsystemet tokens build` for theming
- Build your own theme on https://theme.designsystemet.no/


Read the Designsystemet [README](https://github.com/digdir/designsystemet) to get started.

## Q&A

### Tailwind

If you are using Tailwind with (Preflight)[https://tailwindcss.com/docs/preflight] make sure to load Designsystemet first.

#### v4

```css
@import url('@digdir/designsystemet-css');
@import url('tailwindcss');
```
#### v3 and older
```css
@import url('@digdir/designsystemet-css');

@layer base, ds;

@layer base {
@tailwind base;
}
@tailwind components;
@tailwind utilities;
```
9 changes: 6 additions & 3 deletions packages/react/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,13 @@

React implementation of the Designsystemet components

- Uses `@digdir/designsystemet-theme` and `@digdir/designsystemet-css` for styling.
- All components support `forwardRef`.
- Uses `@digdir/designsystemet-css` for styling.
- Uses `@digdir/designsystemet-theme` or CSS file generated from `@digdir/designsystemet tokens build` for theming.
- Build your own theme on https://theme.designsystemet.no/
- All components support `ref`.
- All components support SSR.
- Use full component name, e.g. `CardBlock` instead of `Card.Block`
- Most components extend and behave as native html-elements.
- Most components support composition and `asChild` for overriding the underlying html-element.
- SSR support.

Read the Designsystemet [README](https://github.com/digdir/designsystemet) to get started.
24 changes: 9 additions & 15 deletions packages/theme/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,29 +16,23 @@ Read the Designsystemet [README](https://github.com/digdir/designsystemet) to ge
When importing the package make sure to specify which theme.
By default `digdir` is used.

```tsx
import '@digdir/designsystemet-theme/<theme>.css';

```css
// Digdir theme
import '@digdir/designsystemet-theme';

// Altinn theme
import '@digdir/designsystemet-theme/altinn.css';
@import url('@digdir/designsystemet-theme');
// or
@import url('@digdir/designsystemet-theme/<theme>.css');
```

### CSS

This package adds Designsystemet [css variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) to your `:root {}`.
You only need to import this once in your application, preferably somewhere in your "root" html.
All variables are prefixed with `ds` and inside [@layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) `ds`.

All variables are prefixed with `ds`.
```css
@import url('@digdir/designsystemet-theme/altinn.css');

```js
import '@digdir/designsystemet-theme/altinn.css';
```
@layer "other layers", ds;

```css
div {
.example {
padding: var(--ds-size-1);
}
```
Expand Down

0 comments on commit 0a4d5c7

Please sign in to comment.