[docs-infra] Fix a11y and HTML errors on baseline docs page #2718

oliviertassinari · 2025-09-10T17:57:54Z

A quick, fun one.

There are 359 HTML errors on https://base-ui.com/react/components/slider, if we can trust https://validator.w3.org/nu/?doc=https%3A%2F%2Fbase-ui.com%2Freact%2Fcomponents%2Fslider.

I see this as a regression in Base UI vs. MUI Base https://v6.mui.com/base-ui/react-slider/ that only has errors from the components (or almost).
I can't find one clear PR that broke this in Base UI, it seems to have been ignored from the start, so only a pattern of not considering those errors in the Definition of Done. Which I think we can turn into: mui/mui-public#682.

There are Axe regressions introduced from [docs] New props table #2135.

Which I think we can turn into: mui/mui-public#683.

After this PR change, we only have the bugs that our components have. For example, on the Slider docs page:

https://validator.w3.org/nu/?doc=https%3A%2F%2Fdeploy-preview-2718--base-ui.netlify.app%2Freact%2Fcomponents%2Fslider

Someone could now easily spot the issues and fix them:

The aria-valuemin is redundant, to delete.
The aria-valuemax is redundant, to delete.
The name default value is wrong, the docs say it's empty but it's "". This is not the same: an input without a name doesn't get sent, one with an empty string gets sent with an empty string as key.

cc @mj12albert

Preview: https://deploy-preview-2718--base-ui.netlify.app/react/components/slider

pkg-pr-new · 2025-09-10T17:59:08Z

Open in StackBlitz

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui-components/react@2718

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui-components/utils@2718

commit: 2040900

netlify · 2025-09-10T18:00:13Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`2040900`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/68c1ecee8a1de10008c8ee8a
😎 Deploy Preview	https://deploy-preview-2718--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

mui-bot · 2025-09-10T18:00:22Z

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui-components/react	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

oliviertassinari

Extra context added. Normally, those changes lead to no visual diff (that are not bug fixes).

oliviertassinari · 2025-09-10T17:59:07Z

docs/src/components/Code.tsx

-export function Code({ className, ...props }: React.ComponentProps<'code'>) {
-  return <code className={clsx('Code', className)} {...props} />;
+export function Code(props: React.ComponentProps<'code'>) {
+  return <code {...props} className={clsx('Code', props.className)} />;


Avoid JS object destructuring; it's faster. This components is rendered a bunch on the page.

oliviertassinari · 2025-09-10T17:59:30Z

docs/src/components/CodeBlock.tsx

 }

-export function Panel({ className, children, ...props }: React.ComponentPropsWithoutRef<'div'>) {
+export function Panel({ className, children, ...other }: React.ComponentPropsWithoutRef<'div'>) {


Usual naming convention in the codebase (move closer to have a single convetion in use, to help others navigate it).

In the repo (package and docs) ...props is still by far the most common though

oliviertassinari · 2025-09-10T18:00:34Z

docs/src/components/CodeBlock.tsx

-          event.key === 'a' &&
-          (event.metaKey || event.ctrlKey) &&
+          (event.ctrlKey || event.metaKey) &&
+          String.fromCharCode(event.keyCode) === 'A' &&


The logic was wrong; it ignored, e.g. Dvorak keyboard. This is a straight copy & paste from Material UI, not related to the PR, but I saw it, so why not? For those who wonder, at the root, it's an issue with the web standard.

docs/src/components/ReferenceTable/AttributesReferenceTable.tsx

docs/src/components/ReferenceTable/PropsReferenceAccordion.tsx

oliviertassinari · 2025-09-10T18:03:41Z

docs/src/components/ReferenceTable/PropsReferenceAccordion.tsx

-    <Accordion.Scrollable gradientColor="var(--color-gray-50)">
-      <pre {...props} className="text-xs p-0 m-0" style={{ backgroundColor: 'none' }} />
+    <Accordion.Scrollable component="div" gradientColor="var(--color-gray-50)">
+      <pre {...props} className="text-xs p-0 m-0" style={{ backgroundColor: undefined }} />


background-color: none doesn't exist: https://stackoverflow.com/questions/8739665/is-background-colornone-valid-css. Instead, remove the inline style applied.

docs/src/components/ReferenceTable/PropsReferenceAccordion.tsx

oliviertassinari · 2025-09-10T18:05:25Z

docs/src/components/ReferenceTable/PropsReferenceAccordion.tsx

                      </DescriptionList.Details>
                    </DescriptionList.Item>
                  )}
-


Avoid blank lines in JSX; those always feel arbitrarily placed with no meaning (component separation usually works a lot better to convey context).

oliviertassinari · 2025-09-10T18:06:03Z

docs/src/mdx-components.tsx

-  p: (props) => <p {...props} />,
+  p: (props) => props.children,


We don't need an extra <p> when we inline code, so flatten it.

mj12albert · 2025-09-11T06:54:24Z

docs/src/components/Accordion.tsx

+  const {
+    children,
+    className,
+    component: Component = 'span',


I don't think this component prop is necessary; is it because div is shorter than span? If so this could just always be a div

<Accordion.Scrollable> is used as a child of a <summary> which only allows phrasing content, so it can't be a div, a span works.

But <Accordion.Scrollable> is also used as a parent of a <pre> element, which only allows its parent to be a flow content, so it can't be a span; a div works.

So it needs to be parameterized.

How about tag instead of component? We already use this convention a bit in the package, e.g.

base-ui/packages/react/src/menu/trigger/MenuTrigger.tsx

Line 173 in c2384f9

tag="button"

mj12albert · 2025-09-11T07:05:28Z

docs/src/components/ReferenceTable/PropsReferenceAccordion.tsx

            rehypePlugins: rehypeSyntaxHighlighting,
            useMDXComponents: () => ({
-              code: ExpandedCode,
+              ...inlineMdxComponents,


Why does this need to be spread here now?

I expect that all use of createMdxComponent() must extend the default typography set, so:

diff --git a/docs/src/mdx/createMdxComponent.ts b/docs/src/mdx/createMdxComponent.ts index 6314f9b9..98c99684 100644 --- a/docs/src/mdx/createMdxComponent.ts +++ b/docs/src/mdx/createMdxComponent.ts @@ -1,5 +1,6 @@ import * as jsxRuntime from 'react/jsx-runtime'; import { evaluate, EvaluateOptions } from '@mdx-js/mdx'; +import { mdxComponents } from '../mdx-components'; export async function createMdxComponent( markdown = '', @@ -8,6 +9,7 @@ export async function createMdxComponent( ) { const { default: Component } = await evaluate(markdown, { ...jsxRuntime, + ...mdxComponents, ...options, } as EvaluateOptions); return Component;

It's only about a step to make this migration easier.

oliviertassinari requested a review from dav-is September 10, 2025 17:57

oliviertassinari requested review from atomiks and colmtuite as code owners September 10, 2025 17:57

oliviertassinari added the docs Improvements or additions to the documentation. label Sep 10, 2025

oliviertassinari requested a review from michaldudak as a code owner September 10, 2025 17:57

oliviertassinari added type: regression A bug, but worse, it used to behave as expected. scope: docs-infra Involves the docs-infra product (https://www.notion.so/mui-org/b9f676062eb94747b6768209f7751305). labels Sep 10, 2025

oliviertassinari removed request for atomiks, colmtuite and michaldudak September 10, 2025 17:58

oliviertassinari commented Sep 10, 2025

View reviewed changes

[docs-infra] Clean API table generation

6649a9c

oliviertassinari force-pushed the fix-html-API-pages branch from c440fe7 to 6649a9c Compare September 10, 2025 18:07

oliviertassinari added 3 commits September 10, 2025 20:57

no visual regressions

45e85c2

no visual regressions

8719b1d

no visual regressions

2040900

mj12albert reviewed Sep 11, 2025

View reviewed changes

mj12albert mentioned this pull request Sep 11, 2025

[slider] Fix input attributes #2728

Merged

1 task

oliviertassinari mentioned this pull request Sep 18, 2025

[docs-infra] Fix WAVE false positive errors #2784

Merged

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Sep 30, 2025

oliviertassinari mentioned this pull request Oct 30, 2025

[docs] Fix invalid <dl> and <dt> nesting #3102

Open

1 task

		p: (props) => <p {...props} />,
		p: (props) => props.children,

Uh oh!

[docs-infra] Fix a11y and HTML errors on baseline docs page #2718

Are you sure you want to change the base?

[docs-infra] Fix a11y and HTML errors on baseline docs page #2718

Uh oh!

Conversation

oliviertassinari commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for base-ui ready!

Uh oh!

mui-bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size report

Uh oh!

oliviertassinari left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

oliviertassinari Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

oliviertassinari commented Sep 10, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 10, 2025 •

edited

Loading

netlify bot commented Sep 10, 2025 •

edited

Loading

mui-bot commented Sep 10, 2025 •

edited

Loading

oliviertassinari Sep 10, 2025 •

edited

Loading

oliviertassinari Sep 18, 2025 •

edited

Loading