Merge pull request #455 from instructure/next

Next

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 npm-debug.log
 yarn-error.log
 lerna-debug.log
+./build-storybook.log
 coverage/
 package-lock.json
 .yarnclean
@@ -15,3 +16,4 @@ __build__
 .env
 .env.test
 .tmp/
+

README.md

@@ -2,13 +2,13 @@
 id: instructure-ui
 ---
 
-## instructure-ui
+## Instructure UI
 
-[![build-status][build-status]][build-status-url]   [![MIT License][license-badge]][license]   [![Code of Conduct][coc-badge]][coc]
+[![MIT License][license-badge]][license]   [![Code of Conduct][coc-badge]][coc]
 
-## Usage
+Instructure UI is an open source UI framework and design system for React. Its components are used by millions of learners every day when they use Instructure products like Canvas LMS.
 
-To build an accessible application using the React components, themes, and utilities provided by instructure-ui, see our [quick start](https://instructure.design/#usage) documentation.
+### See our [website](https://instructure.design) for usage, examples and documentation.
 
 ## Contributing
 
@@ -26,8 +26,6 @@ The last two versions of all modern browsers (Firefox, Safari, Chrome, Edge).
 
 [MIT](#LICENSE)
 
-[build-status]: https://travis-ci.org/instructure/instructure-ui.svg?branch=master
-[build-status-url]: https://travis-ci.org/instructure/instructure-ui 'Travis CI'
 [license-badge]: https://img.shields.io/npm/l/instructure-ui.svg?style=flat-square
 [license]: https://github.com/instructure/instructure-ui/blob/master/LICENSE
 [coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square

docs/getting-started/accessibility.md

@@ -5,6 +5,7 @@ order: 5
 ---
 
 ## Accessibility
+
 We aim to make our software accessible to everyone, including those with vision, hearing, cognitive, or motor impairments. Having an accessible design allows people of all abilities to interact with, understand, and navigate our products. This means that components are [Perceivable, Operable, Understandable, and Robust](https://www.w3.org/TR/2016/NOTE-UNDERSTANDING-WCAG20-20161007/intro.html#introduction-fourprincs-head). It’s important for us to design and develop products that support a wide range of needs and experiences.
 
 ### Color Contrast
@@ -13,11 +14,11 @@ Our [default theme](#canvas) colors meet at least a [3:1](http://www.w3.org/TR/W
 
 ### Keyboard Navigation
 
-Some users are unable to use a mouse, and instead navigate through applications using tools such as a keyboard, mouth wand, or eye tracking software.  Our components are navigable using these technologies without mouse assistance.  Keyboard focus follows the page as an eye would scan it (top to bottom, left to right).  We also ensure that focus indication is clear and apparent so users are always aware of where their current keyboard focus is within the page.  Our components can be interacted with using [standard keystrokes](https://webaim.org/techniques/keyboard/#testing), so there is no need to learn any new shortcuts.
+Some users are unable to use a mouse, and instead navigate through applications using tools such as a keyboard, mouth wand, or eye tracking software. Our components are navigable using these technologies without mouse assistance. Keyboard focus follows the page as an eye would scan it (top to bottom, left to right). We also ensure that focus indication is clear and apparent so users are always aware of where their current keyboard focus is within the page. Our components can be interacted with using [standard keystrokes](https://webaim.org/techniques/keyboard/#testing), so there is no need to learn any new shortcuts.
 
 ### Assistive Technologies
 
-Our components are [tested in VoiceOver for Mac, and NVDA/JAWS for Windows](https://www.canvaslms.com/accessibility), which are the highest utilized screenreaders (according to [WebAim’s user survey](https://webaim.org/projects/screenreadersurvey7/)).  We utilize many different tools to ensure this compatibility, such as features from the Accessible Rich Internet Applications (WAI-ARIA or ARIA) specification to build functionality that is not available with native HTML, and alternative text for images/icons to ensure all users have the same experience when utilizing our components.
+Our components are [tested in VoiceOver for Mac, and NVDA/JAWS for Windows](https://www.canvaslms.com/accessibility), which are the highest utilized screenreaders (according to [WebAim’s user survey](https://webaim.org/projects/screenreadersurvey7/)). We utilize many different tools to ensure this compatibility, such as features from the Accessible Rich Internet Applications (WAI-ARIA or ARIA) specification to build functionality that is not available with native HTML, and alternative text for images/icons to ensure all users have the same experience when utilizing our components.
 
 ### Web Content Accessibility Guidelines (WCAG)
 
@@ -31,4 +32,4 @@ For more information, see the following resources:
 
 ### Feedback
 
-If you notice any issues with the accessibility of our components, please reach out by creating a [GitHub](https://github.com/instructure/instructure-ui) issue and help us make it better.
+If you notice any issues with the accessibility of our components, please reach out to us by creating a [GitHub](https://github.com/instructure/instructure-ui/issues) issue and help us make it better.

docs/getting-started/api-guidelines.md

@@ -8,7 +8,7 @@ order: 4
 
 ### Component Properties
 
-- All components should pass through additional props down to the root DOM element using the `passthroughProps` utility. (e.g. `<div {...passthroughProps(this.props)}>`). Note that in addition to allowing only valid DOM node attributes, `passthroughProps` will remove the `className` and `style` props to prevent unexpected style issues. These need to be set explicitly and used with caution.
+- All components should pass through additional props down to the root DOM element using the `passthroughProps` utility. (e.g. `<div {...passthroughProps(this.props)}>`). Note that in addition to allowing only valid DOM node attributes, `passthroughProps` will remove the `className` and `style` props to prevent unexpected style issues. These need to be set explicitly and used with caution. It also removes the `styles` and `makesStyles` properties added by the [withStyle](#withStyle) decorator.
 - Avoid props that could be computed from other props. (e.g. prefer `<Select filter={handleFilter} />` over `<Select shouldFilter filter={handleFilter} />`. Prefer determining whether filtering should happen based on the presence of the `filter` function prop.)
 - Avoid situations where certain prop combinations are not supported. Prefer splitting the component into separate components with fewer props or using `PropTypes.oneOf`.
 - Set default prop values for non-required props when possible.
@@ -44,16 +44,21 @@ order: 4
 - Child components that can't be used on their own should be exported as static properties on the parent component (e.g. `Table.Row`, `Menu.Item`), so that only one import is required to render the component (e.g. `import Table from '@instructure/ui-tables'`).
 - If the parent component can only be used with specific children that can also be used on their own, it should have the `Group` suffix (e.g. `<RadioGroup><Radio /><Radio /></RadioGroup>`, `<ButtonGroup><Button /><Button /></ButtonGroup>`).
 
-### CSS Class Names
+### styles.js Class Names
 
-- CSS class names that correspond to a boolean prop should match the prop name (e.g. `isOpen`).
-- CSS class names that correspond to a prop name and value should match the kebab-case prop value (e.g. `x-large`) and should be prefixed with the prop name and separated by `--` (e.g. `.size--x-large`, `.width--fluid`).
-- All other CSS class names should be camelCase, semantic (describe the content, not what it looks like), and avoid any component prefix (the component scope will be added by the build).
+- In the `styles.js`, use the name of the component in camelCase (e.g. `appNav`) as the key of the root element's style object. Use camelCase for the keys of child elements as well (e.g. `list` and `listItem`).
+- All style object names should be semantic (describe the content, not what it looks like).
+- We make use of the `label` property of [Emotion.js](https://emotion.sh/) so that it gets displayed in the generated class name for easy readability and targetability. We use a naming convention based on [BEM naming convention](#http://getbem.com/naming/):
+  - For the root element, add a label with the name of the component in camelCase \
+    (e.g. `appNav: { label: 'appNav' }`).
+  - For the child elements, use the double underscore separator to indicate the parent-child relation with the `[rootElementName]__[childName}` format \
+  - In case you want to indicate variants or modifiers of an element, use the double hyphen separator with the `[elementName]--[modifier]` format \
+    (e.g. `view--inline-block` or `calendar__navigation--withButtons`).
 
 ### Component Theme Variables
 
 - Theme variables should be camelCase, reflecting the corresponding CSS property when possible and prefixed with a semantic descriptor, using the following format: `[variation][state][CSS property]` e.g. (for `<Button color="primary" />`, `primaryHoverBackground`).
-- Theme variables shouldn't include the component name because the component scope is added via the build. (`primaryHoverBackground` will be transformed into `--Button`)
+- Theme variables shouldn't include the component name.
 
 ### Component Lifecycle methods
 

docs/getting-started/contributing.md

@@ -6,82 +6,78 @@ order: 2
 
 ## Contributing
 
-Contributions are welcome! If you want to submit a change you will need to open a pull request on Github. To do so first fork the repository to your own Github account. 
+Contributions are welcome! If you want to submit a change you will need to open a pull request on Github. To do so first fork the repository to your own Github account.
 
-__Installation steps:__
+### What can you contribute?
 
-Follow these steps to download and run Instructure-UI on your machine:
+If you found a bug or want to add a minor feature, go ahead! If you'd like to add a new component, or change/add new visuals, please read on.
+
+We try to keep InstUI easy to use, easy to learn and free from bloat.
+For this reason we will only add new components if it fits into the current design patterns, and the new component cannot be
+constructed from the existing ones. For these reasons adding a new component has the following process:
+
+- You should write a document which includes the component description, and the use cases it's meant to be used in.
+- You should make some kind of design sketch that documents the design of the component (e.g. with [Figma](https://www.figma.com/)).
+- Our design team will review and approve this design sketch.
+- If the sketch is OK, you will need to make a pull request (read on for our code guidelines), the InstUI dev team, the design team, and our a11y team will review and merge your contribution.
+
+### Building InstUI from the source
+
+Follow these steps to download and compile Instructure UI on your machine:
 
 1. Install [Git](http://git-scm.com/).
-1. Install [Node 10.x](https://nodejs.org/en/)) (we recommend [nvm](https://github.com/creationix/nvm) to manage multiple Node versions).
-1. Install [Yarn](https://yarnpkg.com/lang/en/docs/install/) (You will need v1.1.0+).
+1. Install [Node >= 12.20](https://nodejs.org/en/)) (we recommend [nvm](https://github.com/creationix/nvm) to manage multiple Node versions).
+1. Install [Yarn >=1.6](https://yarnpkg.com/lang/en/docs/install/)
 1. Clone the repository with `git clone` (If you want to make changes clone the forked repo in your account.)
 1. Run `cd instructure-ui`
 1. Run `yarn`
 1. Run `yarn bootstrap`
 
 Run `yarn run` to list the available commands.
 
-When you are ready with your changes open a pull request on Github to the `master` branch and the maintainers will review and merge it.
-
 ### Running the documentation app
 
 1. Run `yarn start`
 1. Open [http://localhost:8001](http://localhost:8001) in your browser
 
-
 ### Development
 
 1. Run `yarn build:watch` to build all of the packages for a development environment and watch for changes.
 1. Run `yarn dev` to start the dev server to run/develop examples and documentation. You can then visit [http://localhost:8080](http://localhost:8080) in a browser. When you make changes to the source code you should see the page auto-reload.
 1. Run `yarn test:watch --scope @instructure/[package name]` to run the tests for 'package name' and watch for changes.
 1. Run `yarn test` to run all the tests for every package.
 
+## Code guidelines
 
 ### Testing
 
 See the [testing documentation](#testing-components) for details.
 
-
 ### Linters and Code Formatting
 
 Linters are run as part of the build. If you use the Sublime Text, Atom, or VSCode editors, you can set up the following plugins to catch lint and formatting errors earlier.
 
-1. Install the *Linter* plugin [Sublime](http://sublimelinter.readthedocs.org/en/latest/), [Atom](https://atom.io/packages/linter). Linting is included in VSCode.
-1. Install the *EditorConfig* plugin [Sublime](https://github.com/sindresorhus/editorconfig-sublime), [Atom](https://github.com/sindresorhus/atom-editorconfig), [VSCode](https://github.com/editorconfig/editorconfig-vscode)
-1. Install the *Eslint* plugin [Sublime](https://github.com/roadhump/SublimeLinter-eslint), [Atom](https://github.com/AtomLinter/linter-eslint), [VSCode](https://github.com/Microsoft/vscode-eslint)
-1. Install the *Stylelint* plugin [Sublime](https://github.com/kungfusheep/SublimeLinter-contrib-stylelint), [Atom](https://atom.io/packages/linter-stylelint), [VSCode](https://github.com/shinnn/vscode-stylelint)
+1. Install the _Linter_ plugin [Sublime](http://sublimelinter.readthedocs.org/en/latest/), [Atom](https://atom.io/packages/linter). Linting is included in VSCode.
+1. Install the _EditorConfig_ plugin [Sublime](https://github.com/sindresorhus/editorconfig-sublime), [Atom](https://github.com/sindresorhus/atom-editorconfig), [VSCode](https://github.com/editorconfig/editorconfig-vscode)
+1. Install the _Eslint_ plugin [Sublime](https://github.com/roadhump/SublimeLinter-eslint), [Atom](https://github.com/AtomLinter/linter-eslint), [VSCode](https://github.com/Microsoft/vscode-eslint)
+1. Install the _Stylelint_ plugin [Sublime](https://github.com/kungfusheep/SublimeLinter-contrib-stylelint), [Atom](https://atom.io/packages/linter-stylelint), [VSCode](https://github.com/shinnn/vscode-stylelint)
 1. Run `yarn` to install the dependencies
 1. Restart your editor
 
-
 ### Documentation
 
 Please update the documentation and examples with any changes.
 
 - `yarn start` will build the production version of the documentation. You can view it at [http://localhost:8001](http://localhost:8001).
 - All components and utilities should be well documented, including examples.
 - Write documentation inline in code comment blocks. The code and docs should
-always be in sync.
-
+  always be in sync.
 
 ### Commit Guidelines
 
 1. Run `yarn commit` to commit your changes and follow our commit message format.
 1. Please do not include the output of `yarn build` in your commits.
 
-
-### Updating build (repository) dependencies
-
-1. `yarn add <package-name>` or `yarn upgrade <package-name>`.
-1. Commit the result.
-
-
-### Updating individual package dependencies
-
-1. Update the relevant `package.json` file. Make sure to retain the `^` semver range.
-1. Run `yarn bootstrap` and commit the result.
-
 ### Adding a package
 
 1. Run `yarn generate:package` and choose a name for your package (use "kebab" case (dashes), e.g. 'my-package').
@@ -102,24 +98,10 @@ always be in sync.
 1. Visit [http://localhost:8080](http://localhost:8080) in a browser. You should see your component listed in the docs.
 1. Start making changes to your component, and watch it update in the browser automatically.
 
-
-### Proposing API changes
-
-If you'd like to propose changes to a component API or a new component, you'll need to fill out an RFC ("request for change") document and have it reviewed before implementing your change. Be sure to note any breaking changes or deprecations in the RFC document.
-
-1. Run `yarn generate:rfc`. This script creates an RFC document for you in `/rfcs`.
-1. Fill out this document and submit it for review.
-1. Once the RFC is approved and merged you can go ahead and make your change.
-
-
 ### Accessibility and Internationalization Requirements
 
 All components should:
-1. be accessible (See the [accessibility requirements](#accessibility) for more information).
-1. support RTL languages.
-1. localize all dates, times, numbers and strings (or require localized content passed in via props).
-
-
-### Releases
 
-See the [releases documentation](#releases) for information on the release process.
+1. Be accessible (See the [accessibility requirements](#accessibility) for more information).
+1. Support RTL languages.
+1. Localize all dates, times, numbers and strings (or require localized content passed in via props).