[EUI+] New IA #8547

ryankeairns · 2025-04-03T22:51:53Z

Closes https://github.com/elastic/eui-private/issues/243

Summary

Overhaul of the IA. Notable changes include:

Separated out Getting Started; pulled in Theming and Utilities
As a result, Components are components
- Changed groups and order
- All collapsed by default
Flattened overall. Less clicking; richer right-side nav
- Consolidated guidelines and patterns into component pages
- Common page IA: Component, Usage, Guidelines, Props
- Consolidated some patterns into Usage
Moved Writing into Content
A few design tweaks
- Increased font size of sidebar links
- Updated button style for Show source

QA

Remove or strikethrough items that do not apply to your PR.

General checklist

Browser QA
- Checked in both light and dark modes
- Checked in both MacOS and Windows high contrast modes
  - (emulate forced colors if you do not have access to a Windows machine.)
- Checked in mobile
- Checked in Chrome, Safari, Edge, and Firefox
- Checked for accessibility including keyboard-only and screenreader modes
Docs site QA
- Added documentation
- Props have proper autodocs (using @default if default values are missing) and playground toggles
- Checked Code Sandbox works for any docs examples
Code quality checklist
- Added or updated jest and cypress tests
- Updated visual regression tests
Release checklist
- A changelog entry exists and is marked appropriately.
- If applicable, added the breaking change issue label (and filled out the breaking change checklist)
Designer checklist
- If applicable, file an issue to update EUI's Figma library with any corresponding UI changes. (This is an internal repo, if you are external to Elastic, ask a maintainer to submit this request)

ryankeairns · 2025-04-04T21:46:35Z

Organized a few more pages and tweaked some styles.
In particular, took a pass at the props table which felt like it was floating in space and used relatively large font sizing. It is now set to compressed and is wrapped in a panel ... plus a few other small tweaks.

I'll stop here while reviews are under way.

weronikaolejniczak · 2025-04-07T12:17:39Z

@ryankeairns We should probably link this PR with: https://github.com/elastic/eui-private/issues/243 (and update its description, move to M1).

weronikaolejniczak

Amazing job, @ryankeairns! I would say, let's just fix the conflicts and merge as is. All the comments I added are for us to fix in the future, not necessarily now. It's much better to merge imperfect than keep the PR open any longer.

Testing notes

Homepage links

There are broken links on the homepage now:

Highlights > All components button
Footer > Developers > Getting started
Footer > Developers > Tokens
Footer > Designers > Patterns

They don't use Docusaurus' Link component and therefore it's hard to keep track of them breaking. We should probably update them to use it or useBrokenLinks hook.

Utilities

I'd say the Utilities are much better suited in the "Components" section. They don't belong in "Getting Started" that should only scratch the surface. Currently, the developers are used to going to Components and seeing Utilities there. Additionally, although sometimes functions, the majority of the utilities are React components and hooks. I agree we could use some separation between UI components and utility components but we can do it on the same page. What do you think?

Sidebar font-size

There's some font-size inconsistency in the sidebar. I think they should be of equal font-size (probably 14px). The bold text brings enough distinction between the pages vs folders.

Prop table

Maybe we could remove the last line in the prop table:

I think it'd look a bit cleaner.

Relative URL links

I used \[([^\]]+)\]\((?!https:\/\/)(?![^\)]*\.mdx)[^\)]*\) regexp to find all Markdown links that are not https links and do not contain the .mdx file extension. These are:

packages/website/docs/components/overview.mdx links
packages/website/docs/components/display/beacon.mdx:13
packages/website/docs/getting_started/utilities/text_diff.mdx:70
packages/website/docs/getting_started/utilities/text_diff.mdx:298
packages/website/docs/data_visualization/types/metric_chart.mdx:20
packages/website/docs/components/forms/text/inline_edit.mdx icon button links

I fixed these but I think we either lost the changes or have to rebase onto main:

packages/website/docs/patterns/error_messages/overview.mdx links
packages/website/docs/patterns/error_messages/error_warning.mdx:27
packages/website/docs/patterns/error_messages/error_validation.mdx:36
packages/website/docs/patterns/error_messages/error_pages.mdx:44
packages/website/docs/patterns/error_messages/error_help_users_avoid_errors.mdx:139
packages/website/docs/patterns/save_buttons.mdx:28
packages/website/docs/patterns/error_messages/error_banners.mdx:25

If we don't use relative file paths, we cannot leverage the preloading, prefetching and broken link detection Docusaurus capabilities.

weronikaolejniczak · 2025-04-08T08:47:20Z

packages/docusaurus-theme/src/components/prop_table/prop_table.tsx

@@ -182,19 +198,23 @@ export const PropTable = ({
    >
      <header css={styles.header}>
        {showTitle && (
-          <EuiTitle size="m">


sidenote:

The original value m is correct, it's just displayed incorrectly. I fixed this on #8557 using Docusaurus Heading component which also adds an anchor and the copy anchor link icon.

weronikaolejniczak · 2025-04-08T08:53:55Z

packages/website/docs/components/containers/modal/_patterns.mdx

-<PropTable definition={docgen.EuiModalFooter} />
+### Confirming an action
+
+Use a [Modal](#confirming-an-action) when you need to interrupt a user and ask them to confirm an action.


non-blocking:

We're redirecting to itself here. Is that on purpose?

weronikaolejniczak · 2025-04-08T09:15:51Z

packages/website/docs/components/display/badge/index.mdx

@@ -1,12 +1,42 @@
 ---
 slug: /display/badge
 id: display_badge
+sidebar_position: 1


non-blocking:

Are we putting Badge first on purpose? Other components follow alphabetical order.

weronikaolejniczak · 2025-04-08T09:19:26Z

packages/website/docs/components/navigation/button/overview.mdx

non-blocking:

Not super crucial but the filename overview.mdx doesn't fit here because it's a subpage of the Buttons category. I'd say we can just name it button.mdx.

weronikaolejniczak · 2025-04-08T10:14:38Z

packages/website/docs/getting_started/testing/recommendations.mdx

non-blocking:

The "Recommendations" page is the only subpage, so maybe we can merge it with introduction.mdx content and move to a single testing.mdx page?

weronikaolejniczak · 2025-04-08T10:17:11Z

packages/website/docs/components/display/callout.mdx

+
+**Keep these guidelines in mind:**
+
+*   Minimize the number of callouts per page.


non-blocking:

We should either consistently used * Text or - Text. I used and updated the content with the latter.

weronikaolejniczak · 2025-04-08T10:20:02Z

packages/website/docs/components/navigation/pagination/_guidelines.mdx

@@ -184,7 +177,7 @@ If the total results are unknown, you can make a best guess based on the context

 * * *


non-blocking:

We don't use dividers on any other pages, so we should remove it.

weronikaolejniczak · 2025-04-08T10:33:11Z

packages/website/docs/components/display/beacon.mdx

+## Component
+
+:::tip
+It is strongly encouraged to use **EuiBeacon** in conjunction with [**EuiTour**](./tour). Standalone, the beacon is a visual cue that may lack context.


non-blocking:

Sometimes, we seem to bold the component links. Do we want to do that? If so, we should think about whether we want to do it globally or locally like here. We can easily find all those links searching for [** and should be easy to search and replace as well.

kibanamachine · 2025-04-08T16:53:31Z

Preview staging links for this PR:

Docs site: https://eui.elastic.co/pr_8547/
Storybook: https://eui.elastic.co/pr_8547/storybook
New docs: https://eui.elastic.co/pr_8547/new-docs

elasticmachine · 2025-04-08T16:55:45Z

💚 Build Succeeded

Buildkite Build
Commit: db756d1

History

💔 Build #3818 failed aa3e4d5
💚 Build #3796 succeeded 3da2298
💚 Build #3794 succeeded 8849a20
💚 Build #3793 succeeded f4330f3
💚 Build #3792 succeeded 5303dc4

ryankeairns added documentation Issues or PRs that only affect documentation - will not need changelog entries skip-changelog Use on PRs to skip changelog requirement (Don't delete - used for automation) labels Apr 3, 2025

ryankeairns force-pushed the rk/cant-believe-ia-the-whole-thing branch from 0ad1148 to 11b76a0 Compare April 3, 2025 23:13

ryankeairns marked this pull request as ready for review April 4, 2025 13:35

ryankeairns requested a review from a team as a code owner April 4, 2025 13:35

acstll mentioned this pull request Apr 7, 2025

docs: improve i18n section #8554

Merged

1 task

weronikaolejniczak self-requested a review April 7, 2025 11:57

weronikaolejniczak approved these changes Apr 8, 2025

View reviewed changes

ryankeairns added 8 commits April 8, 2025 07:22

resolve conflicts

71bbfc4

More links were broken, but I am not

82843bf

Update components overview

25f2cfc

Updates to empty prompt page

92ce8aa

Fix links on buttons page

c075200

Fix homepage links

070650e

Organize icon page

09692ca

Update prop table styles

aa3e4d5

ryankeairns force-pushed the rk/cant-believe-ia-the-whole-thing branch from 3da2298 to aa3e4d5 Compare April 8, 2025 14:25

fix conflict resolution

db756d1

ryankeairns merged commit a39d7dc into main Apr 8, 2025
5 checks passed

ryankeairns deleted the rk/cant-believe-ia-the-whole-thing branch April 8, 2025 17:01

This was referenced Apr 9, 2025

[EUI+] Investigate Markdown link replacement #8510

Open

docs: technical guidelines for contributing #8562

Merged

This was referenced Apr 10, 2025

fix(website): sidebar font sizes #8581

Merged

[New docs] Restructure docs folder #8583

Closed

chore(website): restructure docs folder (1 of 2) #8588

Merged

chore(website): restructure docs folder (2 of 2) #8594

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[EUI+] New IA #8547

[EUI+] New IA #8547

ryankeairns commented Apr 3, 2025 •

edited

Loading

ryankeairns commented Apr 4, 2025 •

edited

Loading

weronikaolejniczak commented Apr 7, 2025

weronikaolejniczak left a comment

weronikaolejniczak Apr 8, 2025

weronikaolejniczak Apr 8, 2025

weronikaolejniczak Apr 8, 2025

weronikaolejniczak Apr 8, 2025

weronikaolejniczak Apr 8, 2025

weronikaolejniczak Apr 8, 2025

weronikaolejniczak Apr 8, 2025

weronikaolejniczak Apr 8, 2025

kibanamachine commented Apr 8, 2025

elasticmachine commented Apr 8, 2025


		Keep these guidelines in mind:

		* Minimize the number of callouts per page.

		@@ -184,7 +177,7 @@ If the total results are unknown, you can make a best guess based on the context

		* * *

[EUI+] New IA #8547

[EUI+] New IA #8547

Conversation

ryankeairns commented Apr 3, 2025 • edited Loading

Summary

QA

General checklist

ryankeairns commented Apr 4, 2025 • edited Loading

weronikaolejniczak commented Apr 7, 2025

weronikaolejniczak left a comment

Choose a reason for hiding this comment

Testing notes

Homepage links

Utilities

Sidebar font-size

Prop table

Relative URL links

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibanamachine commented Apr 8, 2025

elasticmachine commented Apr 8, 2025

💚 Build Succeeded

History

ryankeairns commented Apr 3, 2025 •

edited

Loading

ryankeairns commented Apr 4, 2025 •

edited

Loading