[Docs] Unify shadow documentation (#9117)

Author: mgadewoll

packages/website/docs/getting-started/theming/tokens/shadows/index.mdx

@@ -6,7 +6,14 @@ sidebar_position: 10
 
 EUI provides 5 shadow sizes (`xs`, `s`, `m`, `l`, `xl`) that can be applied in two directions: `down` (default) and `up`.
 
-The provided EUI shadow utilities handle the following additional style adjustments:
+The provided EUI shadow utilities use the underlying theme shadow tokens and automatically add required adjustments 
+for dark mode and high contrast mode that ensure expected visibility.
+
+:::warning Never use the underlying shadow tokens separately
+Always use the shadow utilities to ensure proper styling.
+:::
+
+These shadow utilities handle the following additional style adjustments:
 
 - adds a light, 4-sided `border` style in Dark mode to increase elevated item visibility
 - replaces the `box-shadow` in High Contrast mode with `border` to ensure visibility in high contrast themes
@@ -23,7 +30,7 @@ import { EuiSpacer } from '@elastic/eui';
 
   const styles = css`
     ${euiShadow(euiThemeContext, 's')};
-    ${euiShadow(euiThemeContext, 's', { direction: 'up' })};
+    ${euiShadow(euiThemeContext, 's', { direction: 'down' })};
   `;  
   ```
 </Example.Snippet>

packages/website/docs/getting-started/theming/tokens/shadows/shadows_table.tsx

@@ -5,9 +5,12 @@ import {
   _EuiThemeShadowSize,
   euiShadow,
   euiShadowFlat,
+  EuiCodeBlock,
 } from '@elastic/eui';
 import { type EuiShadowOptions } from '@elastic/eui-theme-common';
+
 import { ThemeValuesTable } from '../../theme_values_table';
+import { ReactNode } from 'react';
 
 const shadowTypes: _EuiThemeShadowSize[] = ['xs', 's', 'm', 'l', 'xl'];
 
@@ -22,28 +25,37 @@ export const ShadowsTable = ({
   const items = shadowTypes.map((type) => ({
     id: type,
     token: `euiShadow(euiThemeContext, '${type}', { direction: '${direction}' })`,
-    value: euiShadow(euiThemeContext, type, {
-      direction,
-    })
-      .replaceAll(';;', ';')
-      .replaceAll(' ;', ''),
+    value: getFormattedCSS(
+      euiShadow(euiThemeContext, type, {
+        direction,
+      })
+    ),
   }));
 
   // deprecated, remove once obsolete
   items.push({
     id: 'flat',
     token: `euiShadowFlat(euiThemeContext, { direction: '${direction}' }))`,
-    value: euiShadowFlat(euiThemeContext, {
-      direction,
-    })
-      .replaceAll(';;', ';')
-      .replaceAll(' ;', ''),
+    value: getFormattedCSS(
+      euiShadowFlat(euiThemeContext, {
+        direction,
+      })
+    ),
   });
 
   return (
     <ThemeValuesTable
       items={items}
       tokenColumnProps={{ name: 'Utility' }}
+      valueColumnProps={{
+        name: 'Style output',
+        align: 'left',
+        render: (value: ReactNode) => (
+          <small>
+            <EuiCodeBlock language="css">{value}</EuiCodeBlock>
+          </small>
+        ),
+      }}
       render={(item) => (
         <EuiColorPickerSwatch
           showToolTip={false}
@@ -61,3 +73,34 @@ export const ShadowsTable = ({
     />
   );
 };
+
+/* CSS formatting utility */
+const getFormattedCSS = (cssString: string) => {
+  return (
+    cssString
+      // Remove comments
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      // Clean up semicolons
+      .replaceAll(';;', ';')
+      .replaceAll(' ;', '')
+      // Normalize all whitespace to single spaces
+      .replace(/\s+/g, ' ')
+      // Add line breaks after semicolons (for top-level properties)
+      .replace(/;\s*(?![^{]*})/g, ';\n')
+      // Add line breaks before selectors like &::after
+      .replace(/\s*(&[^{]*)\s*{/g, '\n\n$1 {')
+      // Format inside braces: add line breaks and indent
+      .replace(/{([^}]*)}/g, (match, content) => {
+        const formatted = content
+          .split(';')
+          .map((prop: string) => prop.trim())
+          .filter((prop: string) => prop.length > 0)
+          .map((prop: string) => `  ${prop};`)
+          .join('\n');
+        return `{\n${formatted}\n}`;
+      })
+      // Clean up any leading newlines
+      .replace(/^\n+/, '')
+      .trim()
+  );
+};