Adventure Documentation

7. Theme

  1. What is the Theme
  2. Working with the Theme

What is the Theme

The theme specifies the color of the components, size of heads, level of shadow, transition speeds and much more.

Themes let you apply a consistent tone to your app. It allows you to customize design aspects of your template in order to meet the specific needs of your business or brand.

The base theme has a number of root terminologies that contains configuration specific to that design aspect. The base theme has the responsibility of keeping things on the template consistent from a top level so everything follows the same ruleset, the sections are the following:

  • radius (Defines corner smoothing applied to elements throughout the template)
  • shadow (Defines the shadow applied to elements throughout the template)
  • spacing (Defines spacing between elements on the page, very usefull to keep consistency)
  • palette (Defines sets of colors that work well together, main and contrast color)
  • typography (Defines text sizes and fonts used thoughout the template)
  • breakpoints (Defines at what screen size the template is considered mobile, tablet and desktop) 
{
    "palette": {
        "primary": {
            "main": "#000000",
            "contrast": "#ffffff"
        },
        "secondary": {
            "main": "#F2F2F2",
            "contrast": "#000000"
        },
        "error": {
            "main": "#f55426",
            "contrast": "#ffffff"
        },
        "success": {
            "main": "#4db37c",
            "contrast": "#f4f8f7"
        },
        "action": {
            "main": "#5344ad",
            "contrast": "#ffffff"
        },
        "warning": {
            "main": "#f8aa00",
            "contrast": "#ffffff"
        },
        "disabled": {
            "main": "#c8cfd7",
            "contrast": "#7a7d80"
        }
    },
    "radius": 0,
    "shadow": "0 5px 5px 0  rgba(100, 100, 111, 0.2)",
    "spacing": {
        "base": ".8rem",
        "small": "calc(var(--hs-spacing-base) / 2)",
        "large": "calc(var(--hs-spacing-base) * 2)"
    },
    "transitions": {
        "easing": "ease-out",
        "duration": {
            "base": "200ms",
            "long": "300ms",
            "short": "100ms"
        }
    },
    "typography": {
        "font": "sans-serif",
        "root": "16px",
        "sizes": {
            "small": "1rem",
            "base": "1.4rem",
            "large": "2rem"
        },
        "headings": {
            "h1": "2.4rem",
            "h2": "2.2rem",
            "h3": "2rem",
            "h4": "1.8rem",
            "h5": "1.6rem",
            "h6": "1.4rem"
        }
    },
    "breakpoints": {
        "default": "xxl",
        "values": {
            "sm": "600px",
            "md": "960px",
            "lg": "1280px",
            "xl": "1536px",
            "xxl": "1960px"
        }
    }
}

Working with the Theme

The theme is defined by a JSON file located in the /config/theme.json path. This file has to exist for the template to function properly, and making changes is as simple as editing values or even adding and removing keys.

The theme can be customized by the shop owners through the shop administration. This is the recommended way to make changes to the theme.

Theme values can be accessed by using the theme get method provided by the theme module, simply call the theme get method with the key you want to display and it will return the value. This function can be provided a default argument which will be returned if the key does not exist, otherwise null is return.

{$theme = $Platform->import("theme")}

<p>
    <span>The content of "transitions.easing" is:</span>
    <span>{$theme->get("transitions.easing", "easeInOut")}</span>
</p>

The theme is also automatically exposed as CSS variables so they can be accessed in the CSS files of the template. This is a very powerful feature that makes it possible to have consistency throughout the template even if there is a lot of different CSS files, while also ensuring that CSS files can be cached so they don't have to be changed even if the theme changes.

The variables are prefixed with --hs and every part of the nested structure is separated by a dash (-), eg. --hs-transitions-easing.

Unfortunately, CSS variables can not be used in media queries, so all responsive CSS will be located inside the component file. The following example will not work in CSS files, instead we must declare this rule in the tpl files. Hopefully in the future we can pull this logic into the CSS files using the up and coming environment variables for CSS.

{Style}
    @media(min-width: $theme->get("breakpoints.values.sm")) {
        .responsive-rule { visibility: visible }
    }
{/Style}

This is a snippet of a CSS file that makes use of the CSS variables, it uses multiple variables from the theme.

.container {
    margin: 0 auto;
    max-width: var(--hs-container-width);
    box-sizing: border-box;
}

.container--width-sm {
    --hs-container-width: var(--hs-breakpoints-values-sm);
}

.container--pad-block {
    padding-top: var(--hs-spacing-large);
    padding-bottom: var(--hs-spacing-large);
}

Search results