patternfly / patternfly-design

Use this repo to file all new feature or design change requests for the PatternFly project

PatternFly 5

Install

• This assumes an environment is already set up for npm packages - if not, please use npm init following the steps at https://docs.npmjs.com/getting-started/using-a-package.json.
• run npm install @patternfly/patternfly --save

When you install PatternFly 5, the package includes:

• a single file for the entire compiled library: node_modules/@patternfly/patternfly/patternfly.css
• individual files with each component compiled separately: node_modules/@patternfly/patternfly/<ComponentName>/styles.css
• a single file for the entire library's source (SASS): node_modules/@patternfly/patternfly/patternfly.scss
• individual files for each component's source (SASS): node_modules/@patternfly/patternfly/<ComponentName>/styles.scss

Any of the files above are meant for use in consuming the library. The recommended consumption approach will vary from project to project.

Development

PatternFly 5 Development requires Node v16.0.0 or greater

To setup the PatternFly 5 development environment:

• clone the project
• run yarn install from the project root
• run yarn start
• open your browser to http://localhost:8001

After working on your contribution, check for accessibility violations.

Create components, layouts...

To create source file scaffolding for a new component, layout, utility, or demo, run the NPM script:

node generate <CamelName>

Below are the full options for this script:

Options:
  -f, --folder <folder>  Source folder (components, demos, layouts, or utilities) (default: "components")

Examples

To create a "Test component" component (.pf-v5-c-test-component), run:

node generate TestComponent

To create a "Test layout" layout (.pf-l-test-layout), run:

node generate TestLayout -f layouts

To create 3 new demos named "Test demo", "Test demo 2", and "Test demo 3", run:

node generate TestDemo TestDemo2 TestDemo3 -f demos

Update screenshots

When making visual changes to a full page example, new example preview screenshots must be generated. To update the screenshots:

• open a terminal and run yarn build && yarn serve
• in another terminal, run yarn screenshots

Guidelines for CSS development

• For issues created in Core that will affect a component in PF-React, a follow up issue must be created in PF-React once the Pull Request is merged. The issue should include the Core PR #, the Core Release, a link to the component in https://core-staging.patternfly.org, and information detailing the change.
• If global variables are modified in Core, a React issue should be opened to address this.
• CSS developers should ensure that animation is well documented and communicated to the respective React developer.
• Once the component/enhancement is complete it should receive sign off from a visual designer who can then update the master sketch file with any changes.

Handlebars guidelines

For information on how to contribute, refer to our guidelines.

CSS/Sass guidelines

For more information on using CSS and Sass, refer to our guidelines.

Custom icon guidelines

For more information on custom icons, refer to our guidelines.

Beta components

When creating a brand new component, it should be released as beta in order to get feedback.

Testing for accessibility

PatternFly uses aXe: The Accessibility Engine to check for accessibility violations. Our goal is to meet WCAG 2.0 AA requirements, as noted in our Accessibility guide.

How to perform an accessibility audit with aXe

aXe is available as either a browser extension or npm script.

To run the a11y audit locally:

• install the latest chromedriver and ensure its available on your system $PATH
  • macOS users can simply brew cask install chromedriver
• open a terminal and run yarn build && yarn serve
• in another terminal, run yarn a11y

The tool is configured to return WCAG 2.0 AA violations for the full page renderings of all components, layouts, utilities, and demos. The tool will provide feedback about what the violation is and a link to documentation about how to address the violation.

The same tool is also available as a browser extension for Chrome and Firefox.

Fixing violations

Ignore the violations that aren’t related to your contribution.

Fix violations related to your contribution.

If there are violations that are not obvious how to fix, then create an issue with information about the violation that was found. For example, some violations might require further discussion before they can be addressed. And some violations may not be valid and require changes to the workspace or tooling to stop flagging the violation.

If you have any suggestions about ways that we can improve how we use this tool, please let us know by opening an issue.

FAQ

CSS Variables

How do I use CSS variables to customize the library?

Browser support

PatternFly 5 is supported on the latest two major versions of the following browsers:

• Chrome
• Firefox
• Safari
• Edge

patternfly-design's Issues

Info Tip example outdated/inconsistent

The example shown on this page: http://www.patternfly.org/pattern-library/widgets/#info-tip was superseded by the Notification Drawer and new masthead design and should be revised. Furthermore, an Info Tip is just a general pop-up that is not specifically associated with messages or notifications so this example is misleading.

Table View: Table View is presented differently from Card and List views

The pattern library currently includes three parallel view types for presenting summary level content: Card, List, and Table views. Card and List views are presented as full page examples to show how this view can be used in the context of a page. Table View is presented as a stand-alone pattern without additional context. Table view seems to focus more specifically on behaviors associated with data tables.

Recommendation: Create a full page Table View pattern that shows how a table can be used for a summary view similar to List or Card views. Separate out details of data table interaction into a new pattern as tables may be useful in a variety of view contexts.

List View: Inconsistent behavior for row expansion

Behavior for row expansion is inconsistent between HTML and Angular implementations. HTML expands when clicking the row. Angular only when clicking the caret icon. Design is closer to HTML implelmentation.

Table View: Remove unnecessary headers

Remove the section title called "Overview" on the overview tab. Remove the example header called "Default Table". It's not necessary and we can just show the screenshot. http://www.patternfly.org/pattern-library/content-views/table-view/#/_

Trend Card: Design tab has unnecessary dashes included

On the Trend Card page: http://www.patternfly.org/pattern-library/cards/trend-card/#/api
There are "-" listed after all the labels and should be removed.

* List View: Data Toolbar should be Toolbar

On the list view page [1], replace all instances of "Data Toolbar" with "Toolbar" and link them over to the Toolbar pattern here: http://www.patternfly.org/pattern-library/forms-and-controls/toolbar/

[1] http://www.patternfly.org/pattern-library/content-views/list-view/#/api

* Link to line chart from the Bar Chart pattern

Upon mention of the "line chart", the bar chart pattern (https://github.com/patternfly/patternfly-design/blob/master/pattern-library/data-visualization/bar-chart/design/overview.md) should link to it (http://www.patternfly.org/pattern-library/data-visualization/line-chart/#/api).

"Line Chart" should has have header style capitalization.

Toast Notifications: Capitalization bug

All instances of "Toast notifications" on the Overview page should be "Toast Notifications"
http://www.patternfly.org/pattern-library/communication/toast-notifications/#/api

List View: Example in Overview page is too wide to fit container

The example used in the Overview page for List View is too wide to fit in the page template and therefor wraps. It therefore looks different when opened in a separate window.

Recommendation: Redesign the example so it fits.

List View: Inconsistent/incomplete examples between HMTL/CSS and Angular

The Angular implementation does not present row variations as does the HTML/CSS example. There is also no guidance on how these variations can be used, what types of element are available and how they can be defined.

Recommendation: Provide more context for examples and explain general template that should be used to format list items. This would promote better consistency between designs that use list view. Create consistent HTML and Angular examples that implement these variations.

* Table View: Data Toolbar should be Toolbar

On the table view page [1], replace all instances of "Data Toolbar" with "Toolbar" and link them over to the Toolbar pattern here: http://www.patternfly.org/pattern-library/forms-and-controls/toolbar/

[1] http://www.patternfly.org/pattern-library/content-views/table-view/

Forms Patterns: Numerous inconsistencies between Forms design and other patterns

The Forms pattern has numerous inconsistencies with other patterns in the library. Some specific issues are:

• Inconsistency between button usage in examples and other button guidelines in PatternFly.
• Inconsistency between labeling recommendations between Forms and Form Field Layout pages.

Current Forms pattern only addresses simple data entry forms focusing on modals.

Recommendation: Entire Forms section should be reconsidered using a top-down approach. What are the patterns we need? How do we leverage existing work that was done? Where are the gaps.

Bar Chart: Interactive Legend should be a sub-bullet

On this page - http://www.patternfly.org/pattern-library/data-visualization/bar-chart/#/api

Right now it looks like:
Legend: It is recommended to include a legend to define the colors on the chart. On the bar chart, the legend may be located left aligned and underneath the chart or left aligned and to the right of the chart. - Interactive Legend (optional): Clicking on a series in the legend should toggle the visibility of the series in the chart.

and should look like...

• Legend: It is recommended to include a legend to define the colors on the chart. On the bar chart, the legend may be located left aligned and underneath the chart or left aligned and to the right of the chart.
  • Interactive Legend (optional): Clicking on a series in the legend should toggle the visibility of the series in the chart.

Fix templates to include proper format for links

I used the template, which has relative links. Can we update the templates to have the correct format @cshinn ?

Document capitalization recommendation for kebab menu items

The PF kebab example (https://www.patternfly.org/pattern-library/widgets/#kebabs) shows sentence style capitalization for menu items.

In PF T&W (http://www.patternfly.org/styles/terminology-and-wording/) the section for Capitalization for Common Components - it doesn’t talk about capitalization for menu items. But it does say to use Headline capitalization for Button labels. My thought would be Headline would be used for menu items as well.

Could the appropriate recommendation be added to the documentation?

Heat Map should be capitalized

• All instances of "heat map" should be "Heat Map" on the Overview tab
• Instead of referring to "a" heat map, we want to refer specifically to our heat map. Therefore...
  • Instead of "A heat map is a visualization of objects as blocks in a grid.", change to "The Heat Map is a visualization of objects as blocks in a grid. "
  • Instead of "When heat map items become so...", change to "When the Heat Map items become...."
  • Instead of "The most common use cases for a heat map are:", change to "The most common use cases for the Heat Map are:"

http://www.patternfly.org/pattern-library/data-visualization/heat-map/#/api

Utilization Bar Card: Internal inconsistencies between design and implementation

The are various inconsistencies and omissions between design, HTML, and Angular examples. These include:

• Angular examples do not include top-labeled bars as per HTML example and design.
• Tooltip styles are inconsistent between HTML and Angular example. HTML chart does not display PatternFly standard tool tips.
• Examples do not consistently express utilization in bar labeling.

There is also no reference to bar labeling in design description and when to use top labeled vs. left/right labeled bars or explanation of color coding.

Masthead update

Re masthead, Kyle confirmed that the following example is outdated and should come off the PF site: http://www.patternfly.org/pattern-library/navigation/horizontal-navigation/horizontal-navigation.html#

In the Vertical Navigation Pattern, we are missing a link to the new Masthead pattern

Here is the PR for the new Masthead pattern: https://github.com/beanh66/patternfly-design/blob/fb4b2e134405ed5006fe30620b584a7a50437fdb/pattern-library/application-framework/masthead/masthead_overview.md

Aggrgate Status Card: Need more specific guidance for using multiple status icons in the same card

Current documentation does not explain what to display if multiple conditions are being shown in a card and only some of them are reporting conditions that need attention (others are OK). Documentation only addresses what to show if everything is shown or if everything is running OK.

* remove unnecessary folders from card folder

Card does not have any information for discovery or usability testing so it's not necessary to have those template .md files or folders in there. See: https://github.com/patternfly/patternfly-design/tree/master/pattern-library/card

Dashboard Card (Base): Needs further elaboration

The Dashboard Card (Base) pattern is intended as a general container for other dashboard cards, but the relationship between this pattern and other dashboard card patterns in unclear. These is also redundancy between the documentation of features that may be part of the card base pattern (like the time frame filter) rather than the card content itself. This seems like a perfect opportunity for modularization where all dashboard cards are constructed from a consistent base container and additional charts.

There are also inconsistencies between design page and examples around Title formatting. Design says Title is always followed by a horizontal separator, but this is not true in all examples.

Capitalization bug

In the overview section, "aggregate status card" should be "Aggregate Status Card"
http://www.patternfly.org/pattern-library/cards/aggregate-status-card/#/api

Wizard: No need for "Example" header

Remove the section header called "Example" on the overview page. http://www.patternfly.org/pattern-library/communication/wizard/#/api

Vertical Navigation: Pin feature available for Tertiary Navigation only

The optional Pin feature is documented as part of Tertiary Navigation, but wouldn't this feature be just as valid for 2 levels of navigation?

Also, not sure that the icon used for Pin is what we ended up with. Pin feature is not demonstrated in any of the examples.

Bullet Graph need to be capitalized

http://www.patternfly.org/pattern-library/data-visualization/bullet-chart/#/api

On the overview page, "bullet graph" should be "Bullet Graph"

* drag-and-drop filenames are incorrect

the design and overview files in the drag-and-drop folder are incorrectly named.
Currently, they are called drag-drop_design.md and drag-drop_overview.md; they should be called design.md and overview.md

Buttons in modal examples in the form pattern should be updated

The buttons in the modal examples in the form pattern (link is below) should be updated.https://www.patternfly.org/pattern-library/forms-and-controls/forms/#_

• "Save changes" should be changed to "Save" ( or at a minimum "Save Change" with initial caps)
• "Close" should be changed to "Cancel", since this is canceling the operation not just closing the modal

Bar Chart: "-" should be removed

On the design tab (http://www.patternfly.org/pattern-library/data-visualization/bar-chart/#/api), after item "5. Bar:", there is a bug because "Interaction" has a "-" before it. I think it was supposed to be a sub-bullet.

It should look like...

• Bar:
  • Interaction:
    • If drill down behavior is supported, clicking on a bar will navigate to the appropriate page.
    • If supported, right clicking on an bar will bring up a menu with associated actions. If you are using a grouped bar chart, right clicking on a group will bring up a menu with associated actions for that group.
  • Width: All bars should be the same width.
  • Color: For recommendations on fill colors, see the Color Palette.
  • Height: Bar height in vertical charts is the dimension that represents its value.
  • Spacing: Spacing between bars should be equal. In the case of grouped charts, increase the spacing between main categories.

Login Page: Formatting issues

There is some problems with the formatting on the Login page under the Notifications section. See: http://www.patternfly.org/pattern-library/application-framework/login-page/#/design

wrong screenshot on form field layouts page

http://www.patternfly.org/pattern-library/forms-and-controls/form-field-layouts/#/api

The section for left aligned labels has a screenshot that shows top aligned labels instead

Trend Card: Overview and Examples titles are not necessary

Remove the h1 titles "Overview" and "Examples"
http://www.patternfly.org/pattern-library/cards/trend-card/#/api

* Update About Modal pattern to remove "description"

Remove "description" from the About Modal https://github.com/patternfly/patternfly-design/blob/master/pattern-library/communication/about-modal/design/design.md

List View/Card View: Drill-down behavior needs clarification

Existing documentation is not clear about how to handle drill-down if multiple elements within a list item or card are linked. Current guidance that a single click on a list or card item should drill down to the next level may not be sufficient for all use cases.

Recommendation: Consider cases where there may be multiple drill-down links and how one should handle this case vs. single drill-down link.

* Remove unnecessary folders from heat map

Heat map does not have usabiilty tests or discovery so those folders should be removed. See:
https://github.com/patternfly/patternfly-design/tree/master/pattern-library/data-visualization/heat-map

Dashboard Card (Angular): Footer link does not display hand cursor

In Angular example, footer link does not display hand cursor on hover. See example for Footer with Link & Timeframe filter

Donut chart should be capitalized

On the Overview tab for the Donut Chart, all instances of "donut chart" should be "Donut Chart"
http://www.patternfly.org/pattern-library/data-visualization/donut-chart/#/api

* Incorrect capitalization on design.md for Area Chart callouts

"Grid lines:" (the second bullet) should be "Grid Lines:" http://www.patternfly.org/pattern-library/data-visualization/area-chart/#/api

* consolidate the cards and a card folder

There should not be a cards AND a card folder under the pattern-library. add the design folder for "card" underneath the "cards" folder and removed the "card" folder from the pattern-library

Trend Card: Internal inconsistencies between design examples and implementations

There are multiple inconsistencies between trend card design examples and Angular implementation examples. Some of these include:

• Treatment of card with single trend and card with multiple trends are inconsistent in appearance of card title, placement of time frame selector, and placement of text labels.
• Treatment and placement of card titles differs between examples.

Utilization Trend Card: Unclear what label in center of donut chart should reflect

No guidelines on what the value in the center of the donut chart should report. Examples show either Available or Used value, but what is preferable and when?

Empty State: remove necessary title

Remove the title "Example" from the overview page
http://www.patternfly.org/pattern-library/communication/empty-state/#/api

Please add description of what patternfly-design repo's intended use. -thanks

Card View: Inconsistent appearance and behavior between HTML and Angular implementation

In the Card View pattern, the HTML and Angular implementations don't match. HTML follows the design in terms of form and function. Angular implementation lacks formatted card contents and supports selection options that are not described in the design.

Recommend to update Angular card appearance and clarify selections model (updating the design if necessary).

Broken resource links

Same issue as patternfly/patternfly#607, jquery.matchHeight-min.js has changed location.

However there are also some pages that pull resources from CDNs and I suppose that's not what you want. Changing those would require further synchronization with patternfly-org.

Login page images are broken

http://www.patternfly.org/pattern-library/application-framework/login-page/#/api

List view design doc link to Pagination incorrect

The list view design documentation has the following:

"Pagination: Card view can also support pagination. See Pagination for more details."

Should say Card view instead of list view. Link goes to github instead of the pattern on the site.

Vertical Navigation: Examples are for 2-Level nav only

While the design page includes for 2-Level (Secondary) and 3-Level (Tertiary) navigation options, the examples on the Overview and Code pages are only for 2-Level Nav.

* Remove the word "Overview" as it's redundant on Heat Map pattern

Remove the word "Overview" as it's redundant on Heat Map pattern https://github.com/patternfly/patternfly-design/blob/master/pattern-library/data-visualization/heat-map/design/overview.md

Toolbar pattern needs added to the repo

http://www.patternfly.org/pattern-library/forms-and-controls/toolbar/#_