Merge pull request #321 from IBM-Watson/develop

Release 1.0.0-rc.3

CHANGELOG.md

@@ -1,4 +1,19 @@
-# Watson Design Library Changelog
+# Watson Design Guide Changelog
+
+## v1.0.0-rc.3
+**May 15, 2015**
+
+**New**
+
+* Add visual examples for Accessibility
+* Add homepage
+* Add page load visual example for performance
+* Add `gray 30` to grayscale colors
+* Add styling for pattern list
+
+**Change**
+
+* :art: Clean up color and accessibility text
 
 ## v1.0.0-rc.2
 **May 14, 2015**

CONTRIBUTING.md

@@ -1,8 +1,8 @@
-# Contributing to the IBM Watson Design Library
+# Contributing to the IBM Watson Design Guide
 
-The Watson Design Library contains the design and development guidelines and resources for creating cognitive experiences. It's built using Sass and available via Bower, so it's easy to include all or part of it within a project.
+The Watson Design Guide contains the design and development guidelines and resources for creating cognitive experiences. It's built using Sass and available via Bower, so it's easy to include all or part of it within a project.
 
-_**Heads Up!** We love open source, but the Watson Design Library is unlikely to add new guidelines or features that are not in-line with the work we're doing or won't be used at IBM Watson. Inclusion is at the discretion of the Watson Design team. We really love to share, though, so hopefully that means we're still friends :blue_heart:_
+_**Heads Up!** We love open source, but the Watson Design Guide is unlikely to add new guidelines or features that are not in-line with the work we're doing or won't be used at IBM Watson. Inclusion is at the discretion of the Watson Design team. We really love to share, though, so hopefully that means we're still friends :blue_heart:_
 
 ## Navigating the Repository
 
@@ -14,24 +14,24 @@ The `language` folder contains all of the long-form text available and its relat
 
 ### Library
 
-The `library` folder contains all of the items needed to compile the content in the `language` and `patterns` folders into the Watson Design Library website. This includes site-specific Sass, JavaScript, configuration, and templates.
+The `library` folder contains all of the items needed to compile the content in the `language` and `patterns` folders into the Watson Design Guide website. This includes site-specific Sass, JavaScript, configuration, and templates.
 
 ### Patterns
 
 The `patterns` folder contains all of the UI patterns and their documentation. Development is being done following [North's](http://pointnorth.io/#website-building-blocks) naming conventions and best practices. Any code that does not adhere to North's conventions will be asked to be rewritten. The folder is divided in to four parts, [base](https://github.com/IBM-Watson/design-library/tree/develop/patterns/base#base-elements), [components](https://github.com/IBM-Watson/design-library/tree/develop/patterns/components#components), [layouts](https://github.com/IBM-Watson/design-library/tree/develop/patterns/layouts#layouts), and [core](https://github.com/IBM-Watson/design-library/tree/develop/patterns/core#core).
 
 No patterns rely upon JavaScript frameworks (jQuery, Dojo, Angular, etc…). Any pattern submissions that do will be asked to be rewritten without said dependencies. Acceptable JavaScript dependencies include core JavaScript that we provide and any current dependencies already included in the project. Any additional external dependencies will need to be approved before they can be used. Styling should be written without vendor prefixes. Only web standard features that have [moved beyond](http://en.wikipedia.org/wiki/World_Wide_Web_Consortium#Specification_Maturation) the Candidate Recommendation stage (or equivalent for the relevant standards body) will be considered for inclusion.
 
-## Developing for the Watson Design Library
+## Developing for the Watson Design Guide
 
-Whether working on language, library, or patterns, there are a specific set of steps that should be followed in order contribute in a standard and consistent manner. Our wiki contains the full instructions for [setting up and working with the Watson Design Library](https://github.com/IBM-Watson/design-library/wiki/Developing-for-the-Design-Library).
+Whether working on language, library, or patterns, there are a specific set of steps that should be followed in order contribute in a standard and consistent manner. Our wiki contains the full instructions for [setting up and working with the Watson Design Guide](https://github.com/IBM-Watson/design-library/wiki/Developing-for-the-Design-Guide).
 
 ## Submitting Issues
 
 * Before creating a new issue, perform a [cursory search](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aissue+user%3Aibm-watson+) to see if a similar issue has already been submitted.
 * Can create an issue [here](https://github.com/IBM-Watson/design-library/issues). Please include as many details as possible when filing an issue.
 * Issue titles should be descriptive, explaining at the high level what it is about, and should be written in the same style as [Git commit messages](#git-commit-messages).
-* Please include the version of the Design Library being used or viewed
+* Please include the version of the Design Guide being used or viewed
 * Do not open a [pull request](#pull-requests) to resolve an issue without first receiving feedback from a `collaborator` or `owner` and having them agree on a solution forward.
 * Include screenshots and animated GIFs whenever possible; they are immensely helpful.
 * When submitting a browser bug, please include the browser, version, operating system, and operating system version.
@@ -45,7 +45,7 @@ Whether working on language, library, or patterns, there are a specific set of s
 * Pull requests should reference their related issues. If the pull request closes an issue, [please reference its closing from a commit messages](https://help.github.com/articles/closing-issues-via-commit-messages/). Pull requests not referencing any issues will be closed.
 * Pull request titles should be descriptive, explaining at the high level what it is doing, and should be written in the same style as [Git commit messages](#git-commit-messages).
 * Update the [CHANGELOG](#maintaining-thechangelog) with the changes made by the pull request, making sure to use the proper [Emoji](#emoji-cheatsheet).
-* Make sure that the steps for [Developing for the Watson Design Library](https://github.com/IBM-Watson/design-library/wiki/Developing-for-the-Design-Library) have been followed
+* Make sure that the steps for [Developing for the Watson Design Guide](https://github.com/IBM-Watson/design-library/wiki/Developing-for-the-Design-Guide) have been followed
 * Follow our JavaScript and CSS styleguides. We have linters set up to catch most of it.
 * Ensure that [EditorConfig](http://editorconfig.org/) installed in the editor used to work on the library and that it is functioning properly.
 * Do not squash or rebase commits when submitting a Pull Request. It makes it much harder to follow work and make incremental changes.

README.md

@@ -1,9 +1,9 @@
-# Watson Design Library [![Issues In Progress](https://badge.waffle.io/ibm-watson/design-library.svg?label=In%20Progress&title=Issues%20In%20Progress)](http://waffle.io/ibm-watson/design-library) [![Build Status](https://travis-ci.org/IBM-Watson/design-library.svg?branch=develop)](https://travis-ci.org/IBM-Watson/design-library)
+# Watson Design Guide [![Issues In Progress](https://badge.waffle.io/ibm-watson/design-library.svg?label=In%20Progress&title=Issues%20In%20Progress)](http://waffle.io/ibm-watson/design-library) [![Build Status](https://travis-ci.org/IBM-Watson/design-library.svg?branch=develop)](https://travis-ci.org/IBM-Watson/design-library)
 
 
 ## Getting Started
 
-Development on the Watson Design Library is done in this repository. Patterns are developed in the `patterns/` folder, with enhancementsto the library itself and the language are added to the `library/` folder. The design library runs off of the [Watson Runner](https://github.com/IBM-Watson/runner), so work on that should be done there.
+Development on the Watson Design Guide is done in this repository. Patterns are developed in the `patterns/` folder, with enhancementsto the library itself and the language are added to the `library/` folder. The design library runs off of the [Watson Runner](https://github.com/IBM-Watson/runner), so work on that should be done there.
 
 ### Installation
 

bower.json

@@ -1,6 +1,6 @@
 {
-  "name": "watson-design-library",
-  "version": "1.0.0-rc.2",
+  "name": "watson-design-guide",
+  "version": "1.0.0-rc.3",
   "homepage": "https://github.com/IBM-Watson/design-library",
   "authors": [
     "Sam Richard <[email protected]>",
@@ -19,7 +19,10 @@
     "node_modules",
     "bower_components",
     "test",
-    "tests"
+    "tests",
+    "helper-apps",
+    "Vagrantfile",
+    "library"
   ],
   "dependencies": {
     "sass-toolkit": "~2.9.0",

language/02-guidelines/01-style/accessibility/index.md

@@ -24,16 +24,32 @@ variables:
     accessibilityAnimation:
       description: "When there is an animation that last longer than 5 seconds, provide the user a way to pause, stop, or hide the animation."
       visualDisplay: /videos/accessibility/motion-accessibility.webm
+  examples:
+    neutralAccessibility:
+      neutralYes:
+        title: "Accessible"
+        visualDisplay: /images/accessibility/neutral-yes.svg
+        sentiment: positive
+        description: "Primary: Blue 60, Accent: Teal 40, Neutrals: Neutral 20, Neutral 40, Gray 80"
+      neutralNo:
+        title: "Not Accessible"
+        visualDisplay: /images/accessibility/neutral-no.svg
+        sentiment: negative
+        description: "Primary: Orange 50, Neutrals: Neutral 20, Neutral 40, Gray 30"
 ---
 
 When choosing colors and contrast ratios for typography it is important to adhere to the [IBM Design Language recommendations for accessibility](http://www.ibm.com/design/language/framework/visual/color.shtml#contrast), as we must meet [WCAG 2.0 AA requirements](http://www.w3.org/TR/WCAG20/). High color contrast helps users who are partially or completely color blind see differences between certain colors. It creates a strong visual hierarchy and improved usability for everyone. Never rely on color as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.  
 
 {{ _detail.view(detail.accessibilityInteraction) }}
 
+Colors at a 50 value or lower are not accessible when applied to text on neutral backgrounds, unless the text is 24 px or larger. There are no formal color contrast requirements for icons or glyphs that are paired with supporting text. If an icon is used separately from supporting text on a neutral background, use a color value of 50 or higher.
+
+{{ _example.compare(examples.neutralAccessibility) }}
+
 ## Animation
 
 In addition to the fundamental visual accessibility guides, animation has its own set of considerations. For animations that are longer than five seconds, we must provide the ability to pause, stop, or hide animations for users who can be severely distracted, particularly those with attention deficit disorders.
 
 {{ _detail.view(detail.accessibilityAnimation) }}
 
-The five-second limit is long enough to get a user’s attention, but short enough for a user to wait out the distraction before reading the page. (2.2b) Do not include anything that flashes, or can be considered a flash, more than twice per second; it can negatively affect those prone to seizures. (2.3a) If the animation has audio longer than three seconds, provide audio control for users that have screen reading software, as it will make it easier for them to understand their screen reader. (1.4b)
+The five-second limit is long enough to get a user’s attention, but short enough for a user to wait out the distraction before reading the page. Do not include anything that flashes, or can be considered a flash, more than twice per second; it can negatively affect those prone to seizures. If the animation has audio longer than three seconds, provide audio control for users that have screen reading software, as it will make it easier for them to understand their screen reader.

language/02-guidelines/01-style/color/index.md

@@ -26,9 +26,9 @@ variables:
           Primary: Blue 30, Secondary: Orange 30, Accent: Teal 30
 
 
-          Consider users who are sensitive to brightness and high contrast colors by using a Gray value as a background color instead of pure black.
+          Consider users who are sensitive to brightness and high contrast colors by using a gray value as a background color instead of pure black.
   primaryColors:
-    instructions: "Choose a primary and secondary color"
+    instructions: "Choose a primary and secondary color."
     colors:
       - palette: Blue
         tone: 60
@@ -57,7 +57,7 @@ variables:
       - palette: Yellow
         tone: 30
   supportingGrays:
-    instructions: "Choose supporting grays and neutrals"
+    instructions: "Choose supporting grays and neutrals."
     colors:
       - palette: Gray
         tone: 90
@@ -67,6 +67,8 @@ variables:
         tone: 60
       - palette: Gray
         tone: 50
+      - palette: Gray
+        tone: 30
       - palette: Gray
         tone: 10
       - palette: Neutral-White
@@ -77,17 +79,17 @@ variables:
         tone: 10
 ---
 
-Color is a crucial component of our visual vernacular, helping to unify the look and feel of all communications. The [IBM Design Language](http://www.ibm.com/design/language/framework/visual/color.shtml) comprises a wide spectrum of colors; IBM Watson relies on a defined subset of those colors to establish its unique presence while respecting the broader IBM Design guidelines.
+Color is a crucial component of visual vernacular, helping to unify the look and feel of all communications. The [IBM Design Language](http://www.ibm.com/design/language/framework/visual/color.shtml) comprises a wide spectrum of colors; IBM Watson relies on a defined subset of those colors to establish its unique presence while respecting the broader IBM Design guidelines.
 
 ## Colors for Watson
 
-The colors chosen for IBM Watson are flexible and distinguish Watson as a brand across all user experiences. The colors were chosen based on color psychology to support the Watson [brand attributes](brand-attributes.html), reinforce Watson's personality, and set the tone of each specific product.
+The colors chosen for IBM Watson are flexible and distinguish Watson as a brand across all user experiences. The colors were chosen based on color psychology to support the Watson brand attributes, reinforce Watson's personality, and set the tone of each specific product.
 
 {{ _color.adjectiveSwatches(primaryColors) }}
 
-## Choosing A Color Palette
+## Choosing a Color Palette
 
-Choose a primary color, a secondary color, and an accent color. Additional tints and shades of the chosen palette can help to unify the design. These values can add variety to a palette without additional colors. Use the IBM Design Language for a wider variety of colors, values, and neutrals. When choosing a background color for light or dark palettes, IBM Watson recommends using Neutral 1 and Gray 90, as opposed to pure white and black, as some users are sensitive to brightness and high contrast colors.
+Choose a primary color, a secondary color, and an accent color. Additional tints and shades of the chosen palette can help to unify the design. These values can add variety to a palette without additional colors. Refer to the IBM Design Language for a wider variety of colors, values, and neutrals. When choosing a background color for light or dark palettes, IBM Watson recommends using Neutral 1 and Gray 90, as opposed to pure white and black, as some users are sensitive to brightness and high contrast colors.
 
 {{ _color.groupSwatches(primaryColors) }}
 
@@ -97,7 +99,7 @@ Choose a primary color, a secondary color, and an accent color. Additional tints
 
 ## Applying A Color Palette
 
-Color is a powerful communication tool to determine hierarchy on a page. Use ample white space and neutrals to create balance and to direct users' attention.
+Color is a powerful communication tool that helps determine hierarchy on a page. Use ample white space and neutrals to create balance and to direct users' attention.
 
 {{ _example.large(example.paletteApplication.light) }}
 

language/02-guidelines/user-experience/performance/index.md

@@ -18,10 +18,18 @@ resources:
     - name: "Web Page Test"
       source: http://www.webpagetest.org/
 variables:
-  detail:
+  examples:
     framesPerSecond:
       visualDisplay: /videos/performance/performance2.webm
       title: "FPS/Hertz Comparison"
+    desktopLoad:
+      visualDisplay: /videos/performance/wdg--desktop.webm
+      title: "Desktop Page Load"
+      description: "New York, NY USA - **Chrome**. *5/1 Mbps connection with a 28ms round trip time*. [Full test](http://www.webpagetest.org/result/150515_FD_JXH/)"
+    mobileLoad:
+      visualDisplay: /videos/performance/wdg--mobile.webm
+      title: "Mobile Page Load"
+      description: "Dulles, VA - **Motorola E** - **Chrome**. *1.6 Mbps/768 Kbps connection with a 150ms round trip time*. [Full test](http://www.webpagetest.org/result/150515_53_JXT/)"
 ---
 
 Performance is an integral part of a user's experience no matter the medium that interface takes. Web delivered interfaces, native interfaces, application programming interfaces; whenever a user interacts with a product, performance always needs to be a top concern. Slow performing interfaces have been shown to [cost money and conversions](http://www.fastcompany.com/1825005/how-one-second-could-cost-amazon-16-billion-sales) and [affect a company's bottom line](https://blog.kissmetrics.com/loading-time/). More than that, performance is about respecting our users and the way humans perceive and react to the world around them.
@@ -60,7 +68,7 @@ Based on this understanding of memory as well as Nielsen's research, we recommen
 
 A human's sensory memory, acting at 100ms, is able to identify around 10 unique images per second. In order to create the illusion of smooth movement for users, as opposed to a series of independent images, more images are needed. The number of images per second, or frame rate, is often expressed as either Frames per Second (FPS), or in hertz (Hz) when working with progressive scan monitors. For a point of reference, the *de facto* standard for movies and television with sound is 24 FPS.
 
-{{ _detail.view(detail.framesPerSecond) }}
+{{ _example.large(examples.framesPerSecond) }}
 
 When creating interfaces, however, 24 FPS will not provide the fluid movement it does on film. Film relies on a number of effects – most commonly, [motion blur](http://en.wikipedia.org/wiki/Motion_blur) - to hide inter-frame judder. When [animating interface elements](/guidelines/interaction/animation/) or having users interact with our interfaces in a way that would cause motion (such as scrolling), we cannot rely upon those same effects because they are unique to the film medium. Instead, our interfaces should update at the same rate the device's screen is refreshing. When interfaces are not able to refresh at this rate, the result, called [Jank](http://jankfree.org/), is a "…stuttering, juddering, or just plain halting" of the interface.
 
@@ -73,4 +81,13 @@ Whenever working with a network powered interface (websites, native apps that ma
 * Main content is available and usable in **<1s** on a **5/1 Mbps connection with a 28ms round trip time** on a *cold cache*
 * Main content is available and usable in **<3s** on a **1.6 Mbps/768 Kbps connection with a 150ms round trip time** on a *cold cache*
 
+When working with visual interfaces, the [speed index](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) metric is also a good indicator of how quickly an interface is available and usable.
+
+* A speed index of **<1000** on a **5/1 Mbps connection with a 28ms round trip time** on a *cold cache*
+* A speed index of **<3000** on a **1.6 Mbps/768 Kbps connection with a 150ms round trip time** on a *cold cache*
+
+{{ _example.large(examples.desktopLoad) }}
+
+{{ _example.large(examples.mobileLoad) }}
+
 All interfaces should be tested against both. [Web Page Test](http://www.webpagetest.org/) is a tool that will allow teams to test their website performance metrics against these numbers.