docs: update developer content (#2409)

* docs: update developer/setup content

* docs: update setup documentation

* docs: updates to create and structure

* docs: improvements to developer section

* docs: correct link to new issues

* docs: fix url in non markdown block

* docs: update generate new component command

* docs: add example to generation options

* docs: update link to current custom elements working draft

* feat: adding updated footer to the dev server

* docs: improve getting started and quick start

* docs: add screenshots and improve structure server info

* docs: update pf-tabs example

* Revert "feat: adding updated footer to the dev server"

This reverts commit d07033b.

* docs: update screenshots, javascript examples

* docs: improve testing, add screenshots

* docs: update playground url to use a gist url

* docs: correct generate element switch table options

* docs: update default directory path

* docs: improve testing section on setup

* docs: reword wrapper text

* docs: update badges in README

* docs: update README commands

* docs: formatting and consistency updates, changing all example elements to pf-cool-element

* docs: add creating import maps section

* docs: improve get-started code example

* docs: improve importmaps

---------

Co-authored-by: Brian Ferry <[email protected]>
Co-authored-by: Benny Powers <[email protected]>

Author: 3 people

README.md

@@ -1,4 +1,9 @@
-# PatternFly Elements [![Netlify status](https://api.netlify.com/api/v1/badges/bf40e3e7-4f98-4088-91d9-112dbe8a1872/deploy-status)](https://patternfly-elements.netlify.app) ![build status](https://img.shields.io/github/workflow/status/patternfly/patternfly-elements/Build%20&%20test/main) ![commit](https://badgen.net/github/last-commit/patternfly/patternfly-elements) ![latest version](https://img.shields.io/github/lerna-json/v/patternfly/patternfly-elements?label=version) ![contributors](https://img.shields.io/github/contributors/patternfly/patternfly-elements)
+# PatternFly Elements 
+
+ [![latest version](https://img.shields.io/github/package-json/v/patternfly/patternfly-elements?filename=elements%2Fpackage.json)](https://github.com/patternfly/patternfly-elements/releases) [![contributors](https://img.shields.io/github/contributors/patternfly/patternfly-elements?color=%2306c)](https://github.com/patternfly/patternfly-elements/graphs/contributors) \
+ \
+  ![build status](https://img.shields.io/github/actions/workflow/status/patternfly/patternfly-elements/tests.yml)
+ ![last commit](https://img.shields.io/github/last-commit/patternfly/patternfly-elements?color=%2306c) [![Netlify status](https://api.netlify.com/api/v1/badges/bf40e3e7-4f98-4088-91d9-112dbe8a1872/deploy-status?branch=main)](https://patternflyelements.com)
 
 ## Table of Contents
 
@@ -77,24 +82,12 @@ npm run test:vue
 npm run test:ci
 ```
 
-### Open a new pull request
-
-```shell
-# Open a new pull request
-npm run pr
-```
-
-### Documentation site
-View the documentation locally
+### Development and Documentation servers
 ```shell
+# Development and documentation servers load simultaneously on localhost:port `:8000` and `:8080` respectively.
 npm run start
 ```
 
-Build the documentation site
-```shell
-npm run docs
-```
-
 ## Support
 
 Though we have tested and verified general usability within these frameworks, PatternFly Elements makes no guarantees about compatibility within specific sites and applications. Please test accordingly.

docs/docs/develop/create.md

@@ -1,47 +1,48 @@
 ---
 layout: layout-docs.njk
 title: Create a PatternFly Element
-order: 2
+order: 20
 tags:
   - develop
 ---
 
+<style>
+  img {
+    max-width: 100%;
+  }
+</style>
+
 {% band %}
 
+  ## PatternFly Element generator
+
   Before you begin, make sure you've followed the 
   [Prerequisites](/docs/develop/setup#prerequisites) in 
   [Setup](/docs/develop/setup).
 
-  <h3>PatternFly Element generator</h3>
-
-  Use the PatternFly Element generator to start the scaffolding process. From 
-  the root directory of the PatternFly Elements  repository, run the following 
-  command.
+  Then use the PatternFly Element generator to start the scaffolding process. 
+  
+  From the root directory of the PatternFly Elements  repository, run the following 
+  command:
 
   ```bash
   npm run new
   ```
 
-  The generator will ask you a series of questions to set up your project.
+  The generator will then prompt you for the following:
 
-  1.  Your element name:
-      - Your element's name should be lowercase and needs to contain at least 
-        one hyphen. For rules on naming custom elements, refer to the W3C 
-        [Custom Elements Working 
-        Draft](https://www.w3.org/TR/custom-elements/#valid-custom-element-name).
-      - PatternFly Elements prefixes elements with `pf-`. However, prefix your 
-        elements with whatever fits your project.
-      - As an example, we'll create `pf-cool-element`.
+  * What is the element's tag name?
+    * Your element's name should be lowercase and needs to contain at least 
+      one hyphen. For rules on naming custom elements, refer to the W3C 
+      [Custom Elements Working Draft](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name).
+    * As an example, we'll create `pf-cool-element`.  
+    * PatternFly Elements should be prefixed with `pf-`. However, prefix your 
+      elements with whatever fits your project if you are using the generator outside of this project.
 
-  1. The [NPM scope](https://docs.npmjs.com/cli/v6/using-npm/scope) for the 
-  package. For example, patternfly elements packages like `@patternfly/pf-core` 
-  are published under the `patternfly` scope.
 
-  1. A number of questions about the npm package, including the author's name 
-  and email, etc.
+  ![npm run new command](/images/develop/npm-run-new.png)
 
-  After answering the questions, your new component will be created and 
-  bootstrapped in the repository.
+  After answering, your new component will be created and bootstrapped in the repository.
 
   Once that's done, switch directories to the element you just created. We'll 
   `cd` into the `pf-cool-element` directory.
@@ -53,35 +54,16 @@ tags:
   Open your code editor to view the structure of the element.
   The element's source files are located directly in it's package root, in our 
   case:
-    - `pf-cool-element.ts` - The element class declaration
-    - `pf-cool-element.css` - The element's CSS style module
-
-  These two files are the most important as they contain the actual element 
-  definition. In addition, there are a number of config files. Do not edit these files 
-  unless you know what you're doing.
-    - `custom-elements-manifest.config.js` - Configuration for the 
-      custom-elements-manifest analyzer.
-    - `custom-elements.json` - A manifest of your package's JS exports and 
-      custom elements.
-    - `package.json` - NPM package configuration and scripts
-    - `tsconfig.json` - TypeScript configuration for your monorepo.
-
-  For now, your `custom-elements.json` file is empty. If you'd like to generate 
-  content for it, run the `analyze` script in your element's workspace:
-
-  ```bash
-  npm run analyze
-  ```
 
-  This happens automatically when you build or publish your elements, so don't 
-  worry about forgetting to run it.
+  * `pf-cool-element.ts` - The element class declaration
+  * `pf-cool-element.css` - The element's CSS style module
 
   The `demo` directory contains an HTML partial that you can edit to provide an 
   interactive demo of your element.
 
-  The `test` directory contains unit test files for your elemen.
+  The `test` directory contains unit test files for your element.
 
-  You'll also notice that the generator editted the root `tsconfig.json`, adding 
+  You'll also notice that the generator edited the root `tsconfig.json`, adding 
   a `path` to our new element.
   This is important so that TypeScript knows where each of our packages in the 
   monorepo are.

docs/docs/develop/css.md

@@ -1,7 +1,7 @@
 ---
 layout: layout-docs.njk
 title: Write your CSS
-order: 5
+order: 50
 tags:
   - develop
 ---
@@ -34,20 +34,38 @@ Now we can update our styles, like so:
 
 ```css
 :host {
-  display: flex;
+  display: inline-flex;
   flex-direction: column;
   align-items: center;
   justify-content: center;
+  border: 
+    var(--pf-global--BorderWidth--sm, 1px) 
+    solid 
+    var(--pf-global--BorderColor--100, #d2d2d2);
+  padding: var(--pf-global--spacer--xl, 2rem);
+  margin: var(--pf-global--spacer--md, 1rem);
 }
 
 :host([hidden]) {
   display: none;
 }
+
+#profile-pic {
+  width: 60px;
+  height: 60px;
+  margin: var(--pf-global--spacer--md, 1rem);
+  border: 
+    var(--pf-global--BorderWidth--sm, 1px) 
+    solid 
+    var(--pf-global--BorderColor--200, #8a8d90);
+  border-radius: 50%;
+  background-color: var(--pf-global--BackgroundColor--200, #f0f0f0);
+}
 ```
 
 After saving and viewing our demo page, our profile element looks much better.
 
-![Demo Page CSS](/images/develop/develop-sass.png)
+![Demo Page CSS](/images/develop/develop-css.png)
 
 A couple of things to note:
 
@@ -58,8 +76,6 @@ Now that our `pf-cool-element` is more appealing, we'll add the follow button's
 and fill in the profile photo.
 We can accomplish both of these tasks by updating the `pf-cool-element.ts` file.
 
-<a href="{{ '/theming/' | url }}">Learn more about applying a theme.</a>
-
 <a class="cta" href="{{ '../javascript' | url }}">Next up: Write your JavaScript</a>
 
-{% endband %}
+{% endband %}

docs/docs/develop/html.md

@@ -1,7 +1,7 @@
 ---
 layout: layout-docs.njk
 title: Write your HTML
-order: 4
+order: 40
 tags:
   - develop
 ---
@@ -19,7 +19,7 @@ advantage of the slot and shadow root to make our element a bit more
 interesting.
 
 PatternFly elements are written in [TypeScript](https://typescriptlang.org), a 
-dialect of JavaScript which adds development-time type checking and other 
+superset of JavaScript which adds development-time type checking and other 
 features.
 If you are unfamiliar with TypeScript, read their getting-started documentation, 
 and feel free to reach out to the PatternFly Elements team on our social media 
@@ -53,29 +53,24 @@ We'll also need to update `/demo/pf-cool-element.html`
 so that the user's name is passed into the slot that we added in `pf-cool-element.ts`:
 
 ```html
-<link rel="stylesheet" href="./demo.css"/>
+<link rel="stylesheet" href="demo.css">
+<script type="module" src="pf-cool-element.js"></script>
+
 <pf-cool-element>
   Kyle Buchanan
 </pf-cool-element>
 ```
 
-> Slots take the HTML from the light DOM and project it into the shadow DOM at a 
-> given location.
-> To learn more about shadow DOM and how to use slots, check out [Shadow DOM v1: 
-> Self-Contained Web 
-> Components](https://developers.google.com/web/fundamentals/web-components/shadowdom).
+Slots take the HTML from the light DOM and project it into the shadow DOM at a given location.
 
 Here's how it should look in the browser:
 
 ![demo page html step](/images/develop/develop-html.png)
 
-Remember that any changes we make in the element directory are watched while the 
-`npm run dev` command runs.
-When you save changes, the dev server reloads the page and shows you your 
-changes automatically.
+Remember that any changes we make in the element directory are watched while the `npm run start` command runs. When you save changes, the dev server reloads the page and shows you your changes automatically.
 
 Now that we've added the HTML, let's style our element by updating the CSS file.
 
 <a class="cta" href="../css">Next up: Write your CSS</a>
 
-{% endband %}
+{% endband %}