Container themes
Add customizable style across streams, cards, and card elements.
Add a Container theme
- From the Configuration section in the workbench sidebar menu, choose Container themes. Alternatively, open the command palette and type Container themes .
- Click the SDK tab
- Click Add theme button.
Understanding Container themes
This guide contains a detailed summary of which style attributes are customizable across streams, cards, and card elements and how to configure these via themes. Watch this video below for an overview.
- Design principles
- Error and loading states
- Themes
- Position
- Variants
- Markdown
- Colors
- Fonts
- Theme reference
Design principles
Styling the SDKs so they feel right at home in your host apps is crucial to a positive user experience – so we've made their appearance highly configurable.
When creating and sending a card to a container for the first time, you'll notice some sensible defaults are already set. When edited, this style propagates at once across Web, iOS, and Android simultaneously. However, some deviations in layout occur on each platform in order to adhere to their respective design conventions.
Aside from these platform deviations, at present, style is defined globally to establish consistency across platforms.
Error and loading states
Each SDK may be in one of the following three temporary states:
- No internet connection;
- An API issue;
- Loading.
There are two ways these states may be styled, depending on whether a theme has been cached on-device yet. When a stream container is loaded for the first time on a device, the SDK-level configuration options are used. On subsequent loads, once a theme has been cached, this theme is used to style the error and loading states.
This information applies to all display modes for all platforms, except single card view. For single card view, no visual error or loading states are shown at all, but instead the container is set to a collapsed state whilst loading or in an error state, as the intention for the single card view is to be as unobtrusive as possible.
Customizable style attributes
Workbench theme
These theme elements are used once a cached theme has been downloaded on the user's device.
- Message and button text: See Error overlay in the theme reference.
- Loading indicator: See Loading spinner in the theme reference.
If you wish to match your theme to the default style set by via the SDK on first load, the values are as follows:
- iOS
- Message text: San Francisco, 17px, weight regular(400)
- Button text: San Francisco, 17px, weight bold(700)
- Android
- Message text: Roboto, 16px, weight regular(400)
- Button text: Roboto, 14px, weight bold(700)
- Web
- Message text: System default font stack, 16px, weight regular(400)
- Button text: System default font stack, 16px, weight bold(700)
SDK configuration
These theme attributes are set in code by your development team, and apply only on the first load of a theme for a stream container. Note that the SDK configuration has limited customizable style attributes for message text and button text, to reduce complexity while loading a theme for the first time.
- Message text: Color
- Button text: Color
- Loading indicator: Color
See configuration detail documentation for iOS, Android, or Web.
Themes
In the Atomic Workbench, style is set in the theme editor, where you can edit, add, or delete themes. Go to: Configuration > SDK > Container themes.
The theme editor generates a structured JSON object. When editing the theme, you can edit the raw JSON by selecting the overflow menu then 'Show JSON'.
As a rule, most non-layout stylistic attributes are fully customizable. For example, you're able to define border radius, background color or font weight on a button to match your design language, but not layout properties like width
or margin
.
Fonts
Custom fonts can be added within the theme editor, and referenced in the theme. You can reference hosted OpenType (.otf) or TrueType (.ttf) fonts by url, or use fonts already embedded in your application, for iOS and Android.
If a font is not specified, Atomic uses the following fallbacks:
iOS
San Francisco
Android
Roboto
Web
The default of sans-serif
is the last resort and will be different depending on operating system:
- Apple operating systems will use San Francisco
- Windows will use Segoe UI
- Chromebooks will use Roboto
- The fallback chain is: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
If you specify a default font in the theme, Atomic will use that font in every place you have not defined a font.
Embedded fonts
When creating your stream container's theme in the Atomic Workbench, you optionally define custom fonts that can be used by the stream container for UI elements. When defined in the Workbench, these fonts must point to a remote URL, so that the SDK can download the font, register it against the system and use it.
It is likely that the custom fonts you wish to use are already part of your app, particularly if they are a critical component of your brand identity. If this is the case, you can have a stream container font - with a given font family name, weight and style - reference a font embedded in your app instead. This is also useful if the license for your font only permits you to embed the font and not download it from a remote URL.