From d25c8c2de0660c2b851ea81e1b87213229220264 Mon Sep 17 00:00:00 2001 From: Marionne Patel <95588923+marionnegp@users.noreply.github.com> Date: Tue, 3 Dec 2024 09:35:07 -0500 Subject: [PATCH 1/4] docs(subnav): update best practices (#2072) * docs(subnav): update best practices * docs(subnav): fix typos in "Best practices" section --- elements/rh-subnav/docs/20-guidelines.md | 172 ++++++++++++------ .../subnav-best-practices-max-links-do.svg | 12 ++ .../subnav-best-practices-max-links-dont.svg | 44 +++++ .../subnav-best-practices-min-links-do.svg | 9 + .../subnav-best-practices-min-links-dont.svg | 8 + .../subnav-best-practices-nav-order-do.svg | 65 +++++++ .../subnav-best-practices-nav-order-dont.svg | 65 +++++++ ...nav-best-practices-overflow-buttons-do.svg | 39 ++++ ...v-best-practices-overflow-buttons-dont.svg | 38 ++++ ...subnav-best-practices-spacing-width-do.svg | 10 + ...bnav-best-practices-spacing-width-dont.svg | 10 + 11 files changed, 416 insertions(+), 56 deletions(-) create mode 100644 elements/rh-subnav/docs/subnav-best-practices-max-links-do.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-max-links-dont.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-min-links-do.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-min-links-dont.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-nav-order-do.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-nav-order-dont.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-do.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-dont.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-spacing-width-do.svg create mode 100644 elements/rh-subnav/docs/subnav-best-practices-spacing-width-dont.svg diff --git a/elements/rh-subnav/docs/20-guidelines.md b/elements/rh-subnav/docs/20-guidelines.md index cdd8794e47..d40e057c1b 100644 --- a/elements/rh-subnav/docs/20-guidelines.md +++ b/elements/rh-subnav/docs/20-guidelines.md @@ -210,62 +210,122 @@ labels. ## Best practices -### Incorrect ordering - -Do not position the subnavigation above the primary navigation. - - - Image of a subnavigation above the primary navigation, which is incorrect usage - - - -### Not enough links - -There should be at least two links minimum. - - - Image of a subnavigation with only one link, which is incorrect usage - - - -### Too many links - -Be careful about displaying too many links, some of them will become hidden even -at large breakpoints. - - - Image of a subnavigation with seven links and overflow buttons, which is incorrect usage - - - -### Extra spacing - -Do not add extra spacing or stretch the width of links. - - - Image of a subnavigation with stretched links, which is incorrect usage - - +### Navigation order + + + + Subnavigation positioned below primary nav + + +

Subnavigation should always appear below the primary navigation.

+ + + + + Subnavigation positioned above primary nav + + +

Do not position the subnavigation above the primary navigation.

+ + +### Minimum number of links + +
+ + + Subnavigation with two links + +

There should be at least two links in subnavigation.

+ + + + + Subnavigation with one link + +

Do not add only one subnavigation link.

+ +
+ +### Maximum number of links + + + + Subnavigation at a large breakpoint with five links + + +

There is no specific maximum number of links, but use a reasonable number of links.

+ + + + + Subnavigation at a large breakpoint with more than eight links and with visible overflow buttons + + +

Avoid displaying too many links. Some will become hidden, even at large breakpoints.

+ + +### Spacing and width + + + + Subnavigation with links using default spacing + + +

Retain the default spacing and width of each subnavigation link.

+ + + + + Subnavigation with links that use extra spacing on the left and right + + +

Do not add extra spacing or stretch the width of links.

+ ### Overflow buttons -Overflow buttons should not be visible if all links are visible. - - - Image of a subnavigation with only two links and overflow buttons, which is incorrect usage - + + + Subnavigation with at least three links in a smaller viewport with overflow buttons + + +

Use overflow buttons if not all of the links can fit.

+ + + + + Subnavigation with two short links in a smaller viewport with overflow buttons + + +

Do not make overflow buttons visible if all links can comfortably fit and are visible.

+ \ No newline at end of file diff --git a/elements/rh-subnav/docs/subnav-best-practices-max-links-do.svg b/elements/rh-subnav/docs/subnav-best-practices-max-links-do.svg new file mode 100644 index 0000000000..9d9d603150 --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-max-links-do.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-max-links-dont.svg b/elements/rh-subnav/docs/subnav-best-practices-max-links-dont.svg new file mode 100644 index 0000000000..46b54bec7e --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-max-links-dont.svg @@ -0,0 +1,44 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-min-links-do.svg b/elements/rh-subnav/docs/subnav-best-practices-min-links-do.svg new file mode 100644 index 0000000000..2a5c88e3b8 --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-min-links-do.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-min-links-dont.svg b/elements/rh-subnav/docs/subnav-best-practices-min-links-dont.svg new file mode 100644 index 0000000000..409349fb04 --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-min-links-dont.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-nav-order-do.svg b/elements/rh-subnav/docs/subnav-best-practices-nav-order-do.svg new file mode 100644 index 0000000000..16954a17ec --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-nav-order-do.svg @@ -0,0 +1,65 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-nav-order-dont.svg b/elements/rh-subnav/docs/subnav-best-practices-nav-order-dont.svg new file mode 100644 index 0000000000..97ecef64b0 --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-nav-order-dont.svg @@ -0,0 +1,65 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-do.svg b/elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-do.svg new file mode 100644 index 0000000000..c618a58a51 --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-do.svg @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-dont.svg b/elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-dont.svg new file mode 100644 index 0000000000..c21b9c08c8 --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-overflow-buttons-dont.svg @@ -0,0 +1,38 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-spacing-width-do.svg b/elements/rh-subnav/docs/subnav-best-practices-spacing-width-do.svg new file mode 100644 index 0000000000..5c2b0223fe --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-spacing-width-do.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/elements/rh-subnav/docs/subnav-best-practices-spacing-width-dont.svg b/elements/rh-subnav/docs/subnav-best-practices-spacing-width-dont.svg new file mode 100644 index 0000000000..0693a5451a --- /dev/null +++ b/elements/rh-subnav/docs/subnav-best-practices-spacing-width-dont.svg @@ -0,0 +1,10 @@ + + + + + + + + + + From 2195be206198d441dd2fbec83769dcfd65f7011c Mon Sep 17 00:00:00 2001 From: Benny Powers Date: Thu, 5 Dec 2024 10:54:52 +0200 Subject: [PATCH 2/4] docs: fix edit this page links closes #2074 --- docs/_includes/partials/component/edit-this-page.njk | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/_includes/partials/component/edit-this-page.njk b/docs/_includes/partials/component/edit-this-page.njk index fad40be243..9f8fcfd2bb 100644 --- a/docs/_includes/partials/component/edit-this-page.njk +++ b/docs/_includes/partials/component/edit-this-page.njk @@ -9,7 +9,6 @@ {% endif %} {% endfor %} {% endif %} - {# remove ./ leading on path #} - {% set editPath = (inputPath or page.inputPath) | replace('./', '/') %} - Edit this page on GitHub - \ No newline at end of file + {% set editPath = ('/' + (inputPath or page.inputPath)) | replace(r/^(\.)?\//, '') %} + Edit this page on GitHub + From 450b81023a25d6c38c7b841dbe37cf99ba18a2f6 Mon Sep 17 00:00:00 2001 From: Benny Powers Date: Thu, 5 Dec 2024 16:51:26 +0200 Subject: [PATCH 3/4] docs(tokens): print descriptions for token groups --- docs/_includes/layouts/pages/tokens.11ty.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_includes/layouts/pages/tokens.11ty.ts b/docs/_includes/layouts/pages/tokens.11ty.ts index 0e397ca491..ab5291210d 100644 --- a/docs/_includes/layouts/pages/tokens.11ty.ts +++ b/docs/_includes/layouts/pages/tokens.11ty.ts @@ -365,9 +365,10 @@ export default class TokensPage extends Renderer { `; + const description = options.tokens._?.$description ?? options.tokens.$description ?? ''; return html` ${permalink} -
${await this.renderTemplate(options.tokens.$description ?? '', 'md')}
+
${await this.renderTemplate(description, 'md')}
${this.#renderThemeTokensCard(options)} ${await this.#renderTable(options)} ${await this.#renderChildren(options)} From 217377b82ea2978354f4ecd475047f9cde221166 Mon Sep 17 00:00:00 2001 From: Benny Powers Date: Thu, 5 Dec 2024 16:55:29 +0200 Subject: [PATCH 4/4] docs(tokens): print all category descriptions --- docs/_includes/layouts/pages/tokens.11ty.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_includes/layouts/pages/tokens.11ty.ts b/docs/_includes/layouts/pages/tokens.11ty.ts index ab5291210d..7f511bcdf7 100644 --- a/docs/_includes/layouts/pages/tokens.11ty.ts +++ b/docs/_includes/layouts/pages/tokens.11ty.ts @@ -365,7 +365,7 @@ export default class TokensPage extends Renderer { `; - const description = options.tokens._?.$description ?? options.tokens.$description ?? ''; + const description = `${options.tokens.$description ?? ''}\n\n${options.tokens._?.$description ?? ''}`.trim(); return html` ${permalink}
${await this.renderTemplate(description, 'md')}