Carnegie Mellon University
Carnegie Mellon Web Kit

Build on the CMU web template

Carnegie Mellon Web Kit › Install

Install the Kit

Add the kit to a site in a CMS, such as Cascade, or to a web app. Either way you pin one exact version, and nothing changes until you move to a newer one.

What to Load

In the page's <head>, link CMU's template first, then the kit, then your own stylesheet, with <link> tags rather than @import, which loads files one at a time. 

<link href="https://www.cmu.edu/common/standard-v6/css/main.6.7.min.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-cms.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-app.css" rel="stylesheet">  <!-- apps only -->
<link href="/your-site.css" rel="stylesheet">

On a page with components that need a script, the kit's script goes just before </body>, after the template's scripts: 

<script src="https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/js/cmu-app.js"></script>
File Load it on What's in it
cmu-cms.css CMS sites and apps Colors and page content: hero, path cards, steps, check lists, callouts and notes, text with a screenshot, pills and tables
cmu-app.css Apps, after cmu-cms.css Forms, tabs, flash messages, dialogs and file drop zones, the bulk selection bar, row buttons, sortable headers, filters, progress bars, folded lists and panels
cmu-app.js Pages with components that need it, after the template's scripts Behavior for the components that need it: copy buttons, countdowns and screenshots that enlarge

Your own stylesheet holds whatever is particular to your site or app, with its own prefix.

Icons (Optional)

The kit's icon examples use Bootstrap Icons, an optional library for sites and apps. To use them, add this stylesheet after the kit's stylesheets, with a fixed version as shown: 

<link href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.13.1/font/bootstrap-icons.min.css" rel="stylesheet">

Use Icons

Working With the Template

  • The template comes first. See what it already has on CMU Standard, and use its classes as they are: btn, btn small, ghost, cta, table.alternate, .sidebar, .sr-only. The kit never copies the template's rules or values, and adds a class only for what the template doesn't already do.
  • Everything in the kit starts with cmu-: classes, custom properties (--cmu-red) and JavaScript hooks (data-cmu-copy). Variations use a double hyphen (cmu-pill--green). Give your own classes your own prefix, never cmu-.

Versions

Each release is a git tag, such as 0.1.0, listed on the releases page. jsDelivr serves every tag's files at a fixed address: 

https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-cms.css
https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-app.css
  • Always pin an exact version. An address with a version range (@0) or none at all changes under you when a new release comes out.
  • Versions follow semver. A patch (0.1.1) fixes things, a minor version (0.2.0) adds things, and a major version (1.0.0) can rename or remove classes.

CMS Sites

A site in a CMS loads only cmu-cms.css, from jsDelivr, with one line in the head of every page: after the template's stylesheet and before the site's own, so the site's styles come last. Where that line goes depends on the CMS. 

<link href="https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-cms.css" media="screen" rel="stylesheet" type="text/css"/>

In Cascade

Cascade adds extra code to every page's head from a text block, which the site's setup block points to.

  1. In the site's content, open the text block that holds its head code (often named style, holding a link to the site's css/style.css). If the site has none, choose Add Content > Text Block, and check Advanced editor.
  2. Select Edit and add the kit's link on its own line, above the site's own stylesheet, so the site's styles come last: 
    <link href="https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-cms.css" media="screen" rel="stylesheet" type="text/css"/>
<link href="/css/style.css" media="screen" rel="stylesheet" type="text/css"/>
    Then save it.
  3. If you made a new text block, open the site's setup block, select Edit, and near the end set Additional Code to Yes. In the Code item, set Location to In Head and choose your text block under Block. Save it.
  4. Preview a page to check, then publish the site's pages, which pick up the block's code when they're published.

In Another CMS

In Drupal or another CMS on CMU's template, add the same line where the theme puts code in each page's head, such as the theme's page template or a setting for extra head code. If you don't manage the theme, ask whoever does. Then preview a page to check before you publish.

  • Paste components into a content section's Source code view. Each one on the CMS Components page shows its markup.
  • Keep the site's own stylesheet for anything particular to the site, with its own class prefix. Don't redefine cmu- classes there; ask for a change to the kit instead.
  • Try a new version on staging first: Change the version in the link, check the pages, then publish.

Web Apps

A web app loads both stylesheets, cmu-cms.css and cmu-app.css, after the template's stylesheet and before its own, and keeps its own copy of a release, so it doesn't depend on jsDelivr being up. Add cmu-app.js for the components marked Script. Put cmu-app on <body> on pages with the CMU header and footer, or cmu-framed on pages shown inside another tool (such as a Canvas LTI frame) without them. How you get the files depends on the framework.

In Node

Install the tagged release as a dependency, serve its css folder and link it from your page layout. The version is in package.json with everything else.

  1. Install the version you want: 
    npm install github:cmu-web/cmu-web-kit#0.1.0
  2. Serve its files. With Express: 
    const path = require("path");
const kit = path.join(path.dirname(require.resolve("cmu-web-kit/package.json")), "css");
app.use("/vendor/cmu-web-kit", express.static(kit));
  3. Link them in your layout's <head>, after the template and before your own stylesheet: 
    <link href="https://www.cmu.edu/common/standard-v6/css/main.6.7.min.css" rel="stylesheet">
<link href="/vendor/cmu-web-kit/cmu-cms.css" rel="stylesheet">
<link href="/vendor/cmu-web-kit/cmu-app.css" rel="stylesheet">
<link href="/css/your-app.css" rel="stylesheet">

Builds need to reach GitHub to install the package. If yours can't, copy the files in instead, as in Django.

In Rails

The kit also builds a cmu-web-kit gem that makes its stylesheets and script available to the Rails asset pipeline. It supplies an importmap pin when your app uses importmap. This first pass works from a local checkout and has not been published to RubyGems.

Add the checkout to your app's Gemfile, adjusting the path:

gem 'cmu-web-kit', path: '../cmu-web-kit'

Run bundle install and restart Rails. After CMU's template stylesheet, load the kit before your app's own styles: 

<%= stylesheet_link_tag 'cmu-cms', 'cmu-app', 'application', 'data-turbo-track': 'reload' %>

For importmap apps, import "cmu-web-kit" once in app/javascript/application.js, after your existing template script. Remove previous copies of the kit's assets and their script import. The Rails setup guide covers the full setup, including apps without importmap and local gem builds.

In Django

Copy a release's files into one of your Django apps' static folders and commit them, with the version in the folder name so it's obvious which one you have: 

V=0.1.0
D=yourapp/static/vendor/cmu-web-kit-$V
mkdir -p $D
for f in css/cmu-cms.css css/cmu-app.css js/cmu-app.js; do
  curl -fsSL "https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@$V/$f" -o "$D/${f#*/}"
done

Then link them from your base template:

{% load static %}
<link href="https://www.cmu.edu/common/standard-v6/css/main.6.7.min.css" rel="stylesheet">
<link href="{% static 'vendor/cmu-web-kit-0.1.0/cmu-cms.css' %}" rel="stylesheet">
<link href="{% static 'vendor/cmu-web-kit-0.1.0/cmu-app.css' %}" rel="stylesheet">
<link href="{% static 'css/your-app.css' %}" rel="stylesheet">
<!-- After the template's scripts, before </body>: -->
<script src="{% static 'vendor/cmu-web-kit-0.1.0/cmu-app.js' %}"></script>

collectstatic picks them up with the rest of your static files. Don't edit the copied files; change your own stylesheet, or ask for a change to the kit.

In Another Stack

For PHP, Java or anything else, copy the same files into your app's static folder, as for Django, and link them the same way with your framework's own paths. Commit them, keep the version in the folder name and don't edit them.

Prototypes and Static Pages

For a mockup, a one-off page or a page served while your app is down, link the CDN directly. It's the quickest way to start, at the cost of depending on jsDelivr. 

<link href="https://www.cmu.edu/common/standard-v6/css/main.6.7.min.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-cms.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/gh/cmu-web/cmu-web-kit@0.1.0/css/cmu-app.css" rel="stylesheet">

Moving to a New Version

  1. Read the release notes on the releases page. For a major version, they list every renamed or removed class.
  2. Change the version: in your CMS's head code (in Cascade, the head block), in package.json (then npm install), or in your copied folder.
  3. Check your pages, on staging for a CMS site, before you publish or deploy.