[Docs] Add ThemeLanguages and new Breakpoints page #5227

cchaos · 2021-09-29T22:22:29Z

As part of the CSS-in-JS effort, we now have several ways consumers can consume our theme tokens; via Sass, JS (Theme context), or JSON (exports our Sass tokens as a JSON object). Our docs are currently confusing as to where/how to consume these tokens and might be one of the reasons why still see some raw pixel values downstream.

This PR is just the first of many that will cleanup and consolidate these theme token pages to hopefully make it clearer how to consume them and in their language of choice. It sets up a lot of reused components and the first converted page for "Breakpoints" as an example.

This PR is against master because it is docs only and has no dependencies on the feature branch.

1. Added a ThemeSelector for optionally showing/changing content based on JS or Sass theming language

I've created a button toggle that can be visually turned on via a new prop showThemeLanguageToggle on GuidePage. This toggle is hooked in the docs' ThemeContext and therefore the value of which can be consumed via:

  const themeContext = useContext(ThemeContext);
  const currentLanguage = themeContext.themeLanguage;

It currently saves the value of the button in local storage so as users come and go, their selection will remain (similar to the theme selector).

I've also added a tour for new visitors 😄

Notes

There could be debate whether this should live in the header like the theme selector or only down in the page header as it is here. I've opted for only showing it on the pages that utilize it (at least for now) since there are a lot more that don't than do. Eventually, (maybe when we're more overall converted) we can move it to a more global location.

2. Added some theme helper components like alert banners, values table, and example row

Under src-docs/theme I added a components folder with additional shared components that I'll use throughout. This includes having one place for the banner alerts that look like:

The other components help to build out the repetitive portions of the

values tables:

and example panels:

3 [Manual] Copied the output json version of Sass for easier consumption in docs rather than sass-loader

~~This is a portion that I could use some engineering help with.~~

So far we've been using the !!sass-vars-to-js-loader! method to import Sass files to read the values of some tokens. This only works if the token is as stright string or reference to a string. It cannot run functions or mixins. So those docs tended to be manual, and lightly kept up to date.

What does do all those calculations is our JSON converter. Which also doesn't rely on a specific loading order. So I've setup a folder where ~~I manually copy/pasted~~ the JSON theme files are copied from the dist to src-docs/themes/json at build time. Now I can read all our Sass tokens directly from that and we can either setup a script to always output this on Sass updates or docs build.

So in the Sass portion of the docs we can just grab them like:

  const values = useJsonVars();
  const euiBreakpoints = values.euiBreakpoints;
  const euiBreakpointKeys = Object.keys(euiBreakpoints);

4. Rearranged sidenav to promote Theme section and adding “Breakpoints”

Now to the actual visible changes to the docs pages, I've moved the new "Theming" section to right after the Guidelines section. The context-based theming and Sass pages are mostly untouched, but I did add a page for detailing "Breakpoints".

This is the one of the few theme detailing pages to come and is the simplest.

5. Global values will slowly become the "Customizer"

As I move the full explanation of all the tokens to their separate theme files, I am also simplifying the "Global values" page to be just the token name, type and value updater.

I will also be deleting those sections from the existing Sass page.

Checklist

Check against all themes for compatibility in both light and dark modes
[ ] Checked in mobile I'll follow up with better responsive value tables
Checked in Chrome, Safari, Edge, and Firefox
Props have proper autodocs and playground toggles
Added documentation
~~[ ] Checked Code Sandbox works for any docs examples~~
[ ] Added or updated jest tests
~~[ ] Checked for breaking changes and labeled appropriately~~
Checked for accessibility including keyboard-only and screenreader modes
~~[ ] A changelog entry exists and is marked appropriately~~

…n JS or Sass theming language

…and example row

…on in docs rather that sass-loader

This reverts commit f3eccfb.

…rgb`" This reverts commit 2db22a4.

cchaos

This PR is ready for review. Don't be scared by the line count 😺 , that's mostly from the addition of JSON files. I'm also completely open to any optimizations. Feel free to push directly.

But please do read through the PR summary first where I detail decisions made.

cchaos · 2021-09-29T22:46:05Z

src-docs/src/components/with_theme/theme_context.tsx

+export const theme_languages: THEME_LANGUAGES[] = [
+  {
+    id: 'language--js',
+    label: 'JS',
+    title: 'Language selector: CSS-in-JS',
+  },
+  {
+    id: 'language--sass',
+    label: 'Sass',
+    title: 'Language selector: Sass',
+  },
+];


The labels for these button are up for debate. Mainly that I couldn't think of anything better than JS for the Emotion stuff.

No strong opinions in here personally, the only thing I can even remotely think of is changing the label to CSS-in-JS instead of just JS which feels a little wordier and more awkward, but does has a specific keyword connotation over just "JS". I'd be fine either way tbh

CSS-in-JS instead of just JS

Same thought, but also unsure if it's better

cchaos · 2021-09-29T22:50:18Z

src-docs/src/views/theme/_components/_theme_values_table.tsx

+        // width: '100%', // Applies a specific width
+        // enlarge: true, // Increase text size compared to rest of cells


TODO: TS complains about these props even though they exist...

I also need to work on the responsive version of this table. For now it works, just isn't optimized.

Resolved TypeScript errors in 58a6f14

src-docs/src/views/theme/_json/_get_json_vars.js

cchaos · 2021-09-29T22:55:07Z

src-docs/src/views/utility_classes/utility_classes_responsive.js

+function renderBreakpoint(size) {
+  return (
+    <EuiFlexGroup


This was just moved from the deleted sass/breakpoints file

kibanamachine · 2021-09-29T23:25:25Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

…_setup_and_breakpoints

kibanamachine · 2021-09-30T20:57:08Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

kibanamachine · 2021-10-01T20:59:59Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

kibanamachine · 2021-10-01T21:54:05Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

thompsongl · 2021-10-05T18:00:52Z

This is a portion that I could use some engineering help with.

I'm looking into making the JSON file build automated

kibanamachine · 2021-10-05T19:29:49Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

kibanamachine · 2021-10-05T20:32:23Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

kibanamachine · 2021-10-11T16:02:48Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

cee-chen · 2021-10-11T17:47:11Z

src-docs/src/components/guide_page/guide_page_header.tsx

+      role="region"
+      aria-label="EUI Docs app bar"


Ooh thanks for fixing this! The axe-devtools complaint about our sticky top bar always bugged me :) @1Copenut, do you have any extra suggestions for this region/label, or does this look good to you?

I like this role="region" addition. It frames that control bar nicely. What do you think about spelling out the name like "EUI Documentation theme and apps" ? Users who benefit the most from aria labels may not think of this in terms of a bar, but more of what it allows them to do or learn about EUI.

src-docs/src/views/theme/_breakpoints.js

src-docs/src/components/with_theme/language_selector.tsx

cee-chen

There's so much really lovely stuff going on in this PR 😍 I love the tab switching UX for JS vs Sass, and the new documentation looks really great (love the copy-able snippet!). Code-wise everything looked fantastic as well, everything was straightforward and easy to read/understand, and I really appreciated the tendency to break up code into smaller separate utilities/helpers etc.

I didn't find any issues other than super small nits, so this LGTM, but def feel free to wait for other reviews/approvals to merge!

src-docs/src/views/theme/_components/_theme_values_table.tsx

thompsongl · 2021-10-12T14:12:02Z

src-docs/src/components/with_theme/theme_context.tsx

+export const theme_languages: THEME_LANGUAGES[] = [
+  {
+    id: 'language--js',
+    label: 'JS',
+    title: 'Language selector: CSS-in-JS',
+  },
+  {
+    id: 'language--sass',
+    label: 'Sass',
+    title: 'Language selector: Sass',
+  },
+];


CSS-in-JS instead of just JS

Same thought, but also unsure if it's better

elizabetdev

I love how the new theming section is coming together. The breakpoints page looks good and the JS/Sass button is a great idea.

Tested in chrome, safari, Edge, and Firefox. I also looked at code. LGTM! 🎉

kibanamachine · 2021-10-13T22:20:14Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5227/

* Added a ThemeSelector for optionally showing/changing content based on JS or Sass theming language * Added some theme helper components like alert banners, values table, and example row * [Manual] Copied the outputs json version of Sass for easier consumption in docs rather that sass-loader * Rearranging sidenav to promote Theme section and adding “Breakpoints” * Fixed some routing and notices

cchaos added 11 commits September 29, 2021 15:37

Added a ThemeSelector for optionally showing/changing content based o…

963e589

…n JS or Sass theming language

Added the more options to the GuideSectionTypes

f3eccfb

Added some theme helper components like alert banners, values table, …

4e66fbc

…and example row

[Manual] Copied the outputs json version of Sass for easier consumpti…

082a756

…on in docs rather that sass-loader

Changed color utilites to output hex instead of .css() or rgb

2db22a4

Rearranging sidenav to promote Theme section and adding “Breakpoints”

fcb1b1c

Fixes

b6e52f6

Revert "Added the more options to the GuideSectionTypes"

11cb672

This reverts commit f3eccfb.

Fixed some routing and notices

c386f09

Revert "Changed color utilites to output hex instead of .css() or `…

db817b5

…rgb`" This reverts commit 2db22a4.

Cleanup

f4dd077

cchaos commented Sep 29, 2021

View reviewed changes

cchaos marked this pull request as ready for review September 29, 2021 22:59

cchaos added the skip-changelog label Sep 29, 2021

cchaos added 2 commits September 30, 2021 16:23

Merge remote-tracking branch 'upstream/master' into theme_languages/1…

57f4d4e

…_setup_and_breakpoints

Remove now unnecessary ts-ignore for EuiTour

884cb28

cchaos added 2 commits October 1, 2021 16:43

Fix heading levels

be6754e

Fixed rendering of breakpoint value column

9273b2b

Detailing some of the JS breakpoint hooks available

b8e3bf0

automate docs sass var compilation

352c9f7

Merge branch 'master' into theme_languages/setup_and_breakpoints

1f10e95

thompsongl mentioned this pull request Oct 5, 2021

[CSS-in-JS] Global style reset with emotion #5122

Merged

5 tasks

cchaos requested a review from cee-chen October 7, 2021 19:35

cchaos requested review from thompsongl and elizabetdev October 7, 2021 19:35

fix mobileOptions types

58a6f14

cee-chen reviewed Oct 11, 2021

View reviewed changes

src-docs/src/views/theme/_breakpoints.js Show resolved Hide resolved

cee-chen reviewed Oct 11, 2021

View reviewed changes

src-docs/src/components/with_theme/language_selector.tsx Show resolved Hide resolved

cee-chen approved these changes Oct 11, 2021

View reviewed changes

src-docs/src/views/theme/_components/_theme_values_table.tsx Outdated Show resolved Hide resolved

thompsongl approved these changes Oct 12, 2021

View reviewed changes

elizabetdev approved these changes Oct 12, 2021

View reviewed changes

cchaos and others added 2 commits October 13, 2021 17:41

Merge branch 'elastic:master' into theme_languages/setup_and_breakpoints

6385c6d

cleanup

e136566

cchaos enabled auto-merge (squash) October 13, 2021 21:53

cchaos merged commit 56b5764 into elastic:master Oct 13, 2021

cchaos deleted the theme_languages/setup_and_breakpoints branch November 2, 2021 22:15

This was referenced Nov 29, 2022

[Meta] Fix developer experience for Apple M1/arm64 developers #6442

Closed

Remove sass-vars-to-js-loader dependency #6444

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs] Add ThemeLanguages and new Breakpoints page #5227

[Docs] Add ThemeLanguages and new Breakpoints page #5227

cchaos commented Sep 29, 2021 •

edited by thompsongl

Loading

cchaos left a comment •

edited

Loading

cchaos Sep 29, 2021

cee-chen Oct 11, 2021 •

edited

Loading

thompsongl Oct 12, 2021

cchaos Sep 29, 2021

cchaos Sep 29, 2021

thompsongl Oct 11, 2021

cchaos Sep 29, 2021 •

edited

Loading

kibanamachine commented Sep 29, 2021

kibanamachine commented Sep 30, 2021

kibanamachine commented Oct 1, 2021

kibanamachine commented Oct 1, 2021

thompsongl commented Oct 5, 2021

kibanamachine commented Oct 5, 2021

kibanamachine commented Oct 5, 2021

kibanamachine commented Oct 11, 2021

cee-chen Oct 11, 2021

1Copenut Oct 11, 2021

cee-chen left a comment

thompsongl Oct 12, 2021

elizabetdev left a comment

kibanamachine commented Oct 13, 2021

		// width: '100%', // Applies a specific width
		// enlarge: true, // Increase text size compared to rest of cells

[Docs] Add ThemeLanguages and new Breakpoints page #5227

[Docs] Add ThemeLanguages and new Breakpoints page #5227

Conversation

cchaos commented Sep 29, 2021 • edited by thompsongl Loading

1. Added a ThemeSelector for optionally showing/changing content based on JS or Sass theming language

Notes

2. Added some theme helper components like alert banners, values table, and example row

3 [Manual] Copied the output json version of Sass for easier consumption in docs rather than sass-loader

4. Rearranged sidenav to promote Theme section and adding “Breakpoints”

5. Global values will slowly become the "Customizer"

Checklist

cchaos left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cee-chen Oct 11, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cchaos Sep 29, 2021 • edited Loading

Choose a reason for hiding this comment

kibanamachine commented Sep 29, 2021

kibanamachine commented Sep 30, 2021

kibanamachine commented Oct 1, 2021

kibanamachine commented Oct 1, 2021

thompsongl commented Oct 5, 2021

kibanamachine commented Oct 5, 2021

kibanamachine commented Oct 5, 2021

kibanamachine commented Oct 11, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cee-chen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elizabetdev left a comment

Choose a reason for hiding this comment

kibanamachine commented Oct 13, 2021

cchaos commented Sep 29, 2021 •

edited by thompsongl

Loading

cchaos left a comment •

edited

Loading

cee-chen Oct 11, 2021 •

edited

Loading

cchaos Sep 29, 2021 •

edited

Loading