From 4e1acdadb41c0729b4aa9a598bc5019bbb6e1f48 Mon Sep 17 00:00:00 2001 From: marionnegp Date: Wed, 10 Jan 2024 09:51:52 -0500 Subject: [PATCH 01/13] feat: add content and update template --- ...foundations.njk => layout-with-subnav.njk} | 10 +- docs/_plugins/rhds.cjs | 7 ++ docs/foundations/color/accessibility.md | 2 +- docs/foundations/color/index.md | 2 +- docs/foundations/color/usage.md | 2 +- docs/get-started/developers/index.md | 48 +++++++++ docs/get-started/developers/installation.md | 98 +++++++++++++++++++ docs/get-started/developers/tokens.md | 88 +++++++++++++++++ docs/get-started/developers/usage.md | 32 ++++++ 9 files changed, 282 insertions(+), 7 deletions(-) rename docs/_includes/{layout-foundations.njk => layout-with-subnav.njk} (76%) create mode 100644 docs/get-started/developers/index.md create mode 100644 docs/get-started/developers/installation.md create mode 100644 docs/get-started/developers/tokens.md create mode 100644 docs/get-started/developers/usage.md diff --git a/docs/_includes/layout-foundations.njk b/docs/_includes/layout-with-subnav.njk similarity index 76% rename from docs/_includes/layout-foundations.njk rename to docs/_includes/layout-with-subnav.njk index 553658ae12..5f65951bf1 100644 --- a/docs/_includes/layout-foundations.njk +++ b/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:

{{ heading or title }}

- {% for tab in collections.sortedColor %} - - {{ tab.data.title }} - {% endfor %} + + {% for tab in collections.sortedColor %} + + {{ tab.data.title }} + {% endfor %}
diff --git a/docs/_plugins/rhds.cjs b/docs/_plugins/rhds.cjs index 4abe25c19d..5fbbd27544 100644 --- a/docs/_plugins/rhds.cjs +++ b/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 ?? {}; /** diff --git a/docs/foundations/color/accessibility.md b/docs/foundations/color/accessibility.md index 734717fb92..fe3afbc1f0 100644 --- a/docs/foundations/color/accessibility.md +++ b/docs/foundations/color/accessibility.md @@ -1,5 +1,5 @@ --- -layout: layout-foundations.njk +layout: layout-with-subnav.njk title: Accessibility heading: Color tags: diff --git a/docs/foundations/color/index.md b/docs/foundations/color/index.md index be16e80aab..c003aef94f 100644 --- a/docs/foundations/color/index.md +++ b/docs/foundations/color/index.md @@ -1,5 +1,5 @@ --- -layout: layout-foundations.njk +layout: layout-with-subnav.njk title: Overview heading: Color tags: diff --git a/docs/foundations/color/usage.md b/docs/foundations/color/usage.md index 7735d2b969..4c25a6f67d 100644 --- a/docs/foundations/color/usage.md +++ b/docs/foundations/color/usage.md @@ -1,5 +1,5 @@ --- -layout: layout-foundations.njk +layout: layout-with-subnav.njk title: Usage heading: Color tags: diff --git a/docs/get-started/developers/index.md b/docs/get-started/developers/index.md new file mode 100644 index 0000000000..993eeb9099 --- /dev/null +++ b/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 + + + + +## 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. + +
+
+

Foundations

+

Foundations are how we express our brand through color, space, typography, etc.

+
+
+

Design tokens

+

Design tokens are how we translate our design language decisions into code.

+
+
+

Documentation

+

This website offers guidance about how to use our elements and patterns correctly.

+
+
+

GitHub repositories

+

Explore our code, roadmaps, and discussions in the Red Hat Design System repo and the Red Hat Design Tokens repo.

+
+
+ +## About Web Components + + + +{% feedback %} +

Designers

+

To get started using our design system as a designer, go to the Designers page.

+{% endfeedback %} \ No newline at end of file diff --git a/docs/get-started/developers/installation.md b/docs/get-started/developers/installation.md new file mode 100644 index 0000000000..accbb8e1c7 --- /dev/null +++ b/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: 20 +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. + + +curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash + + +**Mac users** should install Homebrew. Go to the website or run this command (takes 5-10 minutes). + + +/bin/bash -c "$(curl -fsSL +https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + + +Then use that to install `nvm`: + + +brew install nvm + + +### Step 2: Clone the repository + +Clone the repository and change the directory to it: + + +git clone git@github.com:redhat-ux/red-hat-design-system +cd red-hat-design-system + + +### Step 3: Install dependencies + +Install the right node version using `nvm`, then install the `node_modules` dependencies: + + +nvm use +npm ci + + +## How to generate an element + +Run the following command to begin the scaffolding process: + + +npm run new + + +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: + + +npm start + + +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: + + +npm-run-dev + + +To run only the docs dev server, first run the build, then 11ty: + + +npm run build +npx eleventy --serve --incremental + + +{% feedback %} +

Designers

+

To get started using our design system as a designer, go to the Designers page.

+{% endfeedback %} \ No newline at end of file diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md new file mode 100644 index 0000000000..4c0984fe83 --- /dev/null +++ b/docs/get-started/developers/tokens.md @@ -0,0 +1,88 @@ +--- +layout: layout-with-subnav.njk +title: Tokens +heading: Developers +tags: + - developers +permalink: /get-started/developers/tokens/index.html +order: 20 +bodyClasses: element-docs +--- + +## How to install tokens + +Run the following git command to install RHDS tokens: + + +npm i @rhds/tokens + + +## 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: + + + + + + +### Reset the shadowroot + +Reset a component's styles (preventing inheritance) by adding resetStyles to its static Constructible Style Sheet list: + + +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]; +} + + +### Import tokens as JavaScript objects + + + +Import tokens as JavaScript objects: + + +import { tokens } from '@rhds/tokens'; + +html`I'm blue`; + + +or for tree-shakable imports: + + +import { ColorBlue300 } from '@rhds/tokens/values.js'; + +html`I'm blue`; + + +## Plugins + +### Using editor snippets + +Editor snippets complete prefixes like `--rh-color-brand` to their CSS custom properties, complete with fallback. + + +color: var(--rh-color-brand, #ee0000); + + +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. \ No newline at end of file diff --git a/docs/get-started/developers/usage.md b/docs/get-started/developers/usage.md new file mode 100644 index 0000000000..7ace8e7e75 --- /dev/null +++ b/docs/get-started/developers/usage.md @@ -0,0 +1,32 @@ +--- +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 + +## 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 %} +

Designers

+

To get started using our design system as a designer, go to the Designers page.

+{% endfeedback %} \ No newline at end of file From 4b6fdab60176f588fe47d3a152babb8db64da3a7 Mon Sep 17 00:00:00 2001 From: marionnegp Date: Wed, 17 Jan 2024 16:29:55 -0500 Subject: [PATCH 02/13] feat: add script tags to some code blocks --- docs/get-started/developers/tokens.md | 68 +++++++++++++++++++++++++-- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md index 4c0984fe83..43ed3cce06 100644 --- a/docs/get-started/developers/tokens.md +++ b/docs/get-started/developers/tokens.md @@ -26,12 +26,14 @@ We use [style-dictionary](https://amzn.github.io/style-dictionary/) to transform Apply defaults to the document root by importing the global stylesheet: + ### Reset the shadowroot @@ -39,6 +41,7 @@ Apply defaults to the document root by importing the global stylesheet: Reset a component's styles (preventing inheritance) by adding resetStyles to its static Constructible Style Sheet list: + ### Import tokens as JavaScript objects - +{% endalert %} Import tokens as JavaScript objects: + or for tree-shakable imports: + ## Plugins @@ -78,11 +85,64 @@ html`I'm blue`; Editor snippets complete prefixes like `--rh-color-brand` to their CSS custom properties, complete with fallback. + 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. \ No newline at end of file +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: + + +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' +} } + + +### 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}`. + + +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' +} + + +{% feedback %} +

Designers

+

To get started using our design system as a designer, go to the Designers page.

+{% endfeedback %} \ No newline at end of file From 5eafcf3559da4fd19aa65d63994e8760f35dacf6 Mon Sep 17 00:00:00 2001 From: marionnegp Date: Wed, 17 Jan 2024 20:23:20 -0500 Subject: [PATCH 03/13] feat: fix page order and headings --- docs/get-started/developers/installation.md | 2 +- docs/get-started/developers/tokens.md | 2 +- docs/get-started/developers/usage.md | 4 +++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/get-started/developers/installation.md b/docs/get-started/developers/installation.md index accbb8e1c7..b8dff9c3ff 100644 --- a/docs/get-started/developers/installation.md +++ b/docs/get-started/developers/installation.md @@ -5,7 +5,7 @@ heading: Developers tags: - developers permalink: /get-started/developers/installation/index.html -order: 20 +order: 10 bodyClasses: element-docs --- diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md index 43ed3cce06..b6fdb4a9c1 100644 --- a/docs/get-started/developers/tokens.md +++ b/docs/get-started/developers/tokens.md @@ -5,7 +5,7 @@ heading: Developers tags: - developers permalink: /get-started/developers/tokens/index.html -order: 20 +order: 30 bodyClasses: element-docs --- diff --git a/docs/get-started/developers/usage.md b/docs/get-started/developers/usage.md index 7ace8e7e75..651705ba40 100644 --- a/docs/get-started/developers/usage.md +++ b/docs/get-started/developers/usage.md @@ -19,7 +19,9 @@ bodyClasses: element-docs ### Vue wrappers -### Adding icons +## Adding icons + +## Customizing ## Other resources From a4b33430a460cdfeda3bfb10bccbc12bc68b2e3b Mon Sep 17 00:00:00 2001 From: marionnegp Date: Wed, 17 Jan 2024 20:42:44 -0500 Subject: [PATCH 04/13] fix: add script tags --- docs/get-started/developers/installation.md | 44 +++++++++++----- docs/get-started/developers/tokens.md | 58 ++++++++++++--------- 2 files changed, 63 insertions(+), 39 deletions(-) diff --git a/docs/get-started/developers/installation.md b/docs/get-started/developers/installation.md index b8dff9c3ff..3eae5aba05 100644 --- a/docs/get-started/developers/installation.md +++ b/docs/get-started/developers/installation.md @@ -18,20 +18,26 @@ To develop components or design system documentation, you must first install som **Fedora/RHEL users** should install nvm for bash directly from GitHub. -curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash + **Mac users** should install Homebrew. Go to the website or run this command (takes 5-10 minutes). -/bin/bash -c "$(curl -fsSL -https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + Then use that to install `nvm`: -brew install nvm + ### Step 2: Clone the repository @@ -39,8 +45,10 @@ brew install nvm Clone the repository and change the directory to it: -git clone git@github.com:redhat-ux/red-hat-design-system -cd red-hat-design-system + ### Step 3: Install dependencies @@ -48,8 +56,10 @@ cd red-hat-design-system Install the right node version using `nvm`, then install the `node_modules` dependencies: -nvm use -npm ci + ## How to generate an element @@ -57,7 +67,9 @@ npm ci Run the following command to begin the scaffolding process: -npm run new + The generator will prompt you for the following: @@ -74,7 +86,9 @@ After answering the script will generate a bootstrapped element in the `elements Run the dev server to develop components: -npm start + 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. @@ -82,14 +96,18 @@ This starts a local dev server at http://localhost:8000 and the 11ty dev server To run only the components dev server, first run the build, and then run the dev server: -npm-run-dev + To run only the docs dev server, first run the build, then 11ty: -npm run build -npx eleventy --serve --incremental + {% feedback %} diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md index b6fdb4a9c1..4dfb353a93 100644 --- a/docs/get-started/developers/tokens.md +++ b/docs/get-started/developers/tokens.md @@ -14,7 +14,9 @@ bodyClasses: element-docs Run the following git command to install RHDS tokens: -npm i @rhds/tokens + ## Usage @@ -26,13 +28,13 @@ We use [style-dictionary](https://amzn.github.io/style-dictionary/) to transform Apply defaults to the document root by importing the global stylesheet: - @@ -101,10 +103,12 @@ Download the VSIX bundle that’s linked at the bottom of our [“Release v1.0.0 Use LunaSnip to load snippets in Neovim: -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' -} } + ### Stylelint plugin @@ -124,22 +128,24 @@ Vim users can load the [vim-hexokinase](https://github.com/RRethy/vim-hexokinase Use the following config (lua syntax, for Neovim users) to configure hexokinase to display color values next to color aliases like `{color.brand.red}`. -vim.g.Hexokinase_optInPatterns = { - 'full_hex', 'triple_hex', - 'rgb', 'rgba', - 'hsl', 'hsla', - 'colour_names', -} + {% feedback %} From 3b1f5de10e11bfeea48874ed3d1e84ccb26805cc Mon Sep 17 00:00:00 2001 From: marionnegp Date: Wed, 24 Jan 2024 14:27:47 -0500 Subject: [PATCH 05/13] feat: updated installation content and code on Tokens subpage --- docs/get-started/developers/installation.md | 25 ++------------------- docs/get-started/developers/tokens.md | 2 +- 2 files changed, 3 insertions(+), 24 deletions(-) diff --git a/docs/get-started/developers/installation.md b/docs/get-started/developers/installation.md index 3eae5aba05..60b70786cd 100644 --- a/docs/get-started/developers/installation.md +++ b/docs/get-started/developers/installation.md @@ -15,30 +15,9 @@ To develop components or design system documentation, you must first install som ### Step 1: Install node -**Fedora/RHEL users** should install nvm for bash directly from GitHub. +**Fedora/RHEL users** should install [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) for bash directly from GitHub. - - - - -**Mac users** should install Homebrew. Go to the website or run this command (takes 5-10 minutes). - - - - - -Then use that to install `nvm`: - - - - +**Mac users** should install [Homebrew](https://brew.sh/). Then use that to install `nvm`. ### Step 2: Clone the repository diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md index 4dfb353a93..870b60548d 100644 --- a/docs/get-started/developers/tokens.md +++ b/docs/get-started/developers/tokens.md @@ -49,7 +49,7 @@ import style from './rh-jazz-hands.css'; @customElement('rh-jazz-hands') export class RhJazzHands extends LitElement { - static readonly styles = [resetStyles, style]; + static readonly styles = [...resetStyles, style]; } From 3627ddade61f034b7d3fc271e1af3f7db63004ec Mon Sep 17 00:00:00 2001 From: marionnegp Date: Tue, 30 Jan 2024 09:28:09 -0500 Subject: [PATCH 06/13] feat: change layout-with-subnav template and frontmatter --- docs/_includes/layout-with-subnav.njk | 6 ++++-- docs/foundations/color/accessibility.md | 1 + docs/foundations/color/index.md | 1 + docs/foundations/color/usage.md | 1 + docs/get-started/developers/index.md | 1 + docs/get-started/developers/installation.md | 1 + docs/get-started/developers/tokens.md | 1 + docs/get-started/developers/usage.md | 1 + 8 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/_includes/layout-with-subnav.njk b/docs/_includes/layout-with-subnav.njk index 5f65951bf1..81f792b66d 100644 --- a/docs/_includes/layout-with-subnav.njk +++ b/docs/_includes/layout-with-subnav.njk @@ -15,14 +15,16 @@ importElements:
-
+

{{ heading or title }}

+ {% if subNavCollection %} - {% for tab in collections.sortedColor %} + {% for tab in collections[subNavCollection] %} {{ tab.data.title }} {% endfor %} + {% endif %}
diff --git a/docs/foundations/color/accessibility.md b/docs/foundations/color/accessibility.md index fe3afbc1f0..6282e79675 100644 --- a/docs/foundations/color/accessibility.md +++ b/docs/foundations/color/accessibility.md @@ -5,6 +5,7 @@ heading: Color tags: - color permalink: /foundations/color/accessibility/index.html +subNavCollection: sortedColor order: 20 bodyClasses: element-docs --- diff --git a/docs/foundations/color/index.md b/docs/foundations/color/index.md index c003aef94f..786ce2515c 100644 --- a/docs/foundations/color/index.md +++ b/docs/foundations/color/index.md @@ -6,6 +6,7 @@ tags: - foundations - color permalink: /foundations/color/index.html +subNavCollection: sortedColor order: 00 bodyClasses: element-docs --- diff --git a/docs/foundations/color/usage.md b/docs/foundations/color/usage.md index 4c25a6f67d..4a3dd66f29 100644 --- a/docs/foundations/color/usage.md +++ b/docs/foundations/color/usage.md @@ -5,6 +5,7 @@ heading: Color tags: - color permalink: /foundations/color/usage/index.html +subNavCollection: sortedColor order: 10 bodyClasses: element-docs --- diff --git a/docs/get-started/developers/index.md b/docs/get-started/developers/index.md index 993eeb9099..3da0b89994 100644 --- a/docs/get-started/developers/index.md +++ b/docs/get-started/developers/index.md @@ -6,6 +6,7 @@ tags: - getstarted - developers permalink: /get-started/developers/index.html +subNavCollection: sortedDevelopers order: 00 bodyClasses: element-docs --- diff --git a/docs/get-started/developers/installation.md b/docs/get-started/developers/installation.md index 60b70786cd..7ffd8c0f58 100644 --- a/docs/get-started/developers/installation.md +++ b/docs/get-started/developers/installation.md @@ -5,6 +5,7 @@ heading: Developers tags: - developers permalink: /get-started/developers/installation/index.html +subNavCollection: sortedDevelopers order: 10 bodyClasses: element-docs --- diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md index 870b60548d..544b133517 100644 --- a/docs/get-started/developers/tokens.md +++ b/docs/get-started/developers/tokens.md @@ -5,6 +5,7 @@ heading: Developers tags: - developers permalink: /get-started/developers/tokens/index.html +subNavCollection: sortedDevelopers order: 30 bodyClasses: element-docs --- diff --git a/docs/get-started/developers/usage.md b/docs/get-started/developers/usage.md index 651705ba40..28da382d2d 100644 --- a/docs/get-started/developers/usage.md +++ b/docs/get-started/developers/usage.md @@ -5,6 +5,7 @@ heading: Developers tags: - developers permalink: /get-started/developers/usage/index.html +subNavCollection: sortedDevelopers order: 20 bodyClasses: element-docs --- From f0ac46aa77028ad75ac7c53dac0f74983892fee8 Mon Sep 17 00:00:00 2001 From: marionnegp Date: Tue, 30 Jan 2024 12:44:24 -0500 Subject: [PATCH 07/13] fix: Change the link in the side nav from "Overview" to "Developers" --- docs/_includes/component/header.njk | 4 ++-- docs/get-started/designers.md | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/_includes/component/header.njk b/docs/_includes/component/header.njk index 10110bb862..82ad9d856a 100755 --- a/docs/_includes/component/header.njk +++ b/docs/_includes/component/header.njk @@ -48,7 +48,7 @@ - +
  • @@ -61,7 +61,7 @@ {%- for link in collections.getstarted -%}
  • {{ link.data.title }} + href="{{ link.url | url }}">{{ link.data.heading }}
    • {%- endfor -%} diff --git a/docs/get-started/designers.md b/docs/get-started/designers.md index 809ac9cbc6..b7a1a8229d 100644 --- a/docs/get-started/designers.md +++ b/docs/get-started/designers.md @@ -1,6 +1,7 @@ --- layout: layout-basic.njk title: Designers +heading: Designers order: 2 tags: - getstarted From 9c3608473029470dfb6791aafe0b28a0a36f2e3c Mon Sep 17 00:00:00 2001 From: marionnegp Date: Tue, 30 Jan 2024 12:46:14 -0500 Subject: [PATCH 08/13] feat: link to Developers page from Get Started: Overview --- docs/get-started.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/get-started.md b/docs/get-started.md index 36ebc2c841..9eb0f0f817 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -37,13 +37,15 @@ The Red Hat Design System for digital experiences gives designers and developers
    Designers
    -
    - {% example - palette="descriptive", - alt="Card overlapping code editor user interface", - src="/assets/get-started/developers.png" %} -
    Developers (Coming soon)
    -
    + +
    + {% example + palette="descriptive", + alt="Card overlapping code editor user interface", + src="/assets/get-started/developers.png" %} +
    Developers
    +
    +     {% feedback %} From 36bbb9c7ca5ba84971bcae5bda2d99f9177f7db1 Mon Sep 17 00:00:00 2001 From: marionnegp Date: Wed, 10 Apr 2024 13:36:09 -0400 Subject: [PATCH 09/13] feat: add usage content and update installation info --- docs/get-started/developers/index.md | 9 ++- docs/get-started/developers/installation.md | 87 ++++++++++++--------- docs/get-started/developers/usage.md | 74 ++++++++++++++++-- 3 files changed, 123 insertions(+), 47 deletions(-) diff --git a/docs/get-started/developers/index.md b/docs/get-started/developers/index.md index 3da0b89994..462f43a14b 100644 --- a/docs/get-started/developers/index.md +++ b/docs/get-started/developers/index.md @@ -13,8 +13,9 @@ bodyClasses: element-docs ## Introduction - +Welcome to the **Red Hat Design System** (RHDS) for digital experiences. If you need to develop something using our design system, you have come to the right place. +Read this section to get started and e-mail [design-system@redhat.com](mailto:design-system@redhat.com) or connect with us on Slack if you have any questions along the way. ## Learn about our design system @@ -39,9 +40,11 @@ Our design system libraries and the documentation website offer assets and guida
    • -## About Web Components +## About web components - +Web components are based on a set of web platform APIs that help to create reusable and encapsulated UI elements. Those standards consist of custom elements, shadow DOM, and HTML Templates. + +Because they're able to work with any framework that supports HTML, web components can be used without having to rework all of your code and are less likely to be affected by changes in preferred web stacks. Encapsulation within the shadow DOM prevents a page's code from breaking a component's style and allows for a scalable design system. {% feedback %}

    Designers

    diff --git a/docs/get-started/developers/installation.md b/docs/get-started/developers/installation.md index 7ffd8c0f58..e4d6db4240 100644 --- a/docs/get-started/developers/installation.md +++ b/docs/get-started/developers/installation.md @@ -12,83 +12,94 @@ 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. +There are three ways you can install the Red Hat Design System's web components: CDN, NPM, or JSPM. Each element's "Code" page includes the same installation information with code snippets that are specific to that element. -### Step 1: Install node +### Red Hat CDN -**Fedora/RHEL users** should install [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) for bash directly from GitHub. +{% alert title="CDN Prerelease", + state="warning" %} +

    We are currently working on our CDN, which will be soon moving into beta. This will be the preferred method of installation in the near future. If you are a Red Hat associate and have questions or comments about the CDN or installation process please connect with us on Slack.

    +{% endalert %} -**Mac users** should install [Homebrew](https://brew.sh/). Then use that to install `nvm`. +The recommended way to load RHDS is via the Red Hat Digital Experience CDN, and using an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap). -### Step 2: Clone the repository - -Clone the repository and change the directory to it: +If you have full control over the page you are using, add an import map to the ``, pointing to the CDN, or update any existing import map. If you are not responsible for the page's ``, request that the page owner makes the change on your behalf. -### Step 3: Install dependencies - -Install the right node version using `nvm`, then install the `node_modules` dependencies: +Once the import map is established, you can load the element with the following module, containing a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). The example below shows how you'd load in <`rh-button>`. -## How to generate an element +Note that modules may be placed in the ``. Since they are deferred by default, they will not block rendering. + +### NPM -Run the following command to begin the scaffolding process: +Install RHDS using your team's preferred NPM package manager. -The generator will prompt you for the following: +Once that's been accomplished, you will need to use a bundler to resolve the bare module specifiers and optionally optimize the package for your site's particular use case and needs. Comprehensive guides to bundling are beyond the scope of this page; read more about bundlers on their websites: -What is the element tag name? +- [Rollup](https://rollupjs.org/) +- [esbuild](https://esbuild.github.io/) +- [Parcel](https://parceljs.org/) +- [Webpack](https://webpack.js.org/) -- 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. +### JSPM -After answering the script will generate a bootstrapped element in the `elements/your-element` directory complete with a`demo` and `test` directory. +{% alert title="Public CDNs", + state="warning" %} +

    JSPM and other public CDNs should not be used on corporate domains. Use them for development purposes only!

    +{% endalert %} -## Run the dev server - -Run the dev server to develop components: +Add an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to the ``, pointing to the CDN, or update any existing import map. -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: +Once the import map is established, you can load the element with the following module, containing a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). The example below shows how you'd load in <`rh-button>`. -To run only the docs dev server, first run the build, then 11ty: - - - - +Note that Modules may be placed in the ``. Since they are deferred by default, they will not block rendering. {% feedback %}

    Designers

    diff --git a/docs/get-started/developers/usage.md b/docs/get-started/developers/usage.md index 28da382d2d..8de2daf335 100644 --- a/docs/get-started/developers/usage.md +++ b/docs/get-started/developers/usage.md @@ -12,17 +12,79 @@ bodyClasses: element-docs ## Usage -### Using npm +Now that you've installed the Red Hat Design System, here's more information about how to use the web components. -### Using the CDN +### Using react wrappers -### React wrappers +React wrappers make it possible to use web components within React JSX files. Follow the steps below to learn how. -### Vue wrappers +#### 1. Initial setup -## Adding icons +We'll bootstrap our React app using Vite. It's possible to use other tools for this, but that is out of the scope of this tutorial. -## Customizing + + + + +This command will ask you to provide the project name, framework, and variant. + +#### 2. Install the `@lit/react` library + +Use the following command: + + + + + +#### 3. Import elements and patterns + +After installing the `@lit/react` library, you can import elements and patterns to your file. Below is an example of importing `` and ``. + + + + + +### Using Vue wrappers + +To get web components to work with Vue, it’s pretty easy and straightforward. Follow the steps below to use web components in a Vue app. + +#### 1. Initial setup + +Add these two lines at the top of the `main.js` file in the `/src/` directory. + + + + + +#### 2. Import elements and patterns + +Add the import statements to the top of the ` + ## Other resources From 3632b064b52cb20a6c1e56738a3889b716c7c2b6 Mon Sep 17 00:00:00 2001 From: marionnegp Date: Wed, 10 Apr 2024 16:55:29 -0400 Subject: [PATCH 10/13] fix: add script tags to code blocks --- docs/get-started/developers/tokens.md | 32 ++++++++++++++++++--------- docs/get-started/developers/usage.md | 4 +++- 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md index 544b133517..b134cec1ff 100644 --- a/docs/get-started/developers/tokens.md +++ b/docs/get-started/developers/tokens.md @@ -45,13 +45,15 @@ Reset a component's styles (preventing inheritance) by adding resetStyles to its -@customElement('rh-jazz-hands') -export class RhJazzHands extends LitElement { - static readonly styles = [...resetStyles, style]; -} + @@ -65,9 +67,11 @@ Import tokens as JavaScript objects: -html`I'm blue`; + @@ -75,9 +79,11 @@ or for tree-shakable imports: -html`I'm blue`; + @@ -89,7 +95,7 @@ Editor snippets complete prefixes like `--rh-color-brand` to their CSS custom pr @@ -136,12 +142,16 @@ Use the following config (lua syntax, for Neovim users) to configure hexokinase 'hsl', 'hsla', 'colour_names', } + + + + @@ -81,7 +83,7 @@ Add the import statements to the top of the ` From 8c218f460a969067a21435e23690ee40cfd8e93c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benny=20Powers=20-=20=D7=A2=D7=9D=20=D7=99=D7=A9=D7=A8?= =?UTF-8?q?=D7=90=D7=9C=20=D7=97=D7=99!?= Date: Thu, 18 Apr 2024 18:08:42 +0300 Subject: [PATCH 11/13] docs: update docs/get-started/developers/tokens.md --- docs/get-started/developers/tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/developers/tokens.md b/docs/get-started/developers/tokens.md index b134cec1ff..9b0a9970c2 100644 --- a/docs/get-started/developers/tokens.md +++ b/docs/get-started/developers/tokens.md @@ -107,7 +107,7 @@ Download the VSIX bundle that’s linked at the bottom of our [“Release v1.0.0 #### Load snippets in Neovim -Use LunaSnip to load snippets in Neovim: +Use LuaSnip to load snippets in Neovim: -### Using Vue wrappers +### Using RHDS elements with Vue To get web components to work with Vue, it’s pretty easy and straightforward. Follow the steps below to use web components in a Vue app. From 6c01bf7eb1c58dc8ebb1bd288f969d31d42eba7c Mon Sep 17 00:00:00 2001 From: Benny Powers Date: Thu, 18 Apr 2024 18:25:20 +0300 Subject: [PATCH 13/13] docs: react usage --- docs/get-started/developers/usage.md | 31 +++++++++++++++++++++------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/get-started/developers/usage.md b/docs/get-started/developers/usage.md index 4df785b5a1..b571d486fc 100644 --- a/docs/get-started/developers/usage.md +++ b/docs/get-started/developers/usage.md @@ -42,16 +42,31 @@ Use the following command: #### 3. Import elements and patterns -After installing the `@lit/react` library, you can import elements and patterns to your file. Below is an example of importing `` and ``. +After installing the `@lit/react` library, you can import elements and patterns +to your file. Below is an example of importing `` and ``, and +managing app state between them using react. - - @@ -96,4 +111,4 @@ Add the import statements to the top of the `