README

What is this repository for?

HTML, CSS and JavaScript for the UCAS Design Framework.

The HTML is written in small, self-contained chunks called components. These are assembled into example pages by a program called Middleman. The CSS is written as Sass, which is also complied by Middleman. Scripts are written as JavaScript.

The resulting files are found in the build directory.
The HTML needs no special software and can be viewed locally or hosted in a central location for easy access by all interested parties.

And why do we need this?

The fundamental idea is to unify the visual style of all UCAS web presence in order to provide a better customer experience.

The aim is to provide a framework consisting of CSS, JavaScript and imagery that can be maintained independently from any project, and included in any project in order to ensure that common elements all have the same look and feel.

See Unified visual style for UCAS web presence and Unified visual style workflow for more detail.

I'm a developer: I just need to implement some markup. What do I do?

You can browse available example pages and view markup by visiting the work-in-progress site, currently at https://s3-eu-west-1.amazonaws.com/ucas-da-ui-framework-2016-01-28/UI/develop/index.html
(Other versions are available: see latest information at http://confluence.ucas.ac.uk/display/designframework/Design+Framework+Home or http://jira.ucas.ac.uk/projects/DF?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page&status=all.)

There is a mix of complete, mocked-up pages and examples of individual components.
If you can't find what you need, speak to the Design Framework team who will be happy to help.

Create a local version of the Design Framework

If you'd like a local version, do the following:

  • If you haven't already, clone this repo.
  • Install Middleman (see below).
  • Run bundle exec middleman build from the root of the repo.
  • All the compiled assets are in build.
  • Example markup is found in build/pages.

How to integrate a version of the design framework into a project

The Design Framework is built and deployed to an S3 bucket and delivered via CloudFront.

Each project needs to pull in the stylesheets and scripts from CloudFront. An example <head> element which lists required tags can be found at https://s3-eu-west-1.amazonaws.com/ucas-da-ui-framework-2016-01-28/UI/develop/pages/global/head-element.html
Link and script URLs will need to be changed to point to the appropriate version for your project.

There are both official, tagged releases (non-changing) and ad-hoc branches (in constant flux) available. A project can safely link to a non-changing tag when in production, but set the development environment to point to a newer tag (or even a development branch in the early stages of a project).
A list of releases is at http://jira.ucas.ac.uk/projects/DF?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page&status=all
Ask the Design Framework team which version is best to include for your particular project.

The base URL will be https://prod.df.ucascdn.com/ followed by the name of the tag you want to use for a stable release.
The base URL will be https://s3-eu-west-1.amazonaws.com/ucas-da-ui-framework-2016-01-28/UI/ followed by the name of the branch you want to use to see work in progress.

e.g. a non-changing tagged release: https://prod.df.ucascdn.com/3.3.1
and a WIP branch: https://s3-eu-west-1.amazonaws.com/ucas-da-ui-framework-2016-01-28/UI/DF-139-search-3.x

So, to bring in base.css from the develop branch, you would use the URL: https://s3-eu-west-1.amazonaws.com/ucas-da-ui-framework-2016-01-28/UI/develop/stylesheets/base.css

To bring in base.css from the 3.3.1 release, you would use the URL: https://prod.df.ucascdn.com/3.3.1/stylesheets/base.css

I'm a frontend dev and need to add new styles and make changes. How do I get going?

First, you'll need Ruby

If you're on OS X or Linux, you probably have it installed already: open a terminal and run ruby -v to check. (Use brew or apt-get, etc., to install it if needs be.)

Installing Ruby on Windows

  • Make sure you either uninstall old versions of Ruby or remove them from your PATH variable - This is highly recommended if you are tempted to recycle an old one it might not work.
  • If you need to install it on Windows, download from http://rubyinstaller.org/downloads. Choose the 32-bit version (the 64-bit version can work, but YMMV).
    Currently, you need at least version 2.2
  • You'll also need the Development Kit, which is on the same page. Make sure you also download the 32-bit version of that.
  • The Ruby installer should be straight-forward.
  • The Development Kit takes a little more work (but not too much). Follow the instructions here: http://github.com/oneclick/rubyinstaller/wiki/Development-Kit

Installing Middleman

  • Open a terminal.
  • If you haven't already, clone this repo.
  • cd into the root of this repo.
  • On Mac, you may need to install the Xcode Comand Line Tools: xcode-select –install
  • On Linux, you may have to install g++: apt-get install build-essential g++ to get some of the things to install
  • Run gem install bundler (if you get SSL errors here please see https://gist.github.com/luislavena/f064211759ee0f806c88)
  • Run bundle install
  • On Windows, you may need to install the hitimes gem manually:
    • gem uninstall hitimes
    • gem install hitimes -v 1.2.3 –platform ruby
  • Run bundle exec middleman from the repo dir in a terminal (newest version of gitbash seems to have issues, powershell works fine however)
  • View site at localhost:4567 (or, if that doesn't work, check the output in the terminal, as Middleman prints out an alternative URL to use when it starts up).

NB To stop Middleman running, use Ctrl-C.
On Windows, you'll get Terminate batch job (Y/N)? popping up (maybe not instantly, so be patient).
Type y and then press Return twice.
If you need to use https, run bundle exec middleman server --https.

Restarting Middleman to see new content

Occassionally you'll need to restart Middleman to see new content: e.g. the index.html page is only refreshed on restart.
Stop Middleman running using Ctrl-C and start again by running bundle exec middleman.

Setting up the linters for JavaScript and SCSS

The linters are set up using npm.

  • Open a terminal.
  • cd into the root of this repo.
  • Make sure you have node installed by running node -v. If you need to install it, follow the instructions at https://docs.npmjs.com/getting-started/installing-node.
  • Run npm install to set up the linters.
  • The easiest way to use them is with a plugin for your text editor. For Visual Studio Code we've been using stylelint and ESLint. For Atom we've been using linter-stylelint.

We're gradually bringing all our code in-line, so you'll still see plenty of non-conformant files for now. New code should be written to keep the linters happy.

Making changes to HTML, CSS and JS

Where things are

  • Individual components (e.g. the logo) are found in source/components.
  • Sample pages, that include a variety of components are found in source/pages.
  • Global Sass files are found under source/stylesheets.
  • Component Sass files are found under source/components, in the directory for that component.

Adding a new component

The HTML, Sass and JavaScript for the component should live in source/components/ in a self-contained directory. Related components are grouped together.

The name of the HTML file needs to start with an underscore and end with .erb
e.g. _header.erb or _main_navigation.erb
Add whatever markup you need in here.

The name of the Sass file needs to start with an underscore and end with .scss
e.g. _header.scss

You will probably want to add an import statement for it to source/stylesheets/base.css.scss
e.g. @import "../components/navigation/main-menu";
or to source/stylesheets/full.css.scss if it's only to be delivered to modern browsers. In this case, your component scss file should have --full or --base in its filename.

Any JavaScript for this component should also have a name which starts with an underscore and end with .js e.g. _header.js You need to add an import statement for it to source/scripts/full.js
e.g. //= require "navigation/_user-menu"

Any images for this component can live in source/images.

Adding your new component to a page

Pages live in source/pages
Their filenames end in .html.erb

Add your new component to an existing page by inserting a snippet like this (using user-menu as an example):

<%= partial "/components/navigation/user-menu" %>

Pages can be seen in your browser at http://localhost:4567/pages/page-name.html
e.g. http://localhost:4567/pages/example.html

While Middleman is running (using bundle exec middleman from the repo root), any changes you make will be updated on page refresh in the browser.

Adding or editing svgs

If you want to change the colour through css, double check in your code editor that it has the fill set to black in the path tag.

Naming your branch

Branch names are used to create test URLs on S3, so it's worthwhile making them short and meaningful.
Start the name with the Jira ticket number.
e.g. DF-134-feedback-button

Deprecating code

If you need to deprecate a CSS class or some other code, then add a comment next to it using the following syntax:
@deprecated since version <version>
where <version> is at least the major version that the code is going into (e.g. 2.x).
Add or update a Jira ticket two major versions away to remove the code. This gives us time to communicate to end-users that a) the code has been deprecated and b) when it will be removed.

How to test new work

Principals and guidance are found on Frontify.

  • Start with the look: does it meet the brand guidelines? If in doubt, ask the design team.
  • Usability: "Similar functionality should look and behave in familiar ways to provide an intuitive user experience across our suite of services." If in doubt, ask the UX team.
  • Accessibility: sees guidance on Frontify.
    • We need to adhere to WCAG 2.0 AA.
    • Use WAVE for automated testing.
    • Check colour contrast.
    • If you are unsure about markup, listen to it using a screen reader (e.g. NVDA).
    • Check that tabbing through a page makes sense and that elements are highlighted suitably.
  • Responsiveness: does everything render sensibly at different sizes?
  • Browsers: see Browser support. Besides local browsers and VMs, we have access to BrowserStack and a selection of devices.
  • No JavaScript: does everything still function with JavaScript off?
  • Markup: (stolen from http://acc.nics.gov.uk/developers/htmlcoding/html6.5.html, no longer online)
    • Markup such as headings, paragraphs, lists, definitions, and quotes add useful semantic information. Markup used for presentation purposes doesn't.
    • Valid code ensures the widest possible acceptance by the multitude of devices, and a clearer upgrade path to new standards.
    • Use the structural markup wherever possible to add meaning to a page
    • Do not use semantic markup for presentation effects, e.g. <blockquote> for indents, <th> for centre align in layout tables, <address>, <em> for italics (default style for these elements), <strong> for bold (default style)
    • Do not use presentation elements to simulate structure, e.g. Bolding and increased font size to make a heading, use <h1>, etc.
    • Do not use deprecated features of HTML
    • Write HTML and CSS according to the specified standards – validate against those standards
    • Total Validator is another useful tool.
  • Class names: class names are based on the Drupal standards. (We hope to clarify these in future.)
  • Make sure we use appropriate Aria roles, states and properties.
  • Performance:
    • Use your browser's network tools to check whether any new requests are being made, whether any JavaScript is forcing repaints or the overall page size is still acceptable (we will be more specific in the future).
    • Use your browser to throttle the network to see how well it performs (2G is a good test).
    • Tools like PageSpeed Insights or webpagetest can be useful.