Make KDS contributor friendly

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,8 @@
 blank_issues_enabled: false
+contact_links:
+  - name: Kolibri GitHub Discussions
+    url: https://github.com/learningequality/kolibri/discussions
+    about: Please ask general questions about contributing to Kolibri or report development server issues here.
+  - name: Learning Equality Community Forum
+    url: https://community.learningequality.org/
+    about: Ask and answer questions about Learning Equality's products and tools, share your experiences using Kolibri, and connect with users around the world.

CONTRIBUTING.md

@@ -0,0 +1,17 @@
+<!-- Also update README.md (duplicate) -->
+
+# How can I contribute?
+
+1. 💻 Follow the [Getting started](./dev_docs/01_getting_started.md) to set up your development server. At the bottom of that page, you will also find links that will take you to guidelines for the most common tasks.
+2. 🔍 Search for issues tagged as [help wanted](https://github.com/learningequality/kolibri-design-system/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee+) or [good first issue](https://github.com/learningequality/kolibri-design-system/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee).
+3. 🗣️ Ask us for an assignment in the comments of an issue you've chosen.
+
+Note that in times of increased contributions activity, it may take us a few days to reply. If you don't hear from us within a week, please reach out via [Kolibri Design System GitHub Discussions](https://github.com/learningequality/kolibri-design-system/discussions).
+
+**❓ Where to ask questions**
+
+- For anything development related, refer to the [developer documentation](./dev_docs/) at first. Some answers may already be there.
+- For questions related to a specific issue or assignment requests, use the corresponding issue's comments section.
+- Visit [Kolibri Design System GitHub Discussions](https://github.com/learningequality/kolibri-design-system/discussions) to ask about anything related to contributing to Kolibri Design System, troubleshoot development server issues, or connect with other contributors.
+
+*Thank you for your interest in contributing to Kolibri Design System! The Kolibri project was founded by volunteers dedicated to helping make educational materials more accessible to those in need, and every contribution makes a difference.*

dev_docs/01_getting_started.md

@@ -0,0 +1,57 @@
+# Getting started
+
+The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation site [`/docs`](../docs/). The following guidelines will help you set up a development environment so that you can update both.
+
+## Prerequisites
+
+- Node.js 10.x (see [Node Version Manager](https://github.com/nvm-sh/nvm))
+- Yarn 1.x
+
+## Troubleshooting
+
+If you experience any problems with the setup below, see if you can find a similar issue in [Tips and troubleshooting](./02_tips_and_troubleshooting.md).
+
+## Development environment
+
+At first, [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) this repository.
+
+Then, change to the directory where you cloned it:
+
+```bash
+cd kolibri-design-system
+```
+
+Install the dependencies using `yarn`:
+
+```bash
+yarn install
+```
+
+Finally, run the development server:
+
+```bash
+yarn dev
+```
+
+This command will start a documentation development server at http://localhost:4000/. It will also run a linter and auto-formatter.
+
+There are few other commands available:
+
+```bash
+yarn dev-only    # launch just the dev server without the linter and auto-formatter
+yarn lint-fix    # run the linter and auto-formatter once
+yarn lint-watch  # run the linter in watch mode, without the auto-formatter
+```
+
+You're now ready to code! 
+
+## Next steps
+
+- If you experienced troubles with the setup above or would like to get some development tips, you can visit [Tips and troubleshooting](./02_tips_and_troubleshooting.md).
+- Our components are build in Vue 2. If you're not familiar with this framework, refer to [Vue 2 documentation](https://v2.vuejs.org/).
+- If you'd like to update the component library, continue to [How to update the component library](./03_how_to_update_library.md).
+
+The guidelines referenced above should be sufficient for the most common tasks. There are a few additional developer documentation pages available. However, these pages contain information that is more internal in nature or related to specialized tasks:
+- [How to update the documentation website](./04_how_to_update_docs.md)
+- [Icons](./05_icons.md)
+- [Miscellaneous](./06_misc.md)

dev_docs/02_tips_and_troubleshooting.md

@@ -0,0 +1,27 @@
+
+# Tips and troubleshooting
+
+Here, you can find development and troubleshooting tips. 
+
+## `ESOCKETTIMEDOUT` error
+
+If you see a timeout error like `ESOCKETTIMEDOUT` during `yarn install`, you can configure yarn with a higher timeout value [as described here](https://github.com/yarnpkg/yarn/issues/5540#issuecomment-374069461).
+
+## `System limit for number of file watchers reached` error
+
+If you see this error when running the development server, you can try to follow [this advice](https://stackoverflow.com/questions/55763428/react-native-error-enospc-system-limit-for-number-of-file-watchers-reached/55763478#55763478).
+
+
+## Vue Devtools
+
+Vue Devtools is a useful browser extension for debugging and developing Vue applications. You can follow these [installation instructions](https://devtools.vuejs.org/guide/installation.html).
+
+## Text editor
+
+When setting up your text editor, it's useful to ignore the following directories:
+
+* `node_modules`
+* `.nuxt`
+* `dist`
+
+You may also want to install syntax highlighters in your editor for Vue and SASS.

dev_docs/03_how_to_update_library.md

@@ -0,0 +1,81 @@
+# How to update the component library
+
+The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation website [`/docs`](../docs/). The following guidelines will help you update the component library. For guidance on developing the documentation website, see [How to update the documentation website](./04_how_to_update_docs.md).
+
+## Prerequisites
+
+Your development server is set up and running at http://localhost:4000/ as described in [Getting started](./01_getting_started.md).
+
+## Add/update a component
+
+Library components are located in [`/lib`](../lib/). If a component is made up of sub-components in separate files, it will typically be placed in a folder.
+
+**How to add a new component**
+
+1. Create a new component file in [`/lib`](../lib/)
+2. In [KThemePlugin](../lib/KThemePlugin.js), import the component and make it globally accessible by registering it with `Vue.component` (see other components)
+
+See the section below to learn how to preview your new component.
+
+## Visually testing components updates
+
+There are two ways to visually test updates as you're developing:
+- (1) In Kolibri Design System environment
+- (2) In a product that uses Kolibri Design System
+
+See the two sections below for detailed guidance.
+
+Option (1) is simpler and sufficient as the first step, so we recommend starting that way. On certain occasions, it may be necessary to test an update in a product. If you're a contributor, you are welcome to try (2) as well, but typically we do not require contributors to do so, or we will provide support if needed.
+
+### (1) Preview updates in the Kolibri Design System environment
+
+The documentation development server can be used to visually test components updates in the following ways:
+
+**Playground page**
+
+Open [/docs/pages/playground.vue](../docs/pages/playground.vue) and add a component you're working on there. Then, as you're developing, you will see it update live at http://localhost:4000/playground. See an example in the playground file.
+
+If you are working on a new component, make sure to register it first in `KThemePlugin` as described in the "How to add a new component" section above in order to make it available on the playground page.
+
+Please do not commit any updates to the playground file as it's meant as your local preview only. This will help other developers have it ready for their own work.
+
+**Components documentation pages**
+
+The majority of existing components have documentation pages that often show live components in different states. One example of this can be seen on the `KBreadcrumbs` component documentation page at http://localhost:4000/kbreadcrumbs. The documentation page source code is located in [`/docs/pages/kbreadcrumbs.vue`](../docs/pages/kbreadcrumbs.vue).
+
+You can find links to documentation pages for existing components on the documentation website in the "Code library components" section at the bottom of the side navigation. 
+
+If there is already a documentation page for a component, please ensure that any new updates don't break examples on the page. Additionally, you may also consider adding new examples to the documentation if applicable. See [How to update the documentation website](./04_how_to_update_docs.md) to find out more about updating documentation content. You can also review existing documentation pages in the [`/docs/pages`](../docs/pages) directory to familiarize yourself with the source code for the documentation.
+
+When creating a new component, it is recommended to add a new documentation page for it as described in the "Create a documentation page for a new component" section of [How to update the documentation website](./04_how_to_update_docs.md). Even if you are not specifically writing documentation, certain sections of the documentation page will be automatically generated from the component's props and related.
+
+### (2) Preview updates in a product
+
+To see local Kolibri Design System updates reflected in a product that is using it (such as [Kolibri Learning Platform](https://github.com/learningequality/kolibri) or [Kolibri Studio](https://github.com/learningequality/studio)): 
+
+1. While in the root of your local `kolibri-design-system` repository, run `yarn link`.
+2. In the root of the product where you intend to use `kolibri-design-system` run `yarn link kolibri-design-system` and then `yarn install`.
+
+Now, when you run the product your changes in `kolibri-design-system` will be updated live when running the product's development server.
+
+For example, to test Kolibri Design System in Kolibri Learning Platform (local `kolibri` repository):
+
+```bash
+# change to the Kolibri Design System repository and add it to yarn's local package registry
+cd ./kolibri-design-system
+yarn link
+
+# change to the Kolibri repository and link it to the local Kolibri Design System package
+cd ../kolibri
+yarn link kolibri-design-system
+
+# re-install Kolibri dependencies
+yarn install
+
+# run the Kolibri development server
+yarn run devserver
+```
+
+Note that to be able to run the Kolibri development server, at first you need to have it set up as described in [Kolibri developer documentation](https://kolibri-dev.readthedocs.io/en/develop/getting_started.html).
+
+Now you're all set to see your changes to the Kolibri Design System working live in Kolibri!

dev_docs/04_how_to_update_docs.md

@@ -0,0 +1,74 @@
+# How to update the documentation website
+
+The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation website [`/docs`](../docs/). The following guidelines will help you update the documentation website. For guidance on developing the component library, see [How to update the component library](./03_how_to_update_library.md).
+
+## Prerequisites
+
+Your development server is set up and running at http://localhost:4000/ as described in the [Getting started](./01_getting_started.md).
+
+## Updating content
+
+The documentation site is built using [NuxtJS](https://nuxtjs.org/) (configured in `/nuxt.config.js`) and [Vue](https://vuejs.org/).
+
+The directories and files in `/docs/pages/` are mapped by NuxtJS to URLs. Start with those files for making updates to documentation content. The table of contents, including sections and pages, are defined in `/docs/tableOfContents.js`.
+
+Common components used in the documentation site are prefixed with `Docs*` and available for use in all pages.
+
+Layout:
+
+* `<DocsPageTemplate />` - the main page template used by all pages
+* `<DocsPageSection />` - sections within the page template with auto-generated anchor links
+
+Links:
+
+* `<DocsAnchorTarget />` - for creating anchor link targets
+* `<DocsExternalLink />` - links to an external website
+* `<DocsInternalLink />` - links to pages within the design system
+* `<DocsLibraryLink />` - links to library components with `<code>` formatting
+
+Illustration:
+
+* `<DocsShow />` - for showing a component
+* `<DocsDoNot />` - for showing side-by-side "Do" and "Do not" illustrations
+* `<DocsColorBlock />` - for showing a theme color
+* `<DocsIconBlock />` - for showing an icon
+
+All Kolibri shared components (for example `KButton`) are also available to be used within content. However, this should be limited to using them for _examples of usage_ only.
+
+## Updating the library components documentation
+
+The `DocsPageTemplate` component takes an optional Boolean prop called `apiDocs`. When provided, the template will look for a shared library component with the same name, extract documentation for the component's props, events, slots, and methods, and display those at the bottom of the page after any other `DocsPageSection` components.
+
+To make updates to this content, modify the library component directly. We support a combination of Markdown and JSDocs inside the components.
+
+JSDocs functionality is primarily provided by the [`vue-docgen-api`](https://www.npmjs.com/package/vue-docgen-api) package. For more information, see [Documenting components](https://vue-styleguidist.github.io/docs/Documenting.html). Note that we leverage a specific subset of the functionality described there. Documenting this is an [open issue](https://github.com/learningequality/kolibri-design-system/issues/222).
+
+### Create a documentation page for a new component
+
+1. For a new component (`/lib/KNewComponent.vue`), create a new Vue file in [`/docs/pages`](../docs/pages) named after the component, except in lowercase (`/docs/pages/knewcomponent.vue`).
+2. Add the following to `/docs/pages/knewcomponent.vue`:
+```vue
+<template>
+  <DocsPageTemplate apiDocs>
+
+  </DocsPageTemplate>
+</template>
+```
+3. Add a new entry to `pages` array in the `Section` with the title `'Code library components'` in [/docs/tableOfContents.js](../docs/tableOfContents.js):
+  ```javascript
+  new Page({
+    path: '/knewcomponent',
+    title: 'KNewComponent',
+    isCode: true,
+  }),
+  ```
+4. See your new documentation page live at http://localhost:4000/knewcomponent (if it doesn't load, try to restart the development server)
+
+## Import aliases
+
+NuxtJS provides two webpack [import aliases](https://nuxtjs.org/guide/directory-structure#aliases):
+
+* `~~/` points to the root of the repository
+* `~/` points to the `/docs` directory
+
+These aliases should _not_ be used by code inside the `/lib` directory because external webpack configurations will not handle them correctly.

dev_docs/05_icons.md

@@ -0,0 +1,48 @@
+# Icons
+
+This page is all about Kolibri Design System icons. It includes information on our icon sources and provides guidelines on related workflows.
+
+## Sources and regenerating Vue components
+
+There are three sources of icons:
+
+- [Google Material Design Icons](https://github.com/material-icons/material-icons) (version pinned in [yarn.lock](yarn.lock))
+- [Material Design Icons](https://github.com/Templarian/MaterialDesign-SVG) (version pinned in [yarn.lock](yarn.lock))
+- [Custom Learning Equality icons]([custom-icons](../custom-icons/))
+
+Icons from these sources are then converted to Vue components by our custom precompilation script. After updating any of these sources, we need to regenerate the Vue components by running:
+
+```bash
+yarn run precompile-svgs
+```
+
+You can also regenerate just the custom icons which is faster:
+
+```bash
+yarn run precompile-custom-svgs
+```
+
+One of these commands should be run after any icon changes.
+
+We don't expose all icons in our KDS public API. Only icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js) are exposed, and we use our custom aliases for them.
+
+In order to use icons in documentation we also output a set of reStructuredText replacement strings. These are added the file `docs/rstIconReplacements.txt` which can be used in docs based on Sphinx. The file is available for download from https://design-system.learningequality.org/icons/#rst
+
+This command should be run after any icon ID changes.
+
+```bash
+yarn run pregenerate
+```
+
+### Example: Upgrading Google Material Design Icons
+
+It is advised to commit changes at each step to make reviewing files other than those in *precompiled-icons/* easier, especially in case of large updates.
+
+1. Run `yarn upgrade @material-icons/svg`
+2. Run `yarn run precompile-svgs`
+3. Review updates of all public icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js)
+
+Large upgrades can result in a colossal git diff which makes reviewing changes of selected public icons in detail difficult. To make such upgrades smoother, in addition to visually reviewing [icons in KDS documentation](https://design-system.learningequality.org/icons/#icons), you can use a report that is printed in a terminal as soon as the precompilation process ends. It contains all exposed icons aliases together with information about whether an icon has been updated or no. If it's been updated, git diff will be printed.
+
+4. Run `yarn run pregenerate`
+5. Write down notes to the changelog about any public updates like visual changes of icons, updates of their aliases, and updates of reStructuredText replacement strings