UI theming and branding
Salsa's embedded and hosted UI can take on your brand's colors, fonts and component styles, so payroll looks and feels like the rest of your product.
Every Salsa UI element and hosted experience is built on a design system that is driven entirely by a theme. Colors, typography, spacing, borders, component styles and more all come from that theme, which means we can reshape the look and feel of Salsa UI to match your brand, from a quick color swap to a full match with your own design system.
Themes are applied by Salsa. Reach out to us through your usual channel, such as Slack or email, whenever you'd like to discuss your theme or learn more. We'll work with you and your designer to set it up or update it. There is no code change needed on your side.
How theming works
Your theme is tied to the client key that Salsa provides you. Whenever Salsa UI is loaded with your client key, it renders with your theme automatically.
| Experience | Uses your theme |
|---|---|
| UI elements embedded with Salsa.js | ✅ Yes |
| Hosted experiences, such as hosted employer and worker onboarding | ✅ Yes |
| Payslips viewed or printed from Salsa UI | ✅ Yes (colors) |
| Salsa Dashboard | ❌ No |
For embedded elements, make sure you initialize Salsa.js with your client key. Without it, Salsa UI renders with Salsa's default look instead of your theme. Hosted links don't take a client key: we connect your hosted experiences to your client key on our side during your integration. A few hosted-only areas, such as the worker onboarding header, can't be themed yet.
The Salsa Dashboard is a partner-facing tool used by your team, not by your employers or workers, so it always shows Salsa's own look and feel.
Because the theme sits underneath every element, a change to it applies everywhere at once. You don't need to redeploy, re-embed or pass new options. Once we release the update, every element and hosted page picks it up the next time it loads.
What you can customize
Customizations range from a couple of brand colors to a complete visual match with your design system. They build on each other, so you can start small and go further whenever you like.
Brand colors
The most common starting point. You give us your brand colors and we turn each one into a full palette of ten shades, from lightest to darkest.
- Primary color. Used for main actions, active states, links, checked controls and highlights.
- Secondary color. Used for supporting accents, such as avatars and secondary highlights.
- Supporting palettes. The grays, reds, greens, yellows and blues used for neutral surfaces, errors, success messages, warnings and information can be replaced with your own, so status colors match your product too.
If your design system already defines exact shades, we use those instead of generating them.
Typography
- Font families for body text, headings and monospaced content. We can use widely available fonts or load your own custom font files.
- Font weights for headings, labels and buttons.
- Font sizes across the type scale.
- Letter spacing, including different values per heading level.
To use a custom font, send us the font files in a web format (such as WOFF2, TTF or OTF) for each weight you use, and confirm that your license allows the font to be embedded on the web.
Design tokens
Beyond palettes, Salsa UI uses semantic tokens: named roles like "body text" or "border" that every component refers to. Changing a token changes every place that role appears. Tokens can be customized for both light and dark mode, including:
- Body text color
- Default and light border colors
- Link colors for default, hover and pressed states
- Label and value colors in cards and summaries
- Side panel and subtle background colors
- Menu item text color
Component styles
Nearly every component in Salsa UI can be restyled, both its base look and each of its variants, sizes and interactive states (hover, focus, pressed, checked and disabled). Common examples:
| Component | Examples of what can change |
|---|---|
| Buttons | Corner radius, height, padding, font weight and size, borders, text shadow, and hover and pressed colors for each style (solid, outline, ghost and link) |
| Text inputs, selects and text areas | Corner radius, background, border colors, hover background and focus ring style |
| Checkboxes, radio buttons and switches | Size, border width, corner radius and checked colors |
| Cards | Corner radius, border, shadow, header and subtitle styles, and the default card style |
| Tables | Header background and text color, row hover and selected colors, borders and header capitalization |
| Modals and drawers | Corner radius, padding, and header and footer dividers and backgrounds |
| Menus, popovers and tooltips | Corner radius, background and default placement |
| Headings and form labels | Font weight, color and size |
| Avatars | Background and initials color |
Styles can also depend on context. For example, a button style can apply only to brand-colored buttons, or a color can differ between light and dark mode.
Page-level styles
Global styles that apply across all of Salsa UI, such as:
- Page background color
- Base text styles and letter spacing
- Heading styles at each level
Light and dark mode
Salsa UI supports light, dark and system color modes. You choose the mode for each element with the colorMode option in Salsa.js. Elements render in light mode unless you set it. With system, the element follows the user's device setting.
The color mode is set when an element is created. To switch modes while your app is running, destroy the element and create it again.
Your theme can define separate colors for light and dark mode, so your brand holds up in both. If you render elements in dark mode, send us your dark mode colors too. Otherwise, dark mode falls back to Salsa's default colors.
What a theme doesn't change
A theme is global: it changes how Salsa UI looks everywhere, consistently. It doesn't change one screen differently from the rest. Requests such as a different button color on a single page, new spacing in one section of a workflow, or adding your own content inside a Salsa screen are outside what a theme can do, because they can't be supported reliably as Salsa UI evolves.
A theme also doesn't change layout, breakpoints or how elements behave on small screens, and it doesn't apply to emails or notifications. To notify your users in your own branding, use webhooks.
If part of a workflow needs to look or behave very differently from the rest, we may be able to support it with an element option. Otherwise, you can build that part of the experience yourself with Salsa's APIs. Tell us what you're trying to achieve and we'll help you pick the best approach.
Beyond look and feel
Some other parts of Salsa UI can also be tailored for your client key:
- Help links. Point help links in employer onboarding and the employer dashboard to articles in your own help center, so employers get support in the place they already use.
- Selected labels. A small set of button and action labels can be renamed to match the terms your users already know. For example, a "Run payroll" button can read "Preview payroll" instead. This applies only to specific labels that Salsa supports, not to any text in Salsa UI.
- Rules we configure for you. For a set of data and actions, we can make them editable, read-only or hidden for your client key. For example, we can make a field read-only, or hide one that doesn't apply to your business. These rules aren't self-serve, so ask us.
Separately, element options that you set in Salsa.js control behavior such as which cards or steps an element shows and which inputs are read-only. See each element's reference page for its options. Some layout, such as table columns and the order of cards, is fixed.
Ask us about any of these when you set up your theme.
Examples
These examples, based on themes we've built with partners, show the range of what's possible.
Brand colors only
A partner provides a primary and secondary color. We generate both palettes, and every button, link, checkbox and highlight across Salsa UI takes on their brand.
Brand colors, font and shape
A partner wants Salsa UI to match their product's typography and softer, more rounded look. In addition to colors, we load their brand font, round the corners of buttons, cards and tables, adjust heading weights, and give tables a branded header row.
Custom button styles
A partner's product uses raised, bordered buttons with a distinct pressed state. We restyle each button style (solid, outline and ghost) with their borders, hover colors and pressed effect, adjust button height and padding, and set a page background that matches their product.
Full design system match
A partner shares their design system's tokens and component documentation. We map it onto Salsa's theme: custom font files, replacement gray, red and green palettes, link colors taken directly from their tokens, and restyled buttons, inputs, checkboxes, radios, switches, cards, tables, modals, drawers, menus, popovers and tooltips. Spacing, font sizes and letter spacing follow their type scale, so Salsa UI is hard to tell apart from the partner's own screens.
Working with us on your theme
We usually set up your theme during your integration, but you can start or update it at any time, including long after launch.
- Reach out. Message us through your usual channel, such as Slack or email, and tell us how far you'd like to go.
- Share your brand. Send whatever you have. Helpful materials include:
- Brand colors as hex values, or full palettes if you have them
- Font names, or font files and license details for custom fonts
- Your design system, design tokens or Figma library
- Screenshots of your product, especially the screens next to where Salsa UI will appear
- Specific components or details you care most about, such as button shape or table headers
- Review together. We share screenshots or a preview with you and your designer, and adjust until it looks right.
- Launch. We release your theme to sandbox and production at the same time.
Some brand colors don't have enough contrast in every role, such as white text on a light button. When that happens, we'll work with you to pick a shade from your palette that keeps text readable. After a font change, we also check text wrapping and spacing across the main screens.
Updated about 21 hours ago
