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.
Each SDK may be in one of the following three temporary states:
No internet connection;
An API issue;
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.
If you wish to match your theme to the default style set by via the SDK on first load, the values are as follows:
Message text: San Francisco, 17px, weight regular(400)
Button text: San Francisco, 17px, weight bold(700)
Message text: Roboto, 16px, weight regular(400)
Button text: Roboto, 14px, weight bold(700)
Message text: System default font stack, 16px, weight regular(400)
Button text: System default font stack, 16px, weight bold(700)
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.
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.
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:
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.
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.
Elements can be displayed within cards and subviews in any order. However, as mentioned above, their layout attributes are defined by Atomic and cannot be customized. To rearrange elements, simply drag them into the desired order in the Workbench card builder. There are only a few elements that cannot be re-arranged, to keep the user experience consistent – these are listed below.
Understanding that the default design provided by a white-label product like Atomic may not align exactly with your design language, many elements offer several different design variants to provide you with additional flexibility. For example, images can be displayed as they are, or as a thumbnail with accompanying text. Similarly, inputs can be displayed in multiple formats such as on a single line, stacked with a floating label, or placed alongside an optional image.
You can define your theme in the Theme editor in the workbench UI; all of the settings you choose are then saved as a JSON object. Read the Themes section in this page if you want to know how to edit the raw JSON.
Custom font families are supported across all SDKs. You can declare as many fonts as you like in your theme definition, each with any number of weights. OpenType (OTF), TrueType (TTF) and Web Open Font (WOFF & WOFF2) fonts are supported.
A font is unique by a combination of its font name, style and weight. This means that if you want to use the same font, but with different weights, you need to import it for each combination.
Custom font families have the following properties:
fontFamily: The name of the font family. A font is unique by a combination of its font name, style and weight.
weight: Expressed as a numerical value, including 400 for regular or 700 for bold.
style: Either normal or italic.
src: The HTTPS URL to download the font from.
The type of font (either OpenType or TrueType) is inferred from the file extension in the src attribute. Ensure your font URL has a file extension of either otf, ttf, woff or woff2 otherwise your font may not be registered correctly.
Typography styles are defined as an object with a font family name, size, transform, weight, style and line height.
When resolving fonts in the SDKs, the combination of font family, weight and style is used.
All three font properties must match
Add a separate font variable for every combination of name, weight and style that you use on components unless the font is already present on the target device.
If there is no matching variable then the text will fall back to a system default font.
Typography properties are:
fontFamily: The name of the custom font family to use. To use the system font for the platform, you can omit this property. The system font is San Francisco on iOS, Roboto on Android and a platform-specific font on Web.
size: The size to use for the font, as a string with a px suffix; e.g. 15px.
transform: Transformation to apply to the text - either none or uppercase.
weight: Font weight to use - either normal or bold.
style: Font style to use - either normal or italic.
lineHeight: The line height to apply to the font, as a decimal. Omitting this property is equivalent to using a value of 1.
When using the Link syntax, you can point it to one of the subviews you created in the Workbench. The syntax is [Label](subview:Id), where Id is the unique ID of a subview, which can be accessed on the subview page in the Workbench.
The list below contains a description of the properties of each theme and style element. Each of these are customizable in the Workbench. Their dot notation name references a path expression within the JSON object.
Color and text style for the label on inline date pickers and dropdowns, and the value on stacked date pickers and dropdowns. This style is also used for labels on steppers and switches, and the entered value in text or number inputs
Colour and text style for the label on inline date pickers and dropdowns, and the value on stacked date pickers and dropdowns. This style is also used for labels on steppers and switches, and the entered value in text or number inputs