Merge pull request #231 from oclif/mdonnalley/ux-docs

feat: ux related docs

docs/themes.md

@@ -2,15 +2,13 @@
 title: Themes
 ---
 
-oclif supports themes that users can either define for themselves or select from a variety of themes you ship with your CLI.
+oclif supports themes that you can ship with your CLI, which users can then override if they choose.
 
 By default, the theme only applies to help output but you can extend the theme for your own purposes if you want. See [Extending Themes](#extending-themes) section below.
 
 ## theme.json
 
-By default oclif will read themes from `~/.config/<CLI>/theme.json`.
-
-This file takes the following shape:
+The theme file takes the following shape:
 
 ```json
 {
@@ -56,6 +54,33 @@ The values for each of these must be one of the following:
 
 Any invalid values will be ignored.
 
+## Shipping a Theme
+
+Shipping a theme with your CLI is very simple.
+
+First you need to create a new theme file (see above) in your CLI. Then, in your package.json, you just need to tell oclif where to find that file:
+
+```json
+{
+  "files": [
+    "/theme.json",
+    "/oclif.manifest.json",
+    "/dist",
+  ],
+  "oclif": {
+    "theme": "theme.json"
+  }
+}
+```
+
+It's important that you also add the file to the list of `files` so that it will be packed with your CLI whenever you publish to npm or when pack your CLI using `oclif pack`.
+
+## Overriding Themes
+
+If you've shipped a theme with your CLI, users can then override the theme by creating their own `theme.json` in the config directory of your CLI (`~/.config/<CLI>` on unix, `%LOCALAPPDATA%\<CLI>` on windows.)
+
+Users can specify one or all of the theme properties in their own `theme.json`, meaning that they can choose to only override a single property of the default theme.
+
 ## Disabling Themes
 
 Themes can be disabled by using `<CLI>_DISABLE_THEME` environment variable.

docs/user_experience.md

@@ -0,0 +1,21 @@
+---
+title: User Experience
+---
+
+oclif's philosophy is that developers should free to design any user experience that they want for their users. In other words, we try really hard to not make any UX decisions for you.
+
+So many times we utilize [hooks](./hooks.md) whenever a user experience is required (e.g. the provided command isn't found). That way you can design the exact experience you want your users to have. In the case of error handling, you're [able to override](./error_handling.md) oclif's default behavior.
+
+But to make it easy for you, `@oclif/core` exports a [`ux` module](https://github.com/oclif/core/blob/main/src/cli-ux/README.md) that offers several tools you can use to implement your desired user experience.
+
+However, due to time constraints we are not able to support this module as well as we would like. For that reason, we **strongly** recommend that you find npm libraries that specialize in the UX components you want to use. Here's a brief list of some of the libraries we like:
+
+- For prompts: [inquirer](https://www.npmjs.com/package/inquirer)
+- For spinners: [ora](https://www.npmjs.com/package/ora)
+- For progress bars: [cli-progress](https://www.npmjs.com/package/cli-progress)
+- For hyperlinks: [hyperlink](https://www.npmjs.com/package/hyperlink)
+- For tables: [tty-table](https://www.npmjs.com/package/tty-table), [cliui](https://www.npmjs.com/package/cliui)
+- For trees: [object-treeify](https://www.npmjs.com/package/object-treeify)
+- For colored JSON: [color-json](https://www.npmjs.com/package/color-json)
+- For notifications: [node-notifier](https://www.npmjs.com/package/node-notifier)
+- For rendering react components: [ink](https://www.npmjs.com/package/ink)