Opal Design System
Relevant source files
The following files were used as context for generating this wiki page:
Opal is the primary design system for the Onyx project, serving as the single source of truth for frontend standards across all platforms, including web and desktop. It is designed to replace legacy components and unify the user interface through a structured hierarchy of layout primitives, core building blocks, and standardized styling conventions.
The system emphasizes consistency through strict adherence to custom color variables, standardized typography, and high-level layout components. New features and components within the Onyx ecosystem are required to prioritize Opal implementations over legacy directories to ensure design alignment with Figma specifications.
Sources: desktop/AGENTS.md:1-12, web/AGENTS.md:1-12
Component Hierarchy and Architecture
The Opal design system is structured into layers, ranging from low-level "Core Primitives" to high-level "Layouts" and feature-specific "Composite Components."
The diagram above illustrates the vertical dependency structure where feature pages consume high-level layouts which are built upon core primitives.
Core Primitives
The core/ directory contains the foundational building blocks. Developers are generally discouraged from interfacing with these directly, instead using higher-level abstractions like Button or Content.
- Interactive Layer: The foundation for all clickable surfaces. It defines a color matrix for hover, active, and disabled states.
Interactive.Stateless: Manages colors for elements like buttons and links via CSS custom properties.Interactive.Stateful: Manages stateful elements (e.g., toggles) usingempty,filled, orselectedstates.Interactive.Container: The structural box providing height, rounding, and borders.
- Disabled Context: A React context-based system that propagates disabled states through a component subtree.
- Hoverable Animations: Standardizes "reveal on hover" patterns using a group-based React context or local CSS triggers.
Sources: desktop/AGENTS.md:104-162, web/AGENTS.md:104-162
Layout Primitives
Opal provides a set of layout primitives under @opal/layouts to handle common UI patterns like information blocks, actions, and empty states.
Content Component
The Content component is the primary tool for rendering combinations of icons, titles, and descriptions. It automatically selects an internal layout based on a sizePreset and variant.
| sizePreset | variant | Internal Route | Layout Description |
|---|---|---|---|
headline / section | heading | ContentXl | Icon on top (flex-col) |
headline / section | section | ContentLg | Icon inline (flex-row) |
main-content / secondary | section / heading | ContentMd | Compact inline |
main-content / secondary | body | ContentSm | Body text layout |
Sources: desktop/AGENTS.md:20-42, web/CLAUDE.md:20-42
Specialized Layouts
- ContentAction: Extends the
Contentblock by adding arightChildrenslot for buttons, badges, or icons. It also includes apaddingVariantprop to control outer spacing. - IllustrationContent: Used for empty states and error placeholders. It features a center-aligned, vertically-stacked layout with a large 7.5rem x 7.5rem illustration.
- Settings Page Layout: A standardized structure for administrative pages featuring scroll-aware sticky headers and centered content containers (
SettingsLayouts.Root,Header, andBody).
Sources: desktop/AGENTS.md:44-90, web/AGENTS.md:44-90
Core UI Components
Button
Opal standardizes button usage through a single component built on Interactive.Stateless. It inherits the global color/state system automatically.
- Variants:
default,action,danger,none. - Prominence:
primary,secondary,tertiary,internal. - Sizes:
lg,md,sm,xs,2xs,fit.
Sources: desktop/AGENTS.md:92-102, web/AGENTS.md:92-102
Text Rendering
Naked text nodes are forbidden. All text must use the Opal Text component to ensure compliance with Figma styles.
- Font Presets: Uses
TextFontenum (e.g.,main-ui-body,heading-h2). - Color Presets: Uses
TextColorenum (e.g.,text-03,text-inverted-05). - Markdown Support: Opt-in markdown parsing via the
markdown()utility and theRichStrtype.
Sources: desktop/AGENTS.md:207-259, web/CLAUDE.md:207-259
Styling and Design Standards
Color System and Dark Mode
Opal uses a custom color system defined in tailwind-themes/tailwind.config.js and src/app/css/colors.css.
The system maps semantic classes to CSS variables that automatically handle dark mode transitions. Using the dark: modifier in Tailwind is strictly prohibited, except for third-party logo icons.
Color Categories:
- Text:
text-01totext-05. - Status:
status-info,status-success,status-warning,status-error. - Theme:
theme-primary,theme-red,theme-blue, etc.
Sources: desktop/AGENTS.md:173-195, web/AGENTS.md:280-312
Iconography
Only icons from the web/src/icons directory are permitted. External libraries like react-icons or lucide are banned to maintain aesthetic consistency. New icons must be imported from Figma using specific project tooling.
Sources: desktop/AGENTS.md:197-205, web/CLAUDE.md:197-205
Engineering Practices
| Practice | Standard |
|---|---|
| Imports | Always use absolute imports with the @ prefix. |
| Components | Prefer regular functions over arrow functions. |
| Props | Extract into interface definitions within the same file. |
| Spacing | Prefer padding over margin. Use paddingVariant props when available. |
| Class Names | Use the cn utility for joining and conditional classes. |
| Data Fetching | Use useSWR at the component level where the data is needed. |
Sources: desktop/AGENTS.md:314-398, web/AGENTS.md:314-398
Opal Design System represents the transition from legacy frontend code to a modern, maintainable, and visually consistent framework, serving as the technical foundation for the Onyx user interface.