feat: setup patterns docs (#7871)

packages/docusaurus-theme/src/components/figma_embed/index.tsx

@@ -0,0 +1,57 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { IframeHTMLAttributes, useMemo } from 'react';
+import { useEuiMemoizedStyles, UseEuiTheme } from '@elastic/eui';
+import { css } from '@emotion/react';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+export interface FigmaEmbedProps
+  extends IframeHTMLAttributes<HTMLIFrameElement> {
+  url: string;
+}
+
+const getFigmaEmbedStyles = (euiTheme: UseEuiTheme) => ({
+  wrapper: css`
+    border: 1px solid ${euiTheme.euiTheme.colors.lightShade};
+    border-radius: ${euiTheme.euiTheme.size.s};
+    margin: ${euiTheme.euiTheme.size.xl} 0;
+  `,
+  iframe: css`
+    border-radius: ${euiTheme.euiTheme.size.s};
+    display: block;
+  `,
+});
+
+export const FigmaEmbed = ({ url, ...rest }: FigmaEmbedProps) => {
+  const baseUrl = useBaseUrl('/', { absolute: true });
+  const styles = useEuiMemoizedStyles(getFigmaEmbedStyles);
+
+  const src = useMemo(() => {
+    const params = new URLSearchParams({
+      embed_host: 'eui.elastic.co',
+      embed_origin: baseUrl,
+      url,
+    });
+
+    return `https://www.figma.com/embed?${params.toString()}`;
+  }, [url, baseUrl]);
+
+  return (
+    <div css={styles.wrapper}>
+      <iframe
+        {...rest}
+        css={styles.iframe}
+        height="450"
+        width="100%"
+        src={src}
+        allowFullScreen
+      />
+    </div>
+  );
+};

packages/docusaurus-theme/src/components/icon/index.ts

@@ -0,0 +1,11 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { EuiIcon } from '@elastic/eui';
+
+export const Icon = EuiIcon;

packages/docusaurus-theme/src/theme/MDXComponents/index.ts

@@ -8,10 +8,14 @@
 
 import OriginalMDXComponents from '@theme-init/MDXComponents';
 import { Badge } from '../../components/badge';
+import { Icon } from '../../components/icon';
+import { FigmaEmbed } from '../../components/figma_embed';
 
 const MDXComponents = {
   ...OriginalMDXComponents,
   Badge,
+  FigmaEmbed,
+  Icon,
 };
 
 export default MDXComponents;

packages/website/docs/patterns/error_messages/_category_.yml

@@ -0,0 +1,4 @@
+label: Error messages
+link:
+  type: doc
+  id: patterns_error_messages_overview

packages/website/docs/patterns/error_messages/error_banners.mdx

@@ -0,0 +1,6 @@
+---
+id: patterns_error_messages_banners
+slug: /patterns/error-messages/error-banners
+---
+
+# Error banner

packages/website/docs/patterns/error_messages/error_pages.mdx

@@ -0,0 +1,6 @@
+---
+id: patterns_error_messages_error_pages
+slug: /patterns/error-messages/error-pages
+---
+
+# Error page

packages/website/docs/patterns/error_messages/examples.mdx

@@ -0,0 +1,109 @@
+---
+id: patterns_error_messages_examples
+slug: /patterns/error-messages/examples
+---
+
+# Error examples
+
+## 400: Bad request
+The server can’t process the information because it’s not complete or is in the wrong format.
+
+Use the [error page pattern](./error_pages.mdx) for `400` errors.
+
+Good example:
+> **You must fix the following**
+> Your email must contain an @ character
+> The date you registered must be in the past
+
+## 401: Unauthorized
+Do not use error pages for authentication errors (`401` error codes). Instead, if the user is logged out automatically, actively redirect them to the login page when it happens and explain why they were logged out using the [error banner pattern](./error_banners.mdx).
+
+## 403: Forbidden
+The user doesn’t have permissions to do what they’re trying to do.
+
+Use the [error page pattern](./error_pages.mdx) for `403` errors.
+
+Good example:
+> **You can’t access this page**
+> You don’t have permission. If you think this is a mistake, contact your administrator: [[email protected]](#).
+
+## 404: Not found
+The page is missing. This is when the user typed a bad URL or clicked on a broken link. It’s different from `410 Gone` where we know that the page has been deleted.
+
+Use the [error page pattern](./error_pages.mdx) for `404` errors.
+
+Good example:
+> **We can’t find the page you’re looking for**
+> If you typed in the URL, check it’s correct. If you clicked a link, contact your administrator and tell them it’s broken: [[email protected]](#).
+
+## 408: Request timeout
+The server did not respond after an acceptable amount of time.
+
+Use the [error page pattern](./error_pages.mdx) for `408` errors.
+
+Good example:
+> **The page took too long to load**
+> This is probably temporary. Wait 1 minute and try again. If this keeps happening, contact your administrator: [email protected].
+
+## 410: Gone
+Similar to `404`, but instead of being missing we know it’s been deleted.
+
+Use the [error page pattern](./error_pages.mdx) for `404` errors.
+
+Good example:
+> **This page has been permanently deleted**
+> You can go back, or go home.
+
+## 429: Too many requests
+The user has tried too many actions in a short space of time.
+
+Use the [error page pattern](./error_pages.mdx) for `429` errors.
+
+Good example:
+> **We’ve temporary limited what you can do**
+> We have a limit of 30 actions per minute, per user. Wait 1 minute and then try again. If this keeps happening contact your administrator: [[email protected]](#).
+
+## 500: Internal server error
+A generic status code, usually used when the application crashes for some unknown reason. It is acceptable to apologize when handling a `500` error.
+
+Use the [error page pattern](./error_pages.mdx) for `500` errors.
+
+Good example:
+> **Sorry, there’s a problem with the application**
+> We aren’t sure what went wrong. If this keeps happening, contact your administrator: [email protected] with the error code: 0x000345.
+
+## 502: Bad gateway
+The server reached out to another system and got a response, but could not complete the action for some reason..
+
+Use the [error banner pattern](./error_banners.mdx) for `502` errors.
+
+Good example:
+> **We could not save your data to AWS**
+> We don’t know what went wrong. You can try again. If this keeps happening, contact your administrator: [[email protected]](#).
+
+## 503: Service unavailable
+The server can’t do what you asked it to do. It may be overloaded or offline for maintenance. It is acceptable to apologize when handling a `503` error.
+
+Use the [error page pattern](./error_pages.mdx) for `503` errors.
+
+Good example:
+> **Sorry, there’s a problem with the application**
+> It might just be busy. Wait for 1 minute and try again. If this keeps happening, contact your administrator: [[email protected]](#).
+
+## 504: Gateway timeout
+The server reached out to another system, but the other system took too long to respond.
+
+Use the [error banner pattern](./error_banners.mdx) for `504` errors.
+
+Good example:
+> **We could not save your data to AWS**
+> AWS took too long to respond. It might just be busy. Wait 1 minute and try again. If this keeps happening, contact your administrator: [[email protected]](#).
+
+## 507: Insufficient storage
+The storage space on the server has run out.
+
+Use the [error banner pattern](./error_banners.mdx) for `507` errors.
+
+Good example:
+> **We could not save your dashboard**
+> Your storage is full. You can delete some data and try again, or you can contact your administrator to upgrade your storage: [[email protected]](#).

packages/website/docs/patterns/error_messages/help_users_avoid_errors.mdx

@@ -0,0 +1,6 @@
+---
+id: patterns_error_messages_avoid
+slug: /patterns/error-messages/help-users-avoid-errors
+---
+
+# Help users avoid errors

packages/website/docs/patterns/error_messages/overview.mdx

@@ -0,0 +1,63 @@
+---
+id: patterns_error_messages_overview
+slug: /patterns/error-messages
+---
+
+# Error messages
+
+## What is an error?
+An error happens when the system couldn’t do something it was trying to do.
+
+There are lots of reasons why errors happen, but they’re not always obvious to the user. It could be because instructions were not clear, data is missing, or there are bugs in the application.
+
+We should do everything we can to [help users to avoid errors](./help_users_avoid_errors.mdx). When an error occurs, we **must** tell the user. You should tell them exactly what went wrong, and any actions they can take to fix it.
+
+Missing or badly written error messages can be frustrating, time consuming and difficult to recover from. They can also make the user believe the task is more complex than it is, and can give the impression that our product is low quality.
+
+We have written guidance on <a id="patternsErrorsWriting">how to write good error messages</a>.
+
+### Primary errors
+Primary errors are as bad as it gets. They block the user from completing the current task, and we can’t even show them the page they expected. For example, when a user does not have permission to view a page, error code 403. A primary error should redirect the user to an error page.
+
+Read more about the <a id="patternsErrorPage">error page pattern</a>.
+
+### Secondary errors
+Secondary errors happen when there is an error which blocks the current task, but we can still show them the page they expected. For example, an API or cluster that is not responding, error code `504`. A secondary error should reload the page without the user losing any information, and display an error banner.
+
+Read more about the <a id="patternsErrorBanner">error banner pattern</a>.
+
+### Validation errors
+Validation errors happen when the user enters information in a different format than expected, blocking the current task, error code `400`. Validation errors should reload the page without the user losing any information, display an error summary, and highlight any fields which caused errors.
+
+Read more about the <a id="patternsErrorValidation">validation errors pattern</a>.
+
+### Unrelated errors (Warnings)
+Unrelated errors are warnings. They don’t impact the user right now, but they’re useful to know. For example, there may be an error in another part of the application, but it’s not blocking the current task.
+
+Read more about the <a id="patternsErrorWarning">error warning pattern</a>.
+
+## Error codes
+When an error happens, there is usually an error code provided by the client (browser) or the server, which can help us to explain to the user what went wrong.
+
+It can be tempting to just tell the user, ‘hey, error 504’. But, most users won’t know what that means. Rather than just quoting the error code, we should translate what it means to the user in plain language.
+
+See examples for common error codes:
+- [400: Bad request](./examples#400-bad-request)
+- [401: Unauthorized](./examples#401-unauthorized)
+- [403: Forbidden](./examples#403-forbidden)
+- [404: Not found](./examples#404-not-found)
+- [408: Request timeout](./examples#408-request-timeout)
+- [410: Gone](./examples#410-gone)
+- [429: Too many requests](./examples#429-too-many-requests)
+- [500: Internal server error](./examples#500-internal-server-error)
+- [502: Bad gateway](./examples#502-bad-gateway)
+- [503: Service unavailable](./examples#503-service-unavailable)
+- [504: Gateway timeout](./examples#504-gateway-timeout)
+- [507: Insufficient storage](./examples#507-insufficient-storage)
+
+
+You can read in-depth about all the different [client errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) and [server errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) on [MDN Web Docs](https://developer.mozilla.org/en-US/).
+
+## Related patterns and documentation
+- <a id="patternsConfirmationPrompts">Confirmation prompts</a>
+- <a id="patternsHelpContent" section="fields-and-settings">Content patterns</a>