wfp / designsystem Goto Github PK

WFP UI Bootstrap theme needs an update, to ensure visual similarity to WFP UI.

• Copy a Bootstrap sample page markup (http://getbootstrap.com/examples/theme/) and include it in the docs as an external file bootstrap.html;
• Load WFP UI Bootstrap theme and verify visual integrity of all components, in comparison to WFP UI.

• Add the following NPM modules:
  • autoprefixer-core
  • bower;
  • grunt;
  • grunt-cli;
  • grunt-postcss;
  • grunt-sass;
  • node-sass;
  • grunt-contrib-jshint;
  • grunt-contrib-watch;
• NPM manifest needs to have the flag private set to true;
• Add the following to .gitignore:
  • node_modules;
  • dist (future temp dir for pushing dist-ready CSS to CDN);
• Add NPM-specific, and Grunt-specific files to Bower's ignore list in bower.json;
• Improve Bower manifest, based on bower.json docs;

Currently, select elements do not look like pulldowns, due to how all default form elements are being reset via CSS. The design needs to solve this.

Bower installs to _components.

• Remove .bowerrc
• Update dependency reference paths

Currently, certain icons give little to no indication of their general purpose, such as query-builder instead of time, etc.

Icon names should be scrutinised and adjusted if necessary.

Currently the wfp/ui does not have a hide class that is supported by screen readers.

Bootstrap solution:

.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0,0,0,0);
    border: 0;
}

However, there are more comprehensive options shown in the third source:

.element-invisible {
  position: absolute !important;
  height: 1px; width: 1px; 
  overflow: hidden;
  clip: rect(1px 1px 1px 1px); /* IE6, IE7 */
  clip: rect(1px, 1px, 1px, 1px);
}

• Create hide class in _utility.scss

Source:
http://getbootstrap.com/
http://stackoverflow.com/questions/1755656/displaynone-vs-visibilityhidden-vs-text-indent9999-how-screen-reader-behave-w
http://snook.ca/archives/html_and_css/hiding-content-for-accessibility

Grunt tasks for consideration:

• build
  Build a dev-ready version with a sass map, process it via PostCSS (with a supporting map).
• dist
  Build a production-ready version without a sass map, process it via PostCSS (without a map), and get its JavaScript checked via JSHint.
• watch
  Automate building upon detecting changes in the file system, by using grunt-contrib-watch module.

We need documentation to use relative paths, to avoid problems when juggling URLs and paths on CDN.

Reference:
http://ricostacruz.com/til/relative-paths-in-jekyll.html

From Marco:

• Breadcrumps Home element padding has different behavior if the breadcrumbs list is made of 1 or n elements.

To ensure we can use spacing elements that conform to the same sizing standards as buttons (for example, for pagination [...] ellipsis elements, we need a totally transparent button, using following spec:

.not-button {
  color: #404040;
  border-color: transparent;
  background-color: transparent;
}

The style and hover effect applied makes it seem as if the ellipsis is clickable (like the numbered pagination buttons).

As the ellipsis is not clickable, it should look distinct from the numbered pagination buttons. See wfp/wfp-theme-d8#21 for details.

Following the addition of automated build tests via Travis CI, it would be good to add automatic deployments to the CDN to the stack for the master branch.

Docs

• CDN location: /guides/ui;
• Deployment source: /dist/docs;
• Grunt task: docs-dist;
• Jekyll config: /docs/_config.yml;

WFP UI

• CDN location: /libraries/wfpui/{tag};
• Deployment source: /dist, excluding /dist/docs;
• Grunt task: dist;

Tasks:

• Auto-deployment for WFP UI
• Auto-deployment for WFP UI Docs

In order to get an overview of the UI Kit files and structure,it would be useful to have:

• A listing of the directories and important files
• A listing with links to the CDN version of the files

• Checked checkbox references an invalid path;
• Checkboxes should use inline icons from the available SVGs;
• Checkbox classes checkbox should be available in the input itself and documented;
• Checkbox icon has dark background instead of white;

Updated 04/02/2016

• Outlines need improvement in terms of accessibility
• Current implementation does not work/look properly across browsers

In order to quickly assess and test the UI Kit implementation, we should create add a basic, single HTML page which implements all of the components of the UI Kit.

The HTML page should reference the built, local CSS files.

Example

test.html.txt is basic attempt I made (warts and all) based on a previous version of the UI Kit which could be used as a starting point / suggested approach.

As a UN organisation, we need to be accessible.
This example looks good: https://playbook.cio.gov/designstandards/visual-style/#text-accessibility

More research is needed to gather all the facts.

Use the following packages for inclusion in devDependencies:

• grunt-sass-lint

To improve compatibility with other frameworks, we need to prefix all classes with wfp-. This applies to:

Components

• Buttons
• Forms
• Tables
• Menu
• Breadcrumbs
• Pagination
• Segmented Control
• Flyout (not documented yet)

Layouts

• Masthead
• Primer (not documented yet)
• Footer (not documented yet)

Modules

• Grid
• Grid Units
• Utility

We should look into moving all CSS class declarations into a separate SCSS document, and apply the prefix globally via SCSS.

This issue depends on #5 to be completed first.

It has been noted that there are several sizes of icons which are not being supported by the UI Kit at present.

For example:

• 192x192 for Android
• 180x180 and 60x60 for newer iPhones
• Possibly even 96x96, 32x32 and 16x16 for Safari and others - to be investigated.
• Research current best practises for favicon formats & sizes.
• Incorporate new sizes into UI Kit.
• Deprecate any unneeded sizes from UI Kit.

@andrewholgate suggested using ESLint instead for JSHint for testing, and I totally back that up, as ESLint seem to be the new standard, but also surpasses JSHint in several areas:

• It's extensible, with many plugins available;
• Its output is easier to understand;
• Includes rules not available in other linters;
• It's future proof, with best ES6 support so far;

Note
Please, port the initial configuration from JSHint to ESLint during the implementation.

To make sure all our releases are ready for prime time, it would be great to integrate this repository with Travis CI. This will let other developers using our repository know, that it is stable and well-maintained for integration with their projects.

The following Grunt tasks will have to be tested:

• grunt build
• grunt dist
• grunt docs-build
• grunt docs-dist

This issue should be re-opened, if any additional tasks/checks need to be added to the Travis CI build.

Current implementation of breadcrumbs uses a flat visual hierarchy. This was a justified approach when IE8 couldn't handle CSS-only implementation of arrows, but since WFP UI now supports IE11+, it makes sense to update the breadcrumbs component from this:

To something more like this:

New UI icons are needed. If any more are required, please add them to the list below.

• share eg.: https://design.google.com/icons/#ic_share
• link eg.: https://design.google.com/icons/#ic_link
• link-external eg.: https://design.google.com/icons/#ic_open_in_new
• download eg.: https://design.google.com/icons/#ic_file_download
• upload eg.: https://design.google.com/icons/#ic_file_upload
• edit eg.: https://design.google.com/icons/#ic_mode_edit

Check and add/update all CDN references to the following resources/assets:

• Fonts
• Favicons (done as part of #43)
• Thematic icons
• UI Icons

Buttons need a visual overhaul, as there have been concerns about their similarity to other form elements, especially inputs. In addition, we need to bring back some slight affordances to make those buttons stand out more from other UI elements. This will positively impact accessibility.

The 0.7.0 documentation makes reference to the Responsive Nav JS library.

This library is not available in the repo nor part of the grunt build.

This will be tricky, because markup changes are by nature volatile and not backwards-compatible.

"Look and feel" changes should be considered for the major version change, when it comes to the UI kit. I would treat this with a bit more complexity:

• if a look & feel changes significantly along with markup and/or CSS classes, it's a major change;
• if a look & feel significantly changes, not affecting the way markup and/or classes are applied to it, then it's a minor change;
• if a look & feel changes are minor, it's a patch change (for example to add small affordances, like shadows, etc);

This needs to be defined, possibly on the homepage, and in the readme.md for future reference.

Icon fonts pose a huge accessibility issue for people with certain vision deficiencies.

People with dyslexia often have special software or fonts installed on their operating system, which override web fonts specified by websites and applications, in order to increase their readability.

More on the issue:

• http://www.sitepoint.com/final-nail-icon-fonts-coffin/
• https://speakerdeck.com/ninjanails/death-to-icon-fonts

Header for public-facing sites, including the WFP logo, etc. Use extended, standard and emblem logos depending on media query.

Depends on #45.

• Design external header component
• Implement the new component
• Document implementation/usage of the new component under .wfp-header-ext

The idea to merge wfp/ui-guide into wfp/ui could be implemented in the following way:

• Move wfp/ui-guide to a docs directory in the root of wfp/ui;
• Trim, restructure and optimise the docs, using wfp/ui as a guide to what's available and what is not;
• Generate docs to dist/docs directory, ready for upload to the CDN.

Some components from the UI Guide should get reimplemented in the UI kit, such as the offscreen navigation.

Based on the all new tests implemented via sasslint, we need to fix issues outlined by this tool in the codebase.

Some issues are not directly fixable, as the depend on third-party components, such as grunt-datauri. Such issues should be omitted and/or reported to a given tool maintainer, if they haven't been reported already.

# Use the following command to test SCSS without rebuilding all sources
$ grunt sasslint

Add automated TravisCI tests for the following aspects of the UI Guide HTML:

• Accessibility audit of pages to ensure they are WCAG2AA compliant (use pa11y) Ref #57
• Audit links and image src's to ensure they are valid (use broken link detector)

This repository needs a readme.md file, to ensure people who intend to use it, know how to perform all the things this package can/will do.

Icons are not showed up correctly

<i class="icon-home"></i>

Static files needs to be gone, in order for us to be able to introduce dynamic build toolkit via Grunt.

Files to remove

• wfpui.css
• wfpui.min.css
• wfpui.min.scss

We'll have three patterns for the footer:

• Minimal
• Compact
• Standard

To ensure documentation follows the most recent wfp-ui release, it should include its version number in the title, such as on the screenshot above. The version should be updated only if a new release is pushed.

When checkboxes and radios are rendered with labels displayed after inputs (instead of inputs being wrapped inside labels), they are not being displayed inline.

Example

<input type="checkbox" id="edit-user-email-verification" name="user_email_verification" value="1" checked="checked" class="form-checkbox">
<label for="edit-user-email-verification" class="option">Require email verification when a visitor creates an account</label>

Grids are an important part of this package and need to be documented, in order for implementers to be able to use them effectively.

• How grids work in WFP UI
• Basic usage
• Advanced layouts
• Samples

Currently, footer--links subcomponent is only available inside footer--compact and footer--std, but it should be available also within footer--mini.

This is to ensure consistency in displaying links, even within smaller footers.

This pattern is not entirely consistent across different implementation. We need to radically improve this pattern with the following principles in mind:

• Accessibility (ARIA preferable, appropriate HTML structure);
• Performance (CSS-only preferable to JavaScript implementation);
• Responsive (is accessible for different viewport sizes);

The following style should be adopted (and possibly improved upon):

The State of wfp/ui

Over the past year, we've been trying to create a fairly universal package/library of UI styles and components for inclusion in both, offline, and online web projects, such as WFP Give, or WFP.org.

Due to the fact that no web project is made equal, and some use a lot of different ways of including sources, we cannot continue to ship this package with precompiled or minified files, ready for production, because this creates an enormous amount of work for maintainers (currently, only me).

In addition, it has no real benefits for others, since the static precompiled CSS and JS (in the future), would end up on CDN anyway, which currently is done manually with a Shell script.

New World Order

In order to solve the above issue, and focus on providing a stable UI framework in a handy package, we should:

• Remove all static, precompiled, and minified CSS & JS sources (if any);
• Focus on providing new and updating existing components;
• Serve as a package for inclusion in web projects (via bower.json);
• Serve as a package for building static sources for CDN (via Gruntfile.js);

Ideas

• Keep wfp/ui as a Bower-only package, and use a separate repo for CDN-only builds (this could include .sh files and other bits);
• Make wfp/uiinto a universal package for both, inclusion in web projects (via Bower), and for building/deploying CDN-only static sources (via NPM/Grunt);

Feel free to chip in with your comments and observations.

The project is using different and outdated file comments. These should be updated and standardise project-wide

For example, the following are different and one is out-of-date:

• https://github.com/wfp/ui/blob/v0.7.0/dist/css/bootstrap-theme.css#L2-L4
• https://github.com/wfp/ui/blob/v0.7.0/dist/css/wfpui%2Bgrid.css#L2-L7

The standard file comment format we propose to use is (as an example for wfpui+grid.css):

/*!
 * WFP UI with grids, v0.7.0
 * Copyright 2016 WFP/Matthew Morek
 * License: https://github.com/wfp/ui/blob/master/LICENSE
 */

Since WFP UI is full of useful resources, we should prepare and add all variants of the WFP logo.

• Include required source files (all languages)
• Output logos as PNGs
• Output logos as SVGs
• Add documentation for implementing logos via srcset attribute inside img tag

Due to how much some developers like to use Bootstrap as their main framework, we need to ensure they can benefit from having similar, if not the same UI without using WFP UI Kit. This is because both frameworks are not entirely compatible.

Fortunately, Bootstrap has use of bootstrap-theme.css which acts like a "skin" for the framework, and if loaded after the main bootstrap.css, it overrides Bootstrap's original styles.

The best way to include it in the build process, might be to use a separate SCSS file (bootstrap-theme.scss), which would depend on the WFP UI Kit.

Using the form components from: http://cdn.wfp.org/guides/ui/v0.8.0/components/forms/

I adding required="required" to the following fields:

• "Email address"
• "Pick a subject"
• "Your message"

This was the output:

Observations

1. required fields do not look significantly clear that they are required to be completed.
2. Not all elements visually change when they are required (eg. select lists and others too).
3. There are no documented examples of required="required" being used on the UI Guide.

This is quite important, as essentially, WFP UI Kit runs on PureCSS, so there's no need for additional override classes.

The library is stable enough for us to absorb it fully and lose pure- namespace prefix from CSS classes, in favour of wfp-, giving us more control over the way things work, look, and feel about this UI kit as a result.

The initial version to integrate is the latest stable: v0.6.0: https://github.com/yahoo/pure/releases/tag/v0.6.0

Components to integrate:

• Base
• Grids
• Buttons
• Forms
• Tables

In order to benefit from consistent implementation of UI and Thematic icons in WFP UI, Grunticon seems to be the best tool for managing our SVG-based workflow, out of many different approaches.

I am regularly having to send links with references specific sections of the guide, such as http://cdn.wfp.org/guides/ui/v0.7.0/components/navigation/#inline-menu

The issue is that I need to manually add the target anchor id to the end (eg. #inline-menu).

It would be useful to implement anchor markers, as per this example for quick linking to the specific heading of the guide.

Marco has suggested moving assets directory under dist, as these resources are fairly static, and could be easily referenced from outside wfp-ui.

In this way we can just copy the content of the the dist folder without the need of picking in different place all the needed files to have wfp/ui working correctly. — Marco