Name: pivotal-ui
Owner: npm
Description: null
Created: 2016-01-27 18:28:21.0
Updated: 2018-04-14 05:28:00.0
Pushed: 2017-03-22 20:11:33.0
Homepage: styleguide.cfapps.io
Size: 40913
Language: HTML
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Pivotal UI is a collection of branded, ready-for-use UI components. Built on top of Bootstrap and React, this library contains everything you need to get started building UI at Pivotal.
To contribute, see the contributing readme.
If you're ready to try PUI with React, follow these instructions!
We're assuming that you have the following setup on your project:
Browserify or Webpack - Our React modules follow the CommonJS module pattern. You will need to use Browserify or Webpack to compile your javascript for use in the browser.
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 these instructions don't make sense to you, don't worry! We're working on a sample project template that we'll publish soon :grin:
Run npm init if you don't have a package.json file already.
Install Dr. Frankenstyle. This tool looks at your dependencies (those added with –save, NOT –save-dev), and compiles the CSS required by these packages.
install --global dr-frankenstyle
Install React, if you haven't already
install --save-dev react
Install a PUI module for the components you need. No need to install additional CSS packages. Our React packages tell Dr. Frankenstyle what CSS is needed for each component.
install --save pui-react-typography
install --save pui-react-buttons
Run Dr. Frankenstyle to compile your CSS to a folder (we use ./build/ but you can choose whatever makes sense for your project)
rankenstyle <path-to-your-asset-build-folder>
ites the compiled css to <path-to-your-asset-build-folder>/components.css
Add the compiled css to your html template
ctype html>
l>
ad>
title>...</title>
link rel="stylesheet" href="<path-to-your-asset-build-folder>/components.css">
ead>
dy>
!-- ... -->
script src="<path-to-your-project's-compiled-javascript-file>"></script>
ody>
ml>
Write some React!
Javascript:
React = require('react');
DefaultH1 = require('@npcorp/pui-react-typography').DefaultH1;
DefaultButton = require('@npcorp/pui-react-buttons').DefaultButton;
MyTestPage = React.createClass({
InitialState: function() {
eturn {showMessage: false};
wMessage: function() {
his.setState({showMessage: true});
der: function() {
eturn (
<div className="container">
DefaultButton onClick={this.showMessage}>Show Message</DefaultButton>
this.state.showMessage ? <DefaultH1>Hello world!</DefaultH1> : null }
iv>
;
t.render(<MyTestPage />, document.getElementById('root'));
HTML
... -->
y>
v id="root"></div>
- Script tag should be below all DOM elements -->
ript src="<path-to-your-project's-compiled-javascript-file>"></script>
dy>
... -->
Every time you install a new PUI React package, you will need to rerun Dr. Frankenstyle to update your compiled CSS.
install --save pui-react-alerts
rankenstyle <path-to-your-asset-build-folder>
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.
If you're not ready to try React, you can still use the HTML/CSS version of Pivotal UI!
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.
Run npm init if you don't have a package.json file already.
Install Dr. Frankenstyle. This tool looks at your dependencies (those added with –save, NOT –save-dev), and compiles the CSS required by these packages.
install --save-dev dr-frankenstyle
Install the Pivotal UI CSS modules
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.
Install jQuery and bootstrap.js
install --save-dev jquery
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.
NB - 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.
Run Dr. Frankenstyle to compile your CSS to a folder (we use ./build/ but you can choose whatever makes sense for your project)
rankenstyle <path-to-your-asset-build-folder>
ites the compiled css to <path-to-your-asset-build-folder>/components.css
Add the css and javascript files to your html template
ctype html>
l>
ad>
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>
ead>
dy>
!-- ... -->
ody>
ml>
Write some CSS/HTML and enjoy!
... -->
y>
v class="container">
h1 class="type-brand-1 em-high">Hello world!</h1>
iv>
dy>
... -->
Upgrade PUI frequently
update pui-css-all
rankenstyle <path-to-your-asset-build-folder>
NB - You must rerun Dr. Frankenstyle after you update PUI (or add any additional CSS module).
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.
Remove the pui-css-all module from your project.
uninstall --save pui-css-all
Add the necessary PUI CSS modules. For this example
install --save pui-css-typography
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:
Rerun Dr. Frankenstyle
rankenstyle <path-to-your-asset-build-folder>
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.
Coming soon!
If you really don't want to use NPM, you can use our compiled PUI monolith. Be warned, you will have to manage updates and dependencies yourself.
l>
ead>
<title>...</title>
<link rel="stylesheet" href="/path/to/release/pivotal-ui.css">
<script src="/path/to/release/pivotal-ui.js"></script>
head>
ody>
<p class='type-brand-1'>Hello, world!</p>
body>
ml>
You'll need to maintain the structure in the release directory to have fonts and assets work properly. Do not modify the release files directly. If you need a component and you cannot find it in the styleguide, write your own styles and javascript separately. Doing so will make it easier to update to newer versions.
If you are building CSS using Sass, you can get pivotal-ui variables and mixins from the pui-css-variables-and-mixins node module.
install --save @npmcorp/pui-css-variables-and-mixins
Import the file and use the variables:
ort '<path-to-your-projects-node-modules>/@npmcorp/pui-css-variables-and-mixins/pui-variables.scss';
ort '<path-to-your-projects-node-modules>/@npmcorp/pui-css-variables-and-mixins/mixins.scss';
special {
ckground-color: $brand-1;
If you want a feature added to Pivotal UI, or you've found a bug that needs fixing, please refer to our contribution guidelines.
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.
Copyright 2015 Pivotal Software, Inc. All Rights Reserved.