Site Styles

Styles:

AuxiliaryColors Colors Config FontSettings FontUrls
IconImage NeutralColors Shapes Spacing Styles
TextColor TextStyles ThemePreset Typography  

Querying

Site Styles are globally available in all templates under the square.site.styles namespace.

You don’t have to specifically list them in your Page JSON props list in order to access them on a template.

Usage

Site Style variables can be interpolated into your Twig Template the same way that resources are - with {{ variable_here }} tags.

These make it easy to use Site Styles (that have been defined by the Seller in the Editor UI) in templates.

Data Structure

The three main categories of Site Style data are:

  • typography
  • colors
  • shapes

Other snapshot variables are directly exposed under square.site.styles, but are less useful:

  • component_styles
  • spacing
  • theme_preset

The three main categories have been organised in a way to make them easier to use in templates.

Typography namespace

Under the square.site.styles.typography namespace, we have:

text_styles

Here, 2-4 text styles are exposed for the site. They are: title, body, and optionally headline and label. Each textstyle contains the following properties: * font_name - the name of the Font Family used for this Text Style, e.g. ‘Butler’ * weight - the weight set for this Text Style, e.g. 700 * provider - this is the original source of the Font Family. * url - an array of URLs for the Font Family, organised by format, e.g. ["woff2" => "public/static/fonts/Butler.woff2"] * font_face_url (optional) - if included, it’s a URL to a .css file hosted by us that defines a @font-face declaration for the Font Family.

See Examples for example usage of Text Styles data.

available_fonts

These are all the subset variations (e.g. different weights) of the fonts that are available from text_styles.

base_font_size

The base font size of the site, defined in px, e.g. 16px.

type_scale

A multiplier number that can be used in a fluid type scaling scheme, such that each step is multiplied by this number. e.g. 1.15

Colors namespace

Under the square.site.styles.colors namespace, we have a list of definitions for color variables on the site. This is derived from the Primary/Secondary Colors, Color Profile, and Color Profile Overrides set on the site. Example value:

{
  "primary": "#141328",
  "primary_contrast": "#ffffff",
  "primary_bright_dark": "#25235d",
  "primary_subtle_dark": "#1e1d30",
  "primary_bright_light": "#a5a2dc",
  "primary_subtle_light": "#efeff5",
  "background": "#501DC2",
  "paragraph": "#ffffff",
  "label": "#ffffff",
  "title": "#ffffff",
  "link": "#ffffff",
  "button_filled": "#141328",
  "button_outline": "#ffffff"
}

Shapes namespace

Under the square.site.styles.shapes namespace, we have a list of definitions for four border radius values, in pixels. Example:

{"default_border_radius":"8px","card_border_radius":"8px","button_border_radius":"32px","image_border_radius":"16px"}

Examples

Site Style data is used in the following example files in the default theme:

  • partials/css_variables.html.twig - creates CSS Variables from the Site’s Color, Shape, and Typography data
  • base.css - uses CSS variables defined in partials/css_variables.html.twig
  • partials/font_assets.html.twig - creates @font-face declarations from the Site’s Available Fonts data

Style resources

AuxiliaryColors

Field Type Description
secondary String Hex value
tertiary String Hex value

Back to top

Colors

Hex color value details for a theme.

Field Type Description
auxiliary AuxiliaryColors Auxiliary color settings
background String Hex value
button_filled_text String Hex value
button_filled String Hex value
button_outline String Hex value
contextual_primary TextColor Text color settings for primary text content
error TextColor Text color settings for error content
label String Hex value
link String Hex value
neutrals NeutralColors Neutral Color settings
overlay String RGBA value
paragraph String Hex value
primary_bright_dark String Hex value
primary_bright_light String Hex value
primary_contrast String Hex value
primary_subtle_dark String Hex value
primary_subtle_light String Hex value
primary String Hex value
success TextColor Text color settings for success content
title String Hex value
warning TextColor Text color settings for warning content

Back to top

Config

Settings for an icon image.

Field Type Description
contrastColor String Contrasting color for the icon
customColor String Custom color chosen for the icon
fontPath String Relative URL to the font in use
iconType String Icon type
imageUrl String Image URL
language String Site language
primaryColor String Primary color of the icon
radius Number Radius of the icon, if circular
siteTitle String Site title
size String Width of the icon, in pixels

Back to top

FontSettings

Details about a font.

Field Type Description
font_face_url String if included, it’s a URL to a .css file hosted by us that defines a @font-face declaration for the Font Family
font_format String Font format, if applicable. Can be null
font_id String Font ID
font_name String Font name
provider String Font provider
url FontUrls Relative URLs to selected font
weight String Font weight

Back to top

FontUrls

Relative URLs to a font.

Field Type Description
woff2 String Relative URL to woff2 file
woff String Relative URL to woff file

Back to top

IconImage

Icon image settings.

Field Type Description
config Config Config settings for the icon
{w}x{h} String Relative URL for the icon image

Back to top

NeutralColors

Neutral color settings.

Field Type Description
neutral_0 String Hex value
neutral_100 String Hex value
neutral_10 String Hex value
neutral_20 String Hex value
neutral_80 String Hex value
neutral_90 String Hex value

Back to top

Shapes

Element shape settings.

Field Type Description
button_border_radius String pixel value
card_border_radius String pixel value
default_border_radius String pixel value
image_border_radius String pixel value

Back to top

Spacing

Spacing settings.

Field Type Description
site_margin Number Maximum site margin (may only be applicable to larger screen sizes)
site_width Number Maximum site width (may only be applicable to larger screen sizes)

Back to top

Styles

A site style configuration.

Field Type Description
colors Colors Theme hex color value details
icon_set String Icon set selection
shapes Shapes Element shape settings
spacing Spacing Spacing settings
theme_preset ThemePreset Pre-selected global site theme preset
typography Typography Font settings

Back to top

TextColor

Text color settings.

Field Type Description
fill String Hex value
on_fill String Hex value
subtle String Hex value
text String Hex value

Back to top

TextStyles

Font settings for a site.

Field Type Description
body FontSettings Font settings for body content
headline FontSettings Font settings for headlines
label FontSettings Font settings for labels
title FontSettings Font settings for titles

Back to top

ThemePreset

A site theme preset.

Field Type Description
id String Theme preset ID
saved_at Number Unix timestamp when the preset was chosen

Back to top

Typography

Font settings.

Field Type Description
base_font_size Number The base font size of the site, defined in px
text_styles TextStyles Font settings for site
type_scale Number A multiplier number that can be used in a fluid type scaling scheme, such that each step is multiplied by this number