Getting Started with Pivotal UI

Starter project

We've created two starter projects to help transitioning to Pivotal UI and React.

  • If you want to quickly try out some Pivotal UI components, try PUI Starter Project.
  • If you want to skip directly to building a full React application, try React Starter.

Once you've played around with some examples and feel comfortable integrating into your project, jump to the next step below.

Using Pivotal UI on your project (with React)

If you're ready to try PUI with React, follow these instructions!

Using the React components is the recommended approach over CSS/HTML because:

  • You have reusable, maintainable code that is more consistent. (compare the React Tabs element to HTML version)
  • Meaningful variables for color mean that you remember why you used a particular color ("marketing-header1" vs "teal-23")
  • Cross-browser and responsive issues are handled for you.
  • It's the future.

However, you'll need to know a few more technologies. Not enough to write a PHD thesis, but mostly in case things go wrong. If you don't know what React, Babel or a transpiler is, follow the links below and then return

Ready? We're assuming that you have the following setup on your project:

  • node

    brew install node
  • node package manager

    npm will be installed as part of node

  • Webpack or Browserify - Our React modules follow the CommonJS module pattern. You will need to use Webpack (recommended) or Browserify to compile your javascript for use in the browser.

    We use Gulp and Webpack Stream.

  • A JSX transpiler - It's easiest to write React code with JSX. You will need a transpiler to convert your JSX code into plain javascript for use in the browser. We recommend Babel. If you are using Webpack, you will also want Babel Loader

    Getting Babel working can be complicated. To see a sample project with Babel integrated, look at React Starter or PUI Starter Project

  • React

    npm install react react-dom --save-dev

Seem overwhelming? It's time to talk with a front-end dev on the Pivotal team on how to hook this into your project.

Install

  1. Create a package.json file that will include the PUI modules you'll be using npm init

  2. Install PUI React Tools. This set of tools includes an asset pipeline for including css and svg assets in your JavaScript. Usage is somewhat complicated, React Starter is a sample project with everything set up.

  3. Install a PUI module for the components you need. No need to install additional CSS packages for React components.

    For example, to create a button:

    npm install --save pui-react-buttons
  4. Write some React!

    Javascript:

    var React = require('react');
    var DefaultButton = require('pui-react-buttons').DefaultButton;
    
    var MyTestPage = React.createClass({
     getInitialState: function() {
       return {showMessage: false};
     },
    
     showMessage: function() {
       this.setState({showMessage: true});
     },
    
     render: function() {
       return (
         <div className="container">
           <DefaultButton onClick={this.showMessage}>Show Message</DefaultButton>
           { this.state.showMessage ? <h1>Hello world!</h1> : null }
         </div>
       );
     }
    });
    
    ReactDOM.render(<MyTestPage />, document.getElementById('root'));

    HTML

    <!-- ... -->
     <body>
       <div id="root"></div>
    
       <!-- Script tag should be below all DOM elements -->
       <script src="<path-to-your-project's-compiled-javascript-file>"></script>
     </body>
     <!-- ... -->
  5. Require any css-only components in your javascript

require('pui-css-alignment');
require('pui-css-whitespace');

These will be included in the built css artifact, in addition to any css internally required by your PUI React Components.

  1. Use the asset pipeline from pui-react-tools.

In development mode, this will inject PUI css directly into your page. In production mode, it will create a file called components.css as well as any fonts or images required by the css. If you are using react-starter, you will need to add components.css to your scripts key in application.json.

Using Pivotal UI on your project (without React)

React is the recommended approach (see reasons above), but some elements are available in HTML/CSS. If you just want all of the Pivotal UI css right now, you can download components.css. Note that all assets (including fonts) are inlined into the css, creating a large file. This isn't 100% ideal, but is fine for most webistes.

The prefered way to consume Pivotal UI is through NPM, even for Rails projects. Using NPM to install PUI will ensure proper dependency management on your project.

  1. Run npm init if you don't have a package.json file already.

  2. Install Dr. Frankenstyle. This tool looks at your dependencies (those added with --save, NOT --save-dev), and compiles the CSS required by these packages.

    npm install --save-dev dr-frankenstyle
  3. Install the Pivotal UI CSS modules

    npm install --save pui-css-all

    If you only want to include a few PUI components in your project, see the instructions below on customizing your PUI build.

  4. Install jQuery and bootstrap.js

    npm install --save-dev jquery
    npm install --save-dev bootstrap

    These installs must happen after you've installed the PUI module. This ensures you'll get the correct version of bootstrap js.

    It's important that you install these modules with --save-dev, because we don't want Dr. Frankenstyle to pick up any CSS from these packages.

  5. Run Dr. Frankenstyle to compile your CSS to a folder (we use ./build/ but you can choose whatever makes sense for your project)

    dr-frankenstyle <path-to-your-asset-build-folder>
    # writes the compiled css to <path-to-your-asset-build-folder>/components.css
  6. Add the css and javascript files to your html template

    <!doctype html>
    <html>
     <head>
       <title>...</title>
       <link rel="stylesheet" href="<path-to-your-asset-build-folder>/components.css">
       <script src="<path-to-your-project's-root-folder>/node-modules/jquery/dist/jquery.js"></script>
       <script src="<path-to-your-project's-root-folder>/node-modules/bootstrap/dist/js/bootstrap.js"></script>
     </head>
     <body>
       <!-- ... -->
     </body>
    </html>
  7. Write some CSS/HTML and enjoy!

    <!-- ... -->
    <body>
     <div class="container">
       <h1 class="type-brand-1 em-high">Hello world!</h1>
     </div>
    </body>
    <!-- ... -->
  8. Upgrade PUI frequently

    npm update pui-css-all
    dr-frankenstyle <path-to-your-asset-build-folder>

NB - You must rerun Dr. Frankenstyle after you update PUI (or add any additional CSS module).

Customizing your PUI build (without React)

If you don't want all of Pivotal UI, you can install only the modules you will need. This will make your resultant CSS smaller! Let's say you're building an app that only has typography and buttons.

  1. Remove the pui-css-all module from your project.

    npm uninstall --save pui-css-all
  2. Add the necessary PUI CSS modules. For this example

    npm install --save pui-css-typography
    npm install --save pui-css-buttons

    Use the styleguide to determine which modules you need to install. Each component contains module information at the beginning of its docs:

    Example of styleguide installation instructions

  3. Rerun Dr. Frankenstyle

    dr-frankenstyle <path-to-your-asset-build-folder>
  4. Every time you install a new PUI CSS package, you will need to rerun Dr. Frankenstyle.

    If you're using gulp or grunt or some other task runner, look at the Dr. Frankenstyle docs for how to make this step part of your task workflow.

Contributing

Github repo

If you want a feature added to Pivotal UI, or you've found a bug that needs fixing, please refer to our contribution guidelines.

Highlights

When creating a pull request, make sure you rebase your branch against our code base (upstream). Read our Commit guidelines! We have a very specific syntax for our messages.

This documentation generated using Hologram