Improve theming

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>

docs-ui/src/app/(docs)/layout.module.css

@@ -1,5 +0,0 @@
-.pageContainer {
-  width: 100%;
-  max-width: 960px;
-  margin: 0 auto;
-}

docs-ui/src/app/(docs)/layout.tsx

@@ -1,16 +0,0 @@
-import type { Metadata } from 'next';
-
-import styles from './layout.module.css';
-
-export const metadata: Metadata = {
-  title: 'Backstage UI',
-  description: 'UI library for Backstage',
-};
-
-export default function DocsLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return <div className={styles.pageContainer}>{children}</div>;
-}

docs-ui/src/app/layout.module.css

@@ -13,6 +13,12 @@
   border-radius: 0.5rem;
 }
 
+.content {
+  width: 100%;
+  max-width: 960px;
+  margin: 0 auto;
+}
+
 @media (min-width: 768px) {
   .container {
     width: calc(100% - 332px - 40px);

docs-ui/src/app/layout.tsx

@@ -51,7 +51,9 @@ export default async function RootLayout({
         <Providers>
           <Sidebar version={packageVersion} />
           <Toolbar />
-          <div className={styles.container}>{children}</div>
+          <div className={styles.container}>
+            <div className={styles.content}>{children}</div>
+          </div>
           <CustomTheme />
         </Providers>
       </body>

docs-ui/src/components/Theming/index.tsx

@@ -2,6 +2,7 @@ import { MDXRemote } from 'next-mdx-remote-client/rsc';
 import { formattedMDXComponents } from '@/mdx-components';
 import { Component } from '@/utils/changelog';
 import { componentDefinitions } from '../../../../packages/ui/src/utils/componentDefinitions';
+import type { DataAttributeValues } from '../../../../packages/ui/src/types';
 
 export function Theming({ component }: { component: Component }) {
   const componentDefinition = componentDefinitions[component];
@@ -11,15 +12,40 @@ export function Theming({ component }: { component: Component }) {
   }
 
   const classNames = componentDefinition.classNames;
+  const dataAttributes = componentDefinition.dataAttributes;
 
-  // Convert classNames object values to array
-  const classNameArray = Object.values(classNames);
+  // Get the first class name
+  const firstClassName = Object.values(classNames)[0];
+
+  // Create array of selectors combining first class name with data attributes
+  const selectorArray: string[] = [];
+
+  if (dataAttributes) {
+    Object.entries(dataAttributes).forEach(
+      ([attributeName, attributeValues]) => {
+        (attributeValues as DataAttributeValues).forEach(value => {
+          selectorArray.push(
+            `${firstClassName}[data-${attributeName}="${value}"]`,
+          );
+        });
+      },
+    );
+  }
+
+  const classNamesArray = [
+    `${firstClassName}`,
+    ...selectorArray,
+    ...Object.values(classNames).slice(1),
+  ];
 
   return (
     <MDXRemote
       components={formattedMDXComponents}
       source={`## Theming
-      ${classNameArray.map(className => `- \`${className}\``).join('\n')}
+
+        Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.
+
+        ${classNamesArray.map(selector => `- \`${selector}\``).join('\n')}
       `}
     />
   );