Our Thoughts
Asmita Wagh
Front End Developer
13 October, 2021
5 MIN READ

How to create a Style Guide with Acquia Site Studio

Before we actually start building a style guide, it's important to understand that there isn't a one-size-fits-all approach. The value of style guides extends beyond big brands with large product teams. Mid to small-sized businesses seeking a consistent digital experience also benefit when UI Style Guides are custom-made to their specific needs.

The main uses for the style guide manager are:

  • UI Style Guides are a design and development tool that brings cohesion to a digital product's user interface and experience. 
  • At their core, they: Record all of the design elements and interactions that occur within a site. 
  • List crucial UI components such as buttons, typography, color, navigation menus, etc.
  • Creating a website where the appearance needs to change depending on the active theme. This is useful when using context to switch a theme. For example, switching the theme if a user is logged in.
  • Creating design systems for multi-brand, multi-site solutions, where each brand needs to apply specific branding to a master design system.
  • In addition to must-have UI components, there are a number of practical features that make UI Style Guides easier for businesses and design teams to reference, navigate, and implement.
     

What is a style guide manager? 

  • An optional module (Not required for a Site Studio to work)
  • Centralized controls: Allows specific aspects of your Site Studio styles, templates, and/or components to be managed from the Drupal theme settings.
  • Use cases: Appearance needs to be changed based on the active theme. Manage designs across brands where each brand needs to apply their own branding such as logos, colours, etc. 

What a style guide manager is not?

  • A visual representation of components
  • A way to manage global settings outside the theme/site studio context
     

How to create a Style Guide with Acquia Site Studio

Before you start with creating your custom style guides for your site in Site Studio make sure the first “Style guide manage module” is installed because this module is optional to start working with cohesion. 

Style guide interface

  • Style Guide Builder
  1. Navigate to Acquia cohesion -> Style guides -> Add style guide. 
  2. Can be used to define your various style guides: eg Branding, typography, social links, Footer settings.
     
  • Style Guide
  1. Resides in your Site Studio enabled theme. Appearance -> settings ->  Acquia cohesion Minimal theme.
  2. You can also install via Drush using the following command:
drush en cohesion_style_guide -y

Also, these allow specific aspects of your Acquia Cohesion styles and templates to be managed from within the Drupal theme settings page (Appearance > Settings > "Theme").

Site studio style guide

The style guide can be considered as a shared record that documents the look and feel of a website, visual representation which can be referred to by designers, developers and site administrators.

You can create Style guides to allow specific aspects of your Acquia Cohesion styles and templates to be managed from within the Drupal theme settings page (Appearance > Settings > "Theme"). You can think of style guides as theme overrides.

 

Creating a style guide 

To create a style guide follow the below mentioned steps: 

  1. Navigate to Acquia Cohesion > Style guides
  2. Click +Add style guide
  3. In the next screen, enter a title for your style guide in the Title field
  4. Click on the + button on the Style guide form builder to access the Style guide fields
  5. Drag a field onto the Style guide form builder
  6. Double click the field to open its settings
  7. Give your field a machine name 
  8. Configure any other settings and click Apply
  9. Click Save and continue

Site studio style guide

Machine name generated is used as a token by the Token browser. Ideally, to locate your style guide tokens while building forms it is a good idea to give your fields the same machine name.


Implementing style guide tokens

For each field added to a style guide, a token is generated. You can use these tokens within your Acquia Site Studio styles and templates in place of static values. Style guide tokens created in the style guide need to be mapped to respective fields or its layout to make it configurable in Acquia minimal theme settings.

Steps to insert style guide tokens in your base styles:

  1. Navigate to a style or template
  2. Click the plus icon button to toggle into variable mode
  3. Click the search icon button to open the token browser
  4. Find the style guide token created. It will be under the style guide section of the token browser
  5. Click into the field where you want to insert the token
  6. Click on the token link within the token browser to insert it into your field
  7. Click the plus icon button to toggle out or variable mode
  8. The token should be displayed below the normal field. The value of the token will be used instead of any value inserted into the static field 
  9. Save your template

Link Style guide tokens to base styles / Components  fields


Steps to create style guide tokens for component & insert style guide tokens in your component templates:

  1. Navigate to styles -> custom styles
  2. Create a custom style by clicking on add custom styles 
  3. Select the appropriate group of styles
  4. On creating a custom style machine name will be generated for the style which can be used as a class in the Site Studio style guide
    Site studio style guide
  5. Once the custom style class is added in the Site Studio style guide tokens can be inserted into respective components
    Site studio style guide
  6.  Navigate to the components -> component
  7. Click into the field where you want to insert the token
  8. Click on the markup option under the three dots
  9. Click the plus icon button to toggle out or variable mode
  10. Click on the token link within the token browser to insert it into your markup as a class
  11. The token should be displayed below the normal field. The custom styles created will now be applied to the field in theme settings based on the option selected
    Site studio style guide
    Site studio style guide
  12. Save your template
  13. Configurable styles will now be available in your Site Studio minimal theme. Style guides will only appear for Cohesion enabled themes.

Site studio style guide

Thank you for reading!

Asmita Wagh