How theming works in Userorbit
Userorbit provides a unified theme system that controls the visual appearance of both your embeddable widget and your public-facing customer portal. When you adjust a theme setting, the change propagates automatically across every surface your customers interact with, ensuring a consistent brand experience.
Design tokens
At the core of the theme system are design tokens — named values that represent individual design decisions such as colors, fonts, spacing, and border radius. Rather than styling each component independently, Userorbit maps tokens to UI elements. For example, your primary color token drives button backgrounds, active states, and link colors throughout the widget and portal simultaneously.
Tokens are organized into several categories:
- Color tokens — primary, secondary, accent, background, surface, text, and border colors.
- Typography tokens — font family, font sizes for headings and body text, line height, and font weight.
- Shape tokens — border radius, spacing scale, and shadow styles.
Inheritance and cascading
The theme system follows an inheritance model. Global tokens act as defaults. When you set a primary color at the workspace level, every component inherits it automatically. You do not need to configure colors for each UI element individually.
Some tokens derive their value from others. For instance, your hover state color is automatically computed as a lighter or darker variation of your primary color, depending on whether you are using light or dark mode. This means a single color change can update dozens of related styles without any extra work.
How changes propagate
When you save a theme change in the Design settings panel, the updated tokens are published immediately. Here is what happens behind the scenes:
- Your new token values are saved to your workspace configuration.
- The widget and portal fetch the latest theme on their next load.
- Active sessions pick up the new theme within a few seconds without requiring a page refresh from your users.
This means you can iterate on your design in near real-time. Open your portal or widget in a separate tab, make a change, and see it reflected almost instantly.
Widget vs. portal theming
The widget and the customer portal share the same set of design tokens. However, the portal has additional layout-level options — such as navigation placement and page width — that do not apply to the compact widget format. All color, typography, and shape tokens remain shared, so your brand identity stays consistent across both surfaces.
Best practices
- Start by setting your brand colors and fonts at the workspace level before fine-tuning individual elements.
- Use the live preview to verify readability and contrast, especially when choosing custom color combinations.
- If you support dark mode, test both light and dark themes to ensure your brand colors work well in each context.