# DBC React Components
Reusable React components for DBC projects.
This library provides a shared, themeable component system used across DBC’s internal (and selected external) applications. It is designed to promote consistency, speed up development, and improve overall quality and accessibility.
---
## Purpose of the library
The goals of this component library are:
- **Consistency**
Provide a unified look and feel across DBC’s digital products, especially internal tools.
- **Development speed**
Reduce development and maintenance time by reusing well-tested components instead of rebuilding UI from scratch.
- **Quality & accessibility**
Components are reviewed and built according to best practices, with accessibility and robustness in mind, ensuring a strong baseline quality.
- **Reduced third-party dependency**
Increase digital independence by building and sharing our own components across the organisation, reducing reliance on external NPM packages.
---
## Getting started
### 1) Install the package
```bash
npm install @dbcdk/react-components
```
---
### 2) Import global styles
> **Important:** The component library requires global styles to be imported once in your application.
```ts
import '@dbcdk/react-components/styles.css'
```
---
### 3) Add `ThemeScript` in your root layout (Next.js example)
The library's shared CSS foundation is still imported normally, but
product-theme switching is handled by `ThemeScript` + `useTheme()`.
`ThemeScript` restores the persisted color scheme and product theme before
paint, so the app avoids a flash of the wrong theme on first load.
```tsx
import { ReactNode } from 'react'
import { ThemeScript } from '@dbcdk/react-components'
import '@dbcdk/react-components/styles.css'
import '@dbcdk/react-components/themes/dbc.css'
export default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
return (
{children}
)
}
```
---
### 4) Switching theme in your application
Example using `useTheme()` when you want to control the theme:
```tsx
'use client'
import { AppHeader, Button, useTheme } from '@dbcdk/react-components'
import { Moon, Sun } from 'lucide-react'
export default function Header() {
const { theme, switchTheme } = useTheme({ defaultTheme: 'dbc' })
return (
)
}
```
The hook updates `data-product-theme`, applies the selected product theme's
token overrides, and persists the selection.
If you only need to read the active theme state, use `useGetActiveTheme()`
instead of `useTheme()`:
```tsx
'use client'
import { useGetActiveTheme } from '@dbcdk/react-components/client'
export function ThemeBadge() {
const { theme, colorScheme, themeKey } = useGetActiveTheme()
return {themeKey ?? `${theme} / ${colorScheme}`}
}
```
`useGetActiveTheme()` is intentionally read-only and takes no options. It
reports the current active theme state as established by `ThemeScript`,
persisted storage, or another mounted theme control. `themeKey` is only set
when both `theme` and `colorScheme` are resolved, and is otherwise `null`.
---
## Using Storybook
Storybook is the primary documentation and exploration tool for this library.
### Local Storybook
```bash
npm run storybook
```
Storybook runs on `http://localhost:6006`.
### In Storybook you can:
1. Browse components in the left-hand navigation
2. Open a story to see variants and states
3. Adjust props via **Controls**
4. Read guidelines and usage notes in the **Docs** tab
---
## Themes
Use the 🎨 **theme selector** in the Storybook toolbar to switch between available themes (e.g. light and dark).
All components are styled using CSS variables defined in the theme files.
---
## Accessibility (a11y)
Accessibility is a first-class concern in this library.
We aim to ensure that components:
- Are usable with keyboard navigation
- Have visible and consistent focus states
- Work with screen readers
- Follow common ARIA and semantic HTML best practices
Storybook includes the a11y addon to help identify issues during development.
---
## Contributing
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for detailed guidelines on:
- Folder structure
- Styling and theming rules
- Storybook requirements
- TypeScript conventions
- Versioning and changesets
---
## License
ISC
```
```