UI Design System & Theming
Relevant source files
The following files were used as context for generating this wiki page:
The UI Design System & Theming in this project is a robust, multi-tenant architecture designed to support various partner platforms (such as DXKB and BV-BRC) through a unified codebase. It leverages Tailwind CSS, CSS Variables (OKLCH color space), and a React-based content mapping system to dynamically alter both the visual appearance and the semantic content of the application based on the active theme.
The system is built on Next.js 16 and utilizes next-themes for theme switching, integrated with Radix UI and Base UI components to ensure accessibility and consistent interaction patterns. Sources: package.json:28-60, src/app/layout.tsx:86-105
Architecture and Data Flow
The design system operates by injecting theme-specific CSS variables into the DOM and providing a ThemeContent utility that resolves text strings based on the active theme.
The diagram above shows the relationship between the ThemeProvider, the global CSS variable injections, and the content resolution logic.
Sources: src/app/layout.tsx:86-105, src/app/globals.css:1-115, src/styles/theme-content.ts:1-105
Design Tokens and Color System
The system uses the OKLCH color space for defining design tokens. This allows for better perceptual uniformity and easier manipulation of lightness and chroma across themes. Themes are applied using the data-theme attribute on the HTML element.
Core Token Mappings
| Token Category | Variables | Purpose |
|---|---|---|
| Colors | --primary, --secondary, --accent, --destructive | Main brand and action colors |
| Backgrounds | --background, --card, --popover, --muted | Surface and container colors |
| Typography | --foreground, --muted-foreground | Standard and low-contrast text |
| Borders/Inputs | --border, --input, --ring | Interactive element boundaries |
| Layout | --radius | Component corner rounding (variable per theme) |
Sources: src/app/globals.css:10-45
Theme Definitions
The project explicitly defines light and dark variants for multiple theme bases including dxkb, bvbrc, zinc, orange, and violet.
[data-theme='dxkb-light'] {
--radius: 0.65rem;
--background: oklch(1 0 0);
--primary: oklch(45.57% 0.137 266.75);
--secondary: oklch(71.57% 0.182 37.18);
}
[data-theme='dxkb-dark'] {
--radius: 1rem;
--background: oklch(0.145 0 0);
--primary: oklch(45.57% 0.137 266.75);
}
Sources: src/app/globals.css:48-115
Dynamic Theme Content
Beyond visual styles, the system manages "Theme Content"—semantic strings that change based on the organization using the platform. This is managed via theme-content.ts, which maps theme IDs to specific content folders.
Content Types and Mappings
| Content Type | DXKB Value | BV-BRC Value |
|---|---|---|
site-name | Disease X Knowledge Base | BV-BRC |
funding-title | A CEPI Initiative. | BRC Program |
welcome-title | Welcome to the Disease X... | Welcome to the Bacterial and Viral... |
Sources: src/styles/theme-content.ts:20-60
Content Resolution Logic
Functions like getThemeContent(theme, contentType) resolve the correct string by looking up the themeBase. For instance, both zinc and orange themes map to a generic content folder. Sources: src/styles/theme-content.ts:7-15, src/styles/theme-content.ts:65-79
Component Styling Patterns
The system utilizes Tailwind's @apply directive and custom CSS classes to maintain a consistent look for complex components like data tables and service forms.
Data Table Styling
The DataTable component uses a mix of utility classes and inline CSS variables to handle dynamic column sizing while maintaining theme consistency.
- Header: Sticky positioning with
bg-primaryandtext-secondary. - Rows: Uses
hover:bg-muted-foregroundfor interaction states. - Selection: Active rows are highlighted using
bg-muted-foreground.
Sources: src/components/containers/DataTable.tsx:570-650, src/app/globals.css:573-581
Service Form Elements
Service forms (e.g., Subspecies Classification, Primer Design) use standardized class names:
.service-card-title: Large, bold headings with optional info popups..service-card-input: Inputs with transition effects andbg-secondary/20hover states..service-collapsible-container: Bordered cards for advanced parameters.
Sources: src/app/globals.css:260-350, src/app/services/(viral-tools)/subspecies-classification/page.tsx:210-250
Global Layout and Shell
The RootLayout ensures the design system is initialized correctly by wrapping the application in a ThemeProvider and a Providers component.
This sequence shows how the theme is applied during the initial page load to prevent hydration mismatches.
Sources: src/app/layout.tsx:86-110, src/app/globals.css:1-10
Navigation and Footer
The DesktopNavbar and Footer components are "Theme Aware." For example, the Footer uses the ThemeContent component to display the correct funding statement based on whether the site is viewed as DXKB or BV-BRC. Sources: src/components/footers/footer.tsx:75-85, src/components/navbars/desktop-navbar.tsx:50-100
Conclusion
The UI Design System & Theming module provides a scalable way to manage multiple brand identities within a single Next.js application. By decoupling visual tokens (CSS Variables) from semantic content (ThemeContent), the project allows developers to add new partner themes with minimal code changes while maintaining high performance and accessibility.