https://norwegianredcross.github.io/DesignSystem/storybook/
Welcome to the Røde Kors Design System! This repository contains a library of reusable UI components built with React, specifically tailored for Norwegian Red Cross digital projects.
It's developed leveraging the foundational components from Digdir's Designsystemet. This approach ensures a unified and recognizable visual identity across all applications for the Norwegian Red Cross. The system is pre-configured with the official Røde Kors brand theme, which is provided via a dedicated design token package.
The primary goal is to ensure brand consistency, improve development efficiency, and maintain high accessibility standards across all Røde Kors applications.
Storybook serves as the interactive documentation and development environment for viewing and testing these components.
To use the Røde Kors Design System in your Next.js (or any React) application:
Install the necessary npm packages for your project. You will need three packages: the component library itself (rk-designsystem), the base styles from Digdir, and the Røde Kors theme package (rk-design-tokens).
# npm
npm install rk-designsystem @digdir/designsystemet-css rk-design-tokens
# yarn
yarn add rk-designsystem @digdir/designsystemet-css rk-design-tokens
# pnpm
pnpm add rk-designsystem @digdir/designsystemet-css rk-design-tokensNote: You do not need to install @digdir/designsystemet-react separately, as all required components are included within the rk-designsystem package.
For the components to be styled correctly, you must import the stylesheets at the highest level of your application, for instance, in your layout.tsx (for Next.js App Router) or _app.tsx (for Next.js Pages Router).
Crucial Order: It's vital that the base stylesheet (@digdir/designsystemet-css) is loaded before the Røde Kors theme file (rk-design-tokens). This ensures our theme's tokens can correctly override the default values.
import './globals.css'; // Your own global styles (if any)
import '@digdir/designsystemet-css/index.css'; // Base stylesheet for components
import 'rk-design-tokens/design-tokens-build/brand-1.css'; // Røde Kors theme
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}import '../styles/globals.css'; // Your own global styles (if any)
import '@digdir/designsystemet-css/index.css'; // Base stylesheet for components
import 'rk-design-tokens/design-tokens-build/theme.css'; // Røde Kors theme
import type { AppProps } from 'next/app';
function MyApp({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />;
}
export default MyApp;Once the stylesheets are included, you can start importing and using components in your project. All components you need are available directly from the rk-designsystem package.
Import components directly from the rk-designsystem package:
import { Alert } from 'rk-designsystem'; // Import necessary components
function MyComponent() {
return (
<>
<Alert variant="info" onClose={() => console.log('Alert closed!')}>
This is an informational message from the Red Cross Design System.
</Alert>
</>
);
}Here's an example of how to use multiple Alert components from the Røde Kors Design System within a Next.js page/component:
'use client'; // Remember 'use client' for interactive components in App Router
import React from 'react';
import { Alert } from 'rk-designsystem'; // Import the components you need
export default function Home() {
return (
<div className="container mx-auto p-8">
<h1 className="text-3xl font-bold mb-8">
Røde Kors Design System Example
</h1>
<section>
<h2 className="text-2xl font-semibold mb-4">Alerts</h2>
{/* Røde Kors Design System Alerts */}
<Alert variant="success">
<p>
Welcome! This message is styled with the official Røde Kors theme.
</p>
</Alert>
<Alert variant="warning" className="mt-4">
<p>
Important information using the official Røde Kors theme.
</p>
</Alert>
</section>
{/* More Røde Kors components can be added here as needed */}
</div>
);
}The appearance of all components is fully controlled by the rk-design-tokens package. To receive any visual updates to the brand theme (like a new primary color), simply update the package to its latest version:
npm update rk-design-tokensThis guide provides a set of standards and best practices for creating new components. Following these guidelines ensures that our component library remains consistent, accessible, and easy to maintain.
Follow these steps to get the local development environment running. All commands should be run from the root of the project.
# 1. Install dependencies
pnpm i
# 2. Build all packages
pnpm build
# 3. Start the local Storybook server
pnpm storybookEvery component we build should adhere to these core principles:
- Accessibility (A11y): Components must be usable by everyone, including people with disabilities. This means proper ARIA attributes, keyboard navigation, and semantic HTML.
- Reusability: Components should be generic enough to be used in multiple contexts without modification.
- Consistency: Components should follow our established design tokens (colors, spacing, typography) and have a consistent API and structure.
- Documentation: Every component must be documented in Storybook to make it discoverable and easy for other developers to use.
Before you start coding, determine what kind of component you need. Most of our needs fall into one of three categories:
-
Wrapped Component (Simple):
- What it is: A component that directly wraps and re-exports a component from
@digdir/designsystemet-reactwith no modifications. - When to use: When the base Digdir component meets our needs perfectly, but we want to include it in our own library for a consistent import source.
- Example: The
Buttonscomponent is a perfect example of this.
- What it is: A component that directly wraps and re-exports a component from
-
Wrapped Component (with Style Overrides):
- What it is: A wrapped Digdir component where we apply custom CSS to tweak its appearance to better match Røde Kors's specific design language.
- When to use: When a Digdir component is functionally correct but needs visual adjustments (e.g., different icons, border radius, padding).
- Example: The
Alertcomponent, which usescomposesin its CSS to inherit base styles and then applies its own overrides.
-
Custom Component (from Scratch):
- What it is: A completely new component built when no existing Digdir component meets our requirements.
- When to use: For unique UI patterns or functionality not covered by the base library.
- Example: The
DateInputcomponent is a custom component with its own state, logic, and styling.
To maintain consistency, every new component should follow this file structure. Create a new folder under src/components/ with the component's PascalCase name.
src/
└── components/
└── MyNewComponent/
├── index.ts // Public API - exports the component and props
├── MyNewComponent.tsx // The React component logic and JSX
├── MyNewComponent.stories.tsx // Storybook stories for documentation
├── styles.module.css // Scoped CSS (only for custom components)
└── MyNewComponent.test.tsx // (Optional but Recommended) Unit tests
- TypeScript First: All components must be written in TypeScript. Define a
Propsinterface for your component, extending from the base HTML element or Digdir component props if applicable. - Forward Refs: Always use
React.forwardRefto allow parent components to get arefto the underlying DOM element. - Accessibility is Mandatory:
- Use semantic HTML (
<button>,<label>,<nav>). - Ensure all interactive elements are keyboard-focusable and operable.
- Provide
aria-labelfor icon-only buttons or elements where the text label is not visible. - Use
aria-invalid,aria-describedby, etc., to communicate state to assistive technologies.
- Use semantic HTML (
- Controlled vs. Uncontrolled: If your component has state (like an input), it should support both controlled (
value+onChange) and uncontrolled (defaultValue) patterns. - Props Naming: Use
data-*attributes for styling variants (e.g.,data-size,data-color) to align with the patterns in our existing components.
- CSS Modules: For custom components, all styles must be placed in a
styles.module.cssfile. This scopes class names locally and prevents global style conflicts. - Design Tokens: Always use our design system tokens (
var(--ds-...)) for colors, spacing, fonts, etc. Do not use hardcoded values (e.g.,#FFF,16px). - Overriding Wrapped Components: For wrapped components, use a standard CSS file. Use the
@layerandcomposeskeywords to extend base Digdir styles without increasing CSS specificity unnecessarily.
Your Storybook file is the official documentation. It must be clear and comprehensive.
metaObject: Define the component's title, component reference, andtags: ['autodocs']to enable automatic documentation.argTypes: Document every single prop. Provide adescription,controltype (e.g.,select,boolean,text), andoptionsif applicable. This powers the interactive controls in Storybook.- Create Multiple Stories: Create a separate story for each key state and variant of your component (e.g.,
Default,Disabled,WithError,WithIcon).
-
Create a Branch: Pull the latest changes from the
mainbranch and create a new feature branch:git checkout -b feat/my-new-component. -
Open a Draft PR: As soon as you start, open a draft pull request on GitHub. This prevents duplicate work and allows others to see what you're working on.
-
Commit Your Changes: As you work, make small, logical commits.
-
Ready for Review: When development is complete and all automated checks are passing, mark the PR as "Ready for review" and request a review from the design system maintainers.