docs: add Get started: Developers

docs/_includes/layout-foundations.njk → docs/_includes/layout-with-subnav.njk

@@ -7,6 +7,7 @@ importElements:
   - rh-subnav
   - rh-tag
   - rh-badge
+  - rh-code-block
 ---
 
 {% include 'component/header.njk' %}
@@ -16,10 +17,11 @@ importElements:
     <header class="l-main__header l-main__header--palette-lighter">
       <div class="container header has-subnav">
         <h1 id="{{ heading or title }}" class="page-title">{{ heading or title }}</h1>
-        <rh-subnav>{% for tab in collections.sortedColor %}
-          <a {{ 'active' if tab.url == page.url }} href="{{ tab.url }}">
-            {{ tab.data.title }}
-          </a>{% endfor %}
+        <rh-subnav>
+          {% for tab in collections.sortedColor %}
+            <a {{ 'active' if tab.url == page.url }} href="{{ tab.url }}">
+            {{ tab.data.title }}</a>
+          {% endfor %}
         </rh-subnav>
       </div>
     </header>

docs/_plugins/rhds.cjs

@@ -209,6 +209,13 @@ module.exports = function(eleventyConfig, { tagsToAlphabetize }) {
     });
   });
 
+  eleventyConfig.addCollection('sortedDevelopers', async function(collectionApi) {
+    const developersCollection = collectionApi.getFilteredByTags('developers');
+    return developersCollection.sort((a, b) => {
+      if (a.data.order > b.data.order) { return 1; } else if (a.data.order < b.data.order) { return -1; } else { return 0; }
+    });
+  });
+
   eleventyConfig.addCollection('elementDocs', async function(collectionApi) {
     const { pfeconfig } = eleventyConfig?.globalData ?? {};
     /**

docs/foundations/color/accessibility.md

@@ -1,5 +1,5 @@
 ---
-layout: layout-foundations.njk
+layout: layout-with-subnav.njk
 title: Accessibility
 heading: Color
 tags:

docs/foundations/color/index.md

@@ -1,5 +1,5 @@
 ---
-layout: layout-foundations.njk
+layout: layout-with-subnav.njk
 title: Overview
 heading: Color
 tags:

docs/foundations/color/usage.md

@@ -1,5 +1,5 @@
 ---
-layout: layout-foundations.njk
+layout: layout-with-subnav.njk
 title: Usage
 heading: Color
 tags:

docs/get-started/developers/index.md

@@ -0,0 +1,48 @@
+---
+layout: layout-with-subnav.njk
+title: Overview
+heading: Developers
+tags:
+  - getstarted
+  - developers
+permalink: /get-started/developers/index.html
+order: 00
+bodyClasses: element-docs
+---
+
+## Introduction
+
+<!-- ADD CONTENT -->
+
+
+## Learn about our design system
+
+Our design system libraries and the documentation website offer assets and guidance needed to create digital experiences. Please use these resources to have a better understanding of how to use our design system.
+
+<div class="multi-column--min-400-wide">
+    <div>
+        <h3>Foundations</h3>
+        <p><a href="foundations">Foundations</a> are how we express our brand through color, space, typography, etc.</p>
+    </div>
+    <div>
+        <h3>Design tokens</h3>
+        <p><a href="tokens">Design tokens</a> are how we translate our design language decisions into code.</p>
+    </div>
+    <div>
+        <h3>Documentation</h3>
+        <p>This website offers guidance about how to use our <a href="elements">elements</a> and <a href="patterns">patterns</a> correctly.</p>
+    </div>
+    <div>
+        <h3>GitHub repositories</h3>
+        <p>Explore our code, roadmaps, and discussions in the <a href="https://github.com/RedHat-UX/red-hat-design-system">Red Hat Design System repo</a> and the <a href="https://github.com/RedHat-UX/red-hat-design-tokens">Red Hat Design Tokens repo</a>.</p>
+    </div>
+</div>
+
+## About Web Components
+
+<!-- ADD CONTENT -->
+
+{% feedback %}
+  <h2>Designers</h2>
+  <p>To get started using our design system as a designer, go to the <a href="get-started/designers">Designers</a> page.</p>
+{% endfeedback %}

docs/get-started/developers/installation.md

@@ -0,0 +1,98 @@
+---
+layout: layout-with-subnav.njk
+title: Installation
+heading: Developers
+tags:
+  - developers
+permalink: /get-started/developers/installation/index.html
+order: 10
+bodyClasses: element-docs
+---
+
+## How to install
+
+To develop components or design system documentation, you must first install some required software, namely node.js. We use [nvm](https://github.com/nvm-sh/nvm) to ensure a uniform development environment.
+
+### Step 1: Install node
+
+**Fedora/RHEL users** should install nvm for bash directly from GitHub.
+
+<rh-code-block>
+curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
+</rh-code-block>
+
+**Mac users** should install Homebrew. Go to the website or run this command (takes 5-10 minutes).
+
+<rh-code-block>
+/bin/bash -c "$(curl -fsSL
+https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+</rh-code-block>
+
+Then use that to install `nvm`:
+
+<rh-code-block>
+brew install nvm
+</rh-code-block>
+
+### Step 2: Clone the repository
+
+Clone the repository and change the directory to it:
+
+<rh-code-block>
+git clone [email protected]:redhat-ux/red-hat-design-system
+cd red-hat-design-system
+</rh-code-block>
+
+### Step 3: Install dependencies
+
+Install the right node version using `nvm`, then install the `node_modules` dependencies:
+
+<rh-code-block>
+nvm use
+npm ci
+</rh-code-block>
+
+## How to generate an element
+
+Run the following command to begin the scaffolding process:
+
+<rh-code-block>
+npm run new
+</rh-code-block>
+
+The generator will prompt you for the following:
+
+What is the element tag name?
+
+- Your element should be lower case and needs to contain at least one hyphen to adhere to the [Custom Elements](https://html.spec.whatwg.org/multipage/custom-elements.html) standard naming convention.
+- Red Hat Design System elements should begin prefixed by `rh-`.  However if you are creating an element for use outside this project prefix your element as you see fit.
+
+After answering the script will generate a bootstrapped element in the `elements/your-element` directory complete with a`demo` and `test` directory.
+
+## Run the dev server
+
+Run the dev server to develop components:
+
+<rh-code-block>
+npm start
+</rh-code-block>
+
+This starts a local dev server at http://localhost:8000 and the 11ty dev server for the docs site at http://localhost:8080. Your changes will automatically refresh the browser window.
+
+To run only the components dev server, first run the build, and then run the dev server:
+
+<rh-code-block>
+npm-run-dev
+</rh-code-block>
+
+To run only the docs dev server, first run the build, then 11ty:
+
+<rh-code-block>
+npm run build
+npx eleventy --serve --incremental
+</rh-code-block>
+
+{% feedback %}
+  <h2>Designers</h2>
+  <p>To get started using our design system as a designer, go to the <a href="get-started/designers">Designers</a> page.</p>
+{% endfeedback %}

docs/get-started/developers/tokens.md

@@ -0,0 +1,148 @@
+---
+layout: layout-with-subnav.njk
+title: Tokens
+heading: Developers
+tags:
+  - developers
+permalink: /get-started/developers/tokens/index.html
+order: 30
+bodyClasses: element-docs
+---
+
+## How to install tokens
+
+Run the following git command to install RHDS tokens:
+
+<rh-code-block>
+npm i @rhds/tokens
+</rh-code-block>
+
+## Usage
+
+We use [style-dictionary](https://amzn.github.io/style-dictionary/) to transform our tokens into multiple formats and helpers.
+
+### Import global CSS
+
+Apply defaults to the document root by importing the global stylesheet:
+
+<rh-code-block>
+    <script type="text/html">
+<link rel="stylesheet" href="/url/to/@rhds/tokens/css/global.css">
+<style>
+  :is(h1, h2, h3, h4, h5, h6) {
+    font-family: var(--rh-font-family-heading);
+  }
+</style>
+  </script>
+</rh-code-block>
+
+### Reset the shadowroot
+
+Reset a component's styles (preventing inheritance) by adding resetStyles to its static Constructible Style Sheet list:
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+import { resetStyles } from '@rhds/tokens/css/reset.css.js';
+import style from './rh-jazz-hands.css';
+
+@customElement('rh-jazz-hands')
+export class RhJazzHands extends LitElement {
+  static readonly styles = [resetStyles, style];
+}
+  </script>
+</rh-code-block>
+
+### Import tokens as JavaScript objects
+
+{% alert title="Note", state="info" %}
+We strongly recommend using CSS variables (and accompanying snippets), instead of importing tokens as JavaScript objects.
+{% endalert %}
+
+Import tokens as JavaScript objects:
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+import { tokens } from '@rhds/tokens';
+
+html`<span style="color: ${tokens.get('--rh-color-blue-300')}">I'm blue</span>`;
+  </script>
+</rh-code-block>
+
+or for tree-shakable imports:
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+import { ColorBlue300 } from '@rhds/tokens/values.js';
+
+html`<span style="color: ${ColorBlue300}">I'm blue</span>`;
+  </script>
+</rh-code-block>
+
+## Plugins
+
+### Using editor snippets
+
+Editor snippets complete prefixes like `--rh-color-brand` to their CSS custom properties, complete with fallback.
+
+<rh-code-block>
+  <script type="text/css">
+color: var(--rh-color-brand, #ee0000);
+  </script>
+</rh-code-block>
+
+They also provide reverse lookup. For example,  if you want to choose between all the tokens with the  value `#e00`, you can do so by completing the prefix `e00`.
+
+#### Load snippets in VSCode 
+
+Download the VSIX bundle that’s linked at the bottom of our [“Release v1.0.0”](https://github.com/RedHat-UX/red-hat-design-tokens/releases/tag/v1.0.0) page.
+
+#### Load snippets in Neovim
+
+Use LunaSnip to load snippets in Neovim:
+
+<rh-code-block>
+require 'luasnip.loaders.from_vscode'.lazy_load { paths = {
+  -- Path to the built project, perhaps in your `node_modules`
+  '~/Developer/redhat-ux/red-hat-design-tokens/editor/vscode'
+} }
+</rh-code-block>
+
+### Stylelint plugin
+
+Install the stylelint plugin to automatically correct token values in your files.
+
+See the [Stylelint Plugin README](https://github.com/RedHat-UX/red-hat-design-tokens/blob/main/plugins/stylelint/README.md) for more info.
+
+### 11ty plugin
+
+The experimental 11ty plugin lets you display token values in an 11ty site.
+
+### vim-hexokinase
+
+Vim users can load the [vim-hexokinase](https://github.com/RRethy/vim-hexokinase) plugin to display color swatches next to their encoded values in their editor.
+
+Use the following config (lua syntax, for Neovim users) to configure hexokinase to display color values next to color aliases like `{color.brand.red}`.
+
+<rh-code-block>
+vim.g.Hexokinase_optInPatterns = {
+  'full_hex', 'triple_hex',
+  'rgb', 'rgba',
+  'hsl', 'hsla',
+  'colour_names',
+}
+
+vim.g.Hexokinase_ftOptOutPatterns = {
+  json = { 'colour_names' },
+  yaml = { 'colour_names' },
+}
+
+vim.g.Hexokinase_palettes = {
+  -- replace with path to the built tokens package on your drive
+  vim.fn.expand'~/Developer/redhat-ux/red-hat-design-tokens/editor/neovim/hexokinase.json'
+}
+</rh-code-block>
+
+{% feedback %}
+  <h2>Designers</h2>
+  <p>To get started using our design system as a designer, go to the <a href="get-started/designers">Designers</a> page.</p>
+{% endfeedback %}

docs/get-started/developers/usage.md

@@ -0,0 +1,34 @@
+---
+layout: layout-with-subnav.njk
+title: Usage
+heading: Developers
+tags:
+  - developers
+permalink: /get-started/developers/usage/index.html
+order: 20
+bodyClasses: element-docs
+---
+
+## Usage
+
+### Using npm
+
+### Using the CDN
+
+### React wrappers
+
+### Vue wrappers
+
+## Adding icons
+
+## Customizing
+
+## Other resources
+
+- [Red Hat Design System Wiki](https://github.com/RedHat-UX/red-hat-design-system/wiki)
+- [Red Hat Brand Standard](https://www.redhat.com/en/about/brand/standards)
+
+{% feedback %}
+  <h2>Designers</h2>
+  <p>To get started using our design system as a designer, go to the <a href="get-started/designers">Designers</a> page.</p>
+{% endfeedback %}