puppetlabs / design-system

A resource for creating user interfaces based on brand, UX, and dev principles

Puppet Design System

The Puppet Design System represents the behaviors, components, principles and visual presentation we share. It is based on our objective to provide consistency, efficiency, and quality experiences to our customers. With it, we scale design across departments, products, platforms, and time zones.

Visit the documentation and living styleguide at https://puppetlabs.github.io/design-system.

Quick start

Prerequisites

Currently, a POSIX environment like macOS or Linux is required for development. (For Windows, you can use Windows Subsystem for Linux.) You must install the version of Node specified in .nvmrc. We recommend using nvm (Node Version Manager), which allows you to nvm install the specified version and nvm use the specified version in the current shell (or nvm alias default to use the specified version in all new shells).

Local sandbox

The primary development environment uses Styleguidist (which is what is also hosted at https://puppet.style). You can run it locally to view the docs and play around with components using live editable code:

git clone [email protected]:puppetlabs/design-system.git && cd design-system
npm install
npm start

With an existing app

To add the main package, @puppet/react-components, to an existing project:

npm install @puppet/react-components

New app from scratch

To try out the design system from scratch, generate a new project with uikit:

npm install -g @puppet/uikit
uikit generate project my-project

Add components

import { Button } from '@puppet/react-components';
<Button>Hello world!</Button>

Use common styles

To use public Sass variables, add @puppet/sass-variables to your project:

npm install @puppet/sass-variables

Reference the public variables from your Sass files:

@import '~@puppet/sass-variables/index';
.my-text {
  color: $puppet-amber;
}

Note: See the Getting Started guide for a longer walkthrough with examples of using the uikit, React components, Sass variables, and other packages.

Packages

The Puppet Design System includes:

• Puppet React Components: Library of reusable React components packages/react-components
• Puppet React Layouts: Library of reusable React layouts like login screens packages/react-layouts
• Puppet Sass Variables: A set of public Sass variables for color palettes, typography, borders, etc. packages/sass-variables
• Puppet UI Toolkit: A uikit CLI for generating apps, components, etc. packages/uikit
• Puppet Design System Website: The website documenting the Design System packages/design-system-website

Contribute

The Puppet Design System is a cross-functional team effort across Puppet with shared ownership where contributions are welcome and encouraged. Read more in CONTRIBUTING.md.

Feedback

We are continuing to iterate on the Puppet Design System and appreciate your feedback and questions. Feel free to create an issue, pull request, or contact [email protected]. Puppet employees can follow along in Slack (#team-design-system) or Jira (PDS).

Release Notes

See the changelog for each package, like react-components' CHANGELOG.md.

design-system's Issues

Remove "approved by" tags from Styleguidist

Review design of Tags and, in particular, review implementation of clickable “x”

Secondary tab background is too dark

Sig: "It's meant to be n50 for the bg of the tab and the page"

Fix issues with Tag component

• Remove clickability from main body of removable tags
• Remove focus state from main body of removable tags
• Fix color on disabled tag
• The "x" on tags is too low

Define how Buttons should handle truncation and other responsiveness

Schedule card review session

Document transparent button with leading and trailing icons

Remove "Just in case" from Sketch styleguide

Fix icon button positioning for use with flexbox

Because an icon in the button component is absolutely positioned, there are issues when using them in flex containers.

Remove all "needs x" tags from Sketch styleguide

Fix Input examples so you can type in them

Use ⚠️ for <Alert type="warning" />

Nathan chatted with Sig about this. puppet-styleguide.sketch would need to be updated too, which currently has "i" icons for both info and warning alerts.

Update action menu name in design styleguide to action select

Update Small body to have 16px line height

Import Sass variables from react-components

Rather than duplicating Sass variables in the sass-variables package from react-components, we should import them during this transition period until react-components is fully merged into design-system.

Update color in action menu to match implementation: hover should not be blue, selected should be blue

Change form field spacing from 20px to 16px

Get new card specs into Sketch styleguide

Remove documentation of icon buttons with state

Clarify icon design designations

Clarify "Icons with a green background have been approved by Design. Scaled svgs (white background) should be OK'd before using."

Update H6 to have 16px line height

Document the ability to add custom SVGs to Icon component

Add Card.Actions example

Refactor folder structure

• Rename component folders to match component names, e.g. action-select would become ActionSelect.
• Use .jsx filename extensions for consistency with other projects.
• Move test files to live alongside the components they test.

Update badge colors to match design

Update badge colors to match design (e.g. green background)

Update progress buttons to have active background color

Create component for logs/code

We should create a component that can display (and ideally stream at some point) logs. It should be able to convert ANSI color escape codes into HTML, which can be done with a library like anser, ansi_up, and ansi-to-react.

Note: Right now, Nebula is reusing the CodeEditor component with mode="" to force no language for syntax highlighting, but embedding the Ace Editor is overkill for logs and a language of "" causes a 404 for mode-mode.js.

<CodeEditor readOnly mode="" darkMode showGutter={false} value={log} />

Remove note in Content component documentation about unimplemented elements

Update Sketch styleguide to match button select dropdown implementation width

Remove "writing content" from Content Sketch styleguide

Align design document and implementation for the carrot in Tooltip

Remove favicon documentation from Sketch styleguide

Update text in breadcrumb example

Use sentence case for "Details" in Breadcrumb: "Items > 11 > details"

Update Content docs

Fix "ol li has 8px bottom margin and a yellow number" to remove yellow reference

Update Sidebar profile icon color

Initial state of profile icon in Sidebar should be grey instead of amber

Warning alert should use ⚠️ icon

Corresponding engineering ticket: #13

Move unimplemented table features to roadmap

Update hover target of form field

Change hover target of form field to be parent so hovering on margin between label and input doesn't change style

Add contributing guidelines for adding an icon

Remove secondary link documentation from Sketch styleguide

Create section for alignment styleguide specs

Pull in Alignment styleguide specs from Sketch styleguide even though there are no code accompaniments

Remove Portfolio components page from Sketch styleguide

Table header text is the wrong color

Change "Badge" text to "Tag" in Sketch Tag example in the Sketch styleguide

Remove sticky tooltip from Sketch styleguide

Set up CI/CD for monorepo

https://tickets.puppetlabs.com/browse/PDS-233

Text area resize handle should match implementation

Update conventions and ESLint rules to match other projects

It should be easy to move packages back and forth between react-components, design-system, and other projects at Puppet like nebula-ui. Therefore, we should align our coding conventions, ESLint rules, and stylelint rules in these project to match.

If we decide to take Airbnb's config and follow the file naming convention elsewhere, we should rename files to be PascalCased with .jsx extensions if they include JSX.

Library template `npm run watch` fails if file is moved, requiring restarting the script

Reproduction steps:

• Run the library generator (uikit g library my-library, etc.)
• Run npm run watch
• Move a file
  • Note that the error below will be shown
• Update import statements to that file
  • Note that saving the file will no longer cause the watch script to update
• ctrl-c to exit the watch script
• Run npm run watch again and verify that the build gets fixed with no other changes

ERROR in ./src/Workflow.jsx
Module build failed (from ./node_modules/babel-loader/lib/index.js):
Error: ENOENT: no such file or directory, open '/Users/ward/src/design-system/packages/react-workflow/src/Workflow.jsx'
 @ ./src/index.js 1:0-34 3:0-20
^C
react-workflow (master *+) $ npm run watch

> @puppet/[email protected] watch /Users/ward/src/design-system/packages/react-workflow
> webpack --watch

clean-webpack-plugin: /Users/ward/src/design-system/packages/react-workflow/dist has been removed.

webpack is watching the files…


WARNING: We noticed you're using the `useBuiltIns` option without declaring a core-js version. Currently, we assume version 2.x when no version is passed. Since this default version will likely change in future versions of Babel, we recommend explicitly setting the core-js version you are using via the `corejs` option.

You should also be sure that the version you pass to the `corejs` option matches the version specified in your `package.json`'s `dependencies` section. If it doesn't, you need to run one of the following commands:

  npm install --save core-js@2    npm install --save core-js@3
  yarn add core-js@2              yarn add core-js@3

Hash: 1fa88f0febb4e948235d
Version: webpack 4.30.0
Time: 4290ms
Built at: 04/22/2019 9:28:25 AM
       Asset     Size  Chunks             Chunk Names
    index.js  103 KiB       0  [emitted]  main
index.js.map  538 KiB       0  [emitted]  main
Entrypoint main = index.js index.js.map

Remove character count and other spacing documentation from Content Sketch styleguide