Your Union Design System

This is the design system and component library for the University of St Andrews Students’ Association.

A design system is a set of standards and guidelines which you can follow to make your website consistent with the Union’s brand. This means you can spend more time developing the website and less time testing and designing little elements, since you can re-use the work already done here.

This design system uses code from Bootstrap and takes inspiration from the GOV.UK Design System and University of St Andrews Digital Pattern Library.

See also: Your Union Brand Guidelines.

Please contact [email protected] before using this design system in your own work.

---

Colours

The primary colour of the current page depends on that page’s family.

• Blue (#00AEEF) is used for events, spaces, and entertainment.
• Yellow (#E3B338) is used for representation, SRC, welfare, and equality.
• Crimson (#D91B5B) is used for activities, societies, and volunteering.
• Grey (#3D3937) is used for administrative matters.

You can use the dropdown at the bottom of the screen to switch the primary colour used in examples on this page.

For more information about the Union colour scheme, see the brand guidelines.

Various shades of each colour are available as CSS variables.

blue-100	yellow-100	crimson-100	gray-100
blue-200	yellow-200	crimson-200	gray-200
blue-300	yellow-300	crimson-300	gray-300
blue-400	yellow-400	crimson-400	gray-400
blue-500	yellow-500	crimson-500	gray-500
blue-600	yellow-600	crimson-600	gray-600
blue-700	yellow-700	crimson-700	gray-700
blue-800	yellow-800	crimson-800	gray-800
blue-900	yellow-900	crimson-900	gray-900

---

Components

These are the components available in the library:

• Button
• Details
• Event row
• Footer
• Forms
• Header
• Heading
• Headline
• Iconography
• Inset
• Notification
• Patterns
• Profile list
• Table
• Tinted card
• Typography

Button

“Button” refers to an element which looks like a button. Semantically, it could be:

• <button type="button"> or <input type="button">, triggering a JavaScript action,
  • Even on <button> elements, type="button" needs to be specified. This is because all MSL pages are wrapped in <form> tags, and the default action of a <button> with no specified type is to act as a submit button.
• <a class="button">, linking to another page,
• <input type="submit">, submitting a form,
• <input type="reset">, resetting a form.

Make sure to use the correct semantic markup for the button.

Button text should be short and accurately describe what clicking the button does. For example “Sign up” or “Buy tickets” would be good button text. “Click here” or “Button” is not.

Keep button text short. It will always appear on one line, so on small screens long buttons may hang off the side of the page.

By default, a button will be a primary button, bordered with the primary colour of the current page.

You can make a button into a secondary button using the button-secondary class. This will make it a lighter, less prominent variant.

Primary and secondary buttons work well next to each other, where you have a ‘main’ action you want a user to take, with an alternative path available.

Make a button bigger using the button-large class. Make a button smaller using the button-small class.

Details

Details elements hide content from a user. This is useful for:

• Making a page easier to quickly read by hiding details which not all users need to see.
• Showing an overview of related content.
• Letting a user hide and show content which is relevant to them.

Do not use a details element for content which every user needs to see. Remember, they hide content, which means that some people may never notice the content exists. Before the details element, first try:

• Simplifying the page and removing unnecessary detail.
• Splitting the content into smaller sections – across multiple pages, or using subheadings. You could then use page navigation components to let a user jump to the section relevant to them.

Don’t put details elements inside other details elements.

Keep the summary text short and descriptive, so people can quickly understand what’s hidden and if they need to open it.

Event row

MSL Event List widgets can be displayed as a compact list by adding the event-row wrapper div CSS class in the widget settings.

Footer

The footer is intended as extra navigation, for places which are regularly needed but not headline features of the site. This includes contact information and social media links.

It’s also the place to link to legal documents and make any references which are required on every page of the site – for example, our charity number which must be displayed in line with OSCR rules, and a copy of our privacy policy.

Remember, any content you put in the footer appears on all pages of the site, so make sure the information you’re adding needs to be there.

The footer is separated from page content using the same skyline image as our logo. The skyline and divider match the current page’s primary colour.

Note that the SVG skyline and icons included must be loaded from the same domain as the main page to appear correctly, and may not appear at all in Firefox. This is a security limitation of the <use> element which we have not applied a workaround for yet.

Forms

MSL wraps every page in a <form> element. This means you don’t need to add your own <form> in the page content, just rely on the wider one provided by MSL.

There are custom styles to clearly display whether each input is valid or not based on the standard HTML5 form validation attributes (like required, pattern, type, maxlength, etc). To avoid showing this validation information while the user is still inputting data, they’re not displayed until the parent <form> has the validated class. This class is added by JavaScript when the form is submitted.

The web browser’s standard validation messages are used to describe exactly what’s wrong with each invalid field. Try to submit the below form to see your browser’s error message style.

Header

The header is the first element on every page and includes our main site navigation.

The first element of the header is a “Skip to main content” link. This appears when it is focussed – usually by someone browsing the page using their keyboard instead of a mouse – and lets the user jump their keyboard focus to the main page content. To support this, the main section of each webpage should have the main ID.

The navigation is built mostly around dropdowns. Each navigation item is an <li> inside an unordered list. There is a <button class="nav-dropdown-toggle"> which is used to open and close the navigation. It uses the aria-expanded and aria-controls attribute both to aid assistive technology and to help manage the dropdown’s state using JavaScript.

The button has a data-path attribute which includes the base path of this site section including a trailing slash. For example, the “About” dropdown has data-path="/about/". This is used by front-end JavaScript to add the current class and aria-current="page" attribute if the user is viewing a page within that section. We cannot do this server-side because no MSL navigation widget lets you create <button>s.

The currently active section’s dropdown is left open by default when you’re on a page in that section. For example, when looking at the list of societies, the “Activities” dropdown is left open on the page by default. This allows users to more quickly navigate to related site content. JavaScript is used to prevent the dropdown obscuring page content.

Immediately following the button is a <div class="nav-dropdown-container"> containing the dropdown content – usually an unordered list of links, but sometimes things like the search form. It should be linked to the button by the button’s aria-controls tag.

The basket navigation item uses the MSL Basket Link widget to display the current number of items in the basket. CSS is used to hide most parts of the MSL component except the number of items in the basket, which appear like a notification badge atop the basket icon.

CSS is used for as much functionality as possible, so the system works with JavaScript disabled. JavaScript is used to enhance accessibility by managing keyboard focus, open the menus on click instead of on hover or focus, close the menus using the escape key, and make the stripe at the top of the header match the colour scheme of the currently-open dropdown menu.

On smaller screens, the page navigation moves into a hamburger menu. Within the hamburger, the first level of navigation is the top-level categories (“About”, “Activities”, etc), and the second level is the pages within that section. Multi-level dropdowns are not supported in any other way or further than these two levels.

The most accurate example of this is the main Union website, where the navigation items are built from the real MSL components. In the code, the header comprises the <div class="skip-link">, followed by the <header>.

Heading

Headings are automatically inserted on content pages. They have a large, bold title and use the page’s featured image tinted to match that page’s theme colour. The featured image is also the one used for link previews on social media sites and similar. Some spot and stripe décor is added on top and behind the heading for depth.

Headline

The headline appears on the main website homepage and includes key items we want to feature, such as big events or offers.

It is made of 1200x630px images, displayed in a grid pattern, and is based on the markup of the MSL News List widget with the headline class.

• If there is one headline, it appears as a single image taking approximately the width of the page container.
• If there are multiple headlines, the headline is split into three columns. The first headline takes two units of width and height, in the top left. Other news then appears around it, taking up one unit of width and height each.

Iconography

Icons are from Font Awesome Free. We don’t load the entire library, just the icons we need in some SVG sprites.

The SVG <use> tag (a common way of loading SVG sprites) will only load content from the same domain in most web browsers, so the sprites need to be hosted on the same system as the main site. Additionally, Firefox will only load the content if it’s in the same subdirectory, which means some icons aren’t currently displayed in that browser. This is a known issue.

Inset

Insets can be used to draw attention to a piece of information. Keep them extremely brief and use them very rarely, so they maintain their impact.

Notification

Notifications are used to show the status of actions in the interface. Most of these are automatically generated in MSL so we don’t have any control over the markup.

Generally, there is an outer div.msl_notification with an inner span.<error type>. All styles we define here need to override the MSL system styles.

MSL tends to use .msl_info for both success and info messages, and .msl_warning, .msl_error, and .error for both errors and warnings.

Patterns

Various patterns are available as page décor. Use a Bootstrap-type background colour utility class along with the class for the pattern you’d like on a <div> or similar, then the element where you’d like the pattern.

Profile list

The Profile List component is created by adding the profile-list class to the MSL Image Navigation widget. It includes the page image in a square, the page title, and description laid out in a grid and is intended for lists of people, like the Officers page.

Table

Tables should be made of standard semantic HTML, including headers, bodies, and footers as needed.

Tinted card

Tinted cards are an alternative layout of the MSL Image Navigation component and include big, bold buttons with the page name and description (if enabled in the widget settings), and a tinted version of the page’s image.

To use tinted cards, add the tinted-cards class to the wrapper div CSS of the Image Navigation widget. You can make a widget including all pages below a certain page in the navigation tree, or based on a custom navigation section configured in Website Admin. In the latter case, you can use the medium and large classes to make the buttons two or three units tall respectively, or any colour class (crimson, yellow, blue, or gray) to change the button tint colour. (The small class does nothing, but is sometimes included in markup for clarity). When laying out custom navigation, the tinted-cards-fill-columns class on the wrapper div will change how the items flow into the grid and may make some layouts easier to make.

Typography

All text content is set in Gotham. The book weight is used for body text, bold is used for headings or emphasis, and the light weight is also available.

Text should never be underlined. Underlines are only used for links.

BLOCK CAPITALS ARE HARD TO READ AND FEEL LIKE YOU’RE SHOUTING. Write in sentence case instead, making use of italics, bold text, highlights, or the inset component for emphasis.

Dividers

Use a horizontal rule to add a visual divider to page content. Do not re-create the line with dashes or hyphens.

Headings

Each page should only have one level 1 heading. When creating subsections, heading levels should never be skipped – for example, direct subsections of a heading 2 must be titled with heading 3s.

If a page doesn’t look right with the correct heading levels, do not change the heading levels. First, consider if you can re-structure your content to improve the balance of the page. If this isn’t possible, use CSS classes to make one level of heading look like another.

You can remove the detail under a heading using the plain class. Heading 1s never have the detail.

Headings should only be used as titles, never to emphasise or enlarge text. If you need to emphasise something, look at the inset component, use bold or italics, or restructure your content to make the information you need to emphasise more naturally-prominent.

Lists

Ordered and unordered lists can be displayed without bullet points or index numbers by adding the list role.