https://norwegianredcross.github.io/DesignSystem/#
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.
The design system includes the following components:
| Component | Description |
|---|---|
| Alert | Display important messages and notifications |
| Avatar | Represent users or entities with images/initials |
| Badge | Show status indicators or counts |
| Breadcrumbs | Navigation showing current location in hierarchy |
| Button | Interactive buttons for actions |
| Card | Container for grouping related content |
| Carousel | Image gallery with navigation |
| Checkbox | Multi-select form inputs |
| Chip | Compact interactive elements for filtering |
| DateInput | Text input for dates with Norwegian formatting |
| DatePicker | Visual calendar for date selection |
| Details | Expandable/collapsible content sections |
| Dialog | Modal and non-modal dialog windows |
| Divider | Visual separator between content |
| Dropdown | Dropdown menus and action lists |
| ErrorSummary | Summary of form validation errors |
| Field | Form field wrapper with label and validation |
| Fieldset | Group related form fields |
| Header | Global application header |
| Input | Basic text input field |
| Link | Navigation links |
| List | Ordered and unordered lists |
| Pagination | Navigate between pages of content |
| Popover | Contextual overlays |
| Radio | Single-select form inputs |
| Search | Search input with button |
| Select | Dropdown selection |
| Skeleton | Loading placeholder |
| SkipLink | Accessibility skip navigation |
| Spinner | Loading indicator |
| Suggestion | Searchable select with autocomplete |
| Switch | Toggle on/off settings |
| Table | Structured data display |
| Tabs | Tabbed content navigation |
| Tag | Static labels for categorization |
| Textarea | Multi-line text input |
| Textfield | Text input with label and validation |
| ToggleGroup | Grouped toggle buttons |
| Tooltip | Hover/focus information overlays |
npm install rk-designsystemFor Next.js projects, use next/font for optimal font loading:
// src/app/layout.tsx (App Router)
import '@digdir/designsystemet-css/index.css';
import 'rk-design-tokens/design-tokens-build/theme.css';
import { Source_Sans_3 } from 'next/font/google';
const sourceSans3 = Source_Sans_3({
subsets: ['latin'],
weight: ['200', '300', '400', '500', '600', '700', '800', '900'],
style: ['normal', 'italic'],
});
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="no">
<body className={sourceSans3.className}>{children}</body>
</html>
);
}Important: Use className, NOT variable. The variable option only creates a CSS custom property without actually applying the font.
import { Button, Alert } from 'rk-designsystem';
export default function Page() {
return (
<Alert variant="success">
Welcome to Røde Kors Design System!
</Alert>
);
}For non-Next.js projects, use the combined styles import:
npm install rk-designsystem// main.tsx or index.tsx
import 'rk-designsystem/styles';This single import includes base styles, theme, and loads the font via Google Fonts.
import { Button, Alert } from 'rk-designsystem';
function App() {
return (
<Alert variant="success">
Welcome to Røde Kors Design System!
</Alert>
);
}// pages/_app.tsx
import '@digdir/designsystemet-css/index.css';
import 'rk-design-tokens/design-tokens-build/theme.css';
import { Source_Sans_3 } from 'next/font/google';
import type { AppProps } from 'next/app';
const sourceSans3 = Source_Sans_3({
subsets: ['latin'],
weight: ['200', '300', '400', '500', '600', '700', '800', '900'],
style: ['normal', 'italic'],
});
export default function App({ Component, pageProps }: AppProps) {
return (
<main className={sourceSans3.className}>
<Component {...pageProps} />
</main>
);
}For AI assistants (Claude Code, Cursor, etc.) working with this design system, an AI Design System Guide is available:
Direct URL:
https://norwegianredcross.github.io/DesignSystem/storybook/AI_DESIGN_SYSTEM_GUIDE.md
# macOS/Linux/Git Bash
curl -o AI_DESIGN_SYSTEM_GUIDE.md https://norwegianredcross.github.io/DesignSystem/storybook/AI_DESIGN_SYSTEM_GUIDE.md
# Windows PowerShell
Invoke-WebRequest -Uri "https://norwegianredcross.github.io/DesignSystem/storybook/AI_DESIGN_SYSTEM_GUIDE.md" -OutFile "AI_DESIGN_SYSTEM_GUIDE.md"- Component Metadata: https://norwegianredcross.github.io/DesignSystem/storybook/metadata.json
- AI Context Manifest: https://norwegianredcross.github.io/DesignSystem/storybook/ai-context.manifest.json
- Design Tokens: https://norwegianredcross.github.io/design-tokens/theme.css
- GitHub Repository: https://github.com/norwegianredcross/DesignSystem
The Storybook publish step ships three downstream-facing artifacts together:
AI_DESIGN_SYSTEM_GUIDE.mdmetadata.jsonai-context.manifest.json
The guide remains the main human-readable reference. The manifest is additive and exists so downstream repos can refresh local rules and detect drift without scraping the full guide.
This 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.
This library is designed to work seamlessly with the official icon set from NAV/Aksel.
# npm
npm install @navikt/aksel-icons
# yarn
yarn add @navikt/aksel-icons
# pnpm
pnpm add @navikt/aksel-iconsIcons are exported as named React components. Import only the icons you need (tree‑shakable):
import { AirplaneIcon, NewspaperIcon } from '@navikt/aksel-icons';
import { Button, Tag } from 'rk-designsystem';
export function IconsExample() {
return (
<div style={{ display: 'flex', gap: 12 }}>
{/* Icon + text: hide icon from AT */}
<Button>
<AirplaneIcon aria-hidden style={{ marginRight: 'var(--ds-spacing-1, 4px)' }} />
Fly
</Button>
{/* Icon inside Tag */}
<Tag data-color="info">
<span style={{ display: 'inline-flex', alignItems: 'center' }}>
<NewspaperIcon aria-hidden style={{ marginRight: 'var(--ds-spacing-1, 4px)' }} />
Ny
</span>
</Tag>
</div>
);
}- Icon + visible text: set
aria-hiddenon the icon so screen readers don't announce it twice. - Icon‑only triggers (e.g., a button): add a descriptive
aria-labelto the trigger, keep the iconaria-hidden. - Color: icons inherit
currentColor; use the component's variant/color to control it (e.g., button variants, tag colors). - Size: set
fontSize(e.g.,fontSize="1.25rem") or inline style (e.g.,style={{ fontSize: '1.25rem' }}).
Use named imports from @navikt/aksel-icons to keep bundles small—unused icons are tree‑shaken by modern bundlers.