Experience Styling
Purple Experience
The recommended style setup uses Builder Pipelines to process the styles before they get delivered in the app or web. The experience loads the following four files on startup:
- custom.css
- fonts.css
- platform.css
- submit.css
All your styling changes should end up in the storefront/assets/custom.css file, the others are for special use cases. To make style development easier and allow better common styles, especially in multi-brand setups, it is best to not write any styles into the custom.css directly, but to generate it via pipelines from SCSS files. For details on the pipeline Architecture see Builder Pipelines Architecture Info.
Relative imports are not supported in Web without using SCSS pipelines, as only the custom.css gets inlined to optimize loading performance
Because SCSS also supports CSS, you can leave existing CSS files as they are and just @use them, except for when they use CSS @imports themselves, in which case they must be rewritten to @use declarations
- custom.css ← generated, read-only
- styles/
- index.scss ← entry point, only import other files
- colors.scss ← app colors
- custom.scss / custom.css ← changes for this app only
- ... other styles that can be shared across apps
SCSS imports must not end with ".scss" / ".css", else they won't be compiled in!
Instead, import other files using @use "./custom"; for example to import the custom.scss
In web, for correct distinction between preview resources and live resources, requests contain the query parameter preview=true. Because you can't hardcode these in relative urls, like when you set a background image from CSS, it is best to use resource://dynamic links, e.g.
Out of convenience and to support older styles, the SASS-pipeline scans all css / scss files for relative imports (e.g. paths beginning without a protocol prefix like https://) and replaces them with the according resource://dynamic links, which you could see in the outputted file.
For posts that are displayed directly inside the Purple Experience (basically everything except for PDF issues and old read mode), the best way is to just use a separate SCSS file, e.g. storefront/assets/styles/article.scss. All post-related styling should be scoped for storefront-content-body which is the outermost wrapper around the displayed content.
The ideal solution is to have all base styling in the storefront/assets/styles folder, so they can be just copied from one app to another. For per-app overwrites, an extra file could be used which sets the CSS variables, fonts, colors etc.
