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 Cascade site or 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 copy buttons or countdowns, 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 copy buttons or countdowns, after the template's scripts Behavior for the components that need it: copy buttons and countdowns

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

Icons (Optional)

The kit has no icons of its own. When a page needs them, load Bootstrap Icons (MIT license) after the template and the kit, and pin its version as you do the kit's: 

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

See How to 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.

Cascade Sites

Cascade sites load only cmu-cms.css, from jsDelivr. 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.
  • 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.

Node Apps

Install the tagged release as a dependency, serve its css folder and link it from your page layout. The app then keeps its own copy, so it doesn't depend on jsDelivr being up, and 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">
  4. 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.

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

Other Apps

For Python, PHP, Java or anything else: copy a release's two files into your app's static folder and commit them, with the version in the folder name so it's obvious which one you have. 

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

Then link them as in step 3 above. Don't edit the copied files; change your own stylesheet, or ask for a change to the kit.

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 the Cascade head block, in package.json (then npm install), or in your copied folder.
  3. Check your pages, on staging for a Cascade site, before you publish or deploy.