From 090e27aee3c520ac0f3db7348a6373c88ee78b51 Mon Sep 17 00:00:00 2001
From: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>
Date: Mon, 30 Mar 2026 21:07:05 +0200
Subject: [PATCH] docs: Fix accessibility for assistive tools in documentation
 notes

Replace heading tags (h1, h2, h3) inside <aside> elements with <p class="note-title"> and add role="note" attribute. This fixes the document outline for screen readers while maintaining identical visual rendering for sighted users.
---
 .github/workflows/docs-accessibility.yml      |  21 ++++
 Makefile                                      |   4 +
 .../src/cronjob-tutorial/cronjob-tutorial.md  |  10 +-
 .../src/cronjob-tutorial/running-webhook.md   |   8 +-
 docs/book/src/cronjob-tutorial/running.md     |  14 +--
 .../webhook-implementation.md                 |   4 +-
 .../src/cronjob-tutorial/writing-tests.md     |   4 +-
 docs/book/src/faq.md                          |   4 +-
 docs/book/src/getting-started.md              |  32 +++---
 docs/book/src/migration/ai-helpers.md         |   4 +-
 docs/book/src/migration/discovery-commands.md |  12 +-
 docs/book/src/migration/manual-process.md     |  60 +++++-----
 docs/book/src/migration/multi-group.md        |  20 ++--
 docs/book/src/migration/namespace-scoped.md   |  32 +++---
 docs/book/src/migration/port-code.md          |  16 +--
 docs/book/src/migration/reorganize-layout.md  |   4 +-
 docs/book/src/migrations.md                   |  24 ++--
 .../src/multiversion-tutorial/conversion.md   |   4 +-
 .../src/multiversion-tutorial/deployment.md   |   4 +-
 .../src/multiversion-tutorial/tutorial.md     |   4 +-
 .../plugins/available/autoupdate-v1-alpha.md  |   8 +-
 .../available/deploy-image-plugin-v1-alpha.md |   8 +-
 .../src/plugins/available/go-v4-plugin.md     |   4 +-
 .../src/plugins/available/grafana-v1-alpha.md |   6 +-
 .../src/plugins/available/helm-v1-alpha.md    |  16 +--
 .../src/plugins/available/helm-v2-alpha.md    |  12 +-
 .../src/plugins/available/kustomize-v2.md     |   8 +-
 docs/book/src/plugins/extending.md            |   4 +-
 .../src/plugins/extending/custom-markers.md   |   4 +-
 .../src/plugins/extending/external-plugins.md |   6 +-
 docs/book/src/plugins/kustomize-v2.md         |   8 +-
 docs/book/src/plugins/plugins-versioning.md   |   4 +-
 docs/book/src/quick-start.md                  |  42 +++----
 docs/book/src/reference/admission-webhook.md  |  12 +-
 docs/book/src/reference/alpha_commands.md     |   4 +-
 docs/book/src/reference/artifacts.md          |   8 +-
 .../src/reference/commands/alpha_generate.md  |   8 +-
 .../src/reference/commands/alpha_update.md    |  12 +-
 docs/book/src/reference/completion.md         |   4 +-
 docs/book/src/reference/controller-gen.md     |   4 +-
 docs/book/src/reference/crd-scope.md          |  12 +-
 docs/book/src/reference/envtest.md            |  16 +--
 docs/book/src/reference/good-practices.md     |   4 +-
 docs/book/src/reference/manager-scope.md      |  12 +-
 docs/book/src/reference/markers.md            |   4 +-
 .../src/reference/markers/crd-validation.md   |   8 +-
 docs/book/src/reference/markers/scaffold.md   |  12 +-
 docs/book/src/reference/metrics.md            |  38 +++---
 docs/book/src/reference/platform.md           |  12 +-
 docs/book/src/reference/pprof-tutorial.md     |   4 +-
 docs/book/src/reference/raising-events.md     |   8 +-
 docs/book/src/reference/submodule-layouts.md  |  12 +-
 .../reference/using_an_external_resource.md   |   4 +-
 .../versions_compatibility_supportability.md  |   4 +-
 docs/book/theme/css/markers.css               |  35 ++++--
 hack/docs/check.sh                            |   5 +
 hack/docs/fix_note_accessibility.sh           | 108 ++++++++++++++++++
 hack/docs/generate.sh                         |   4 +
 test/check_docs_accessibility.sh              |  78 +++++++++++++
 59 files changed, 541 insertions(+), 306 deletions(-)
 create mode 100644 .github/workflows/docs-accessibility.yml
 create mode 100755 hack/docs/fix_note_accessibility.sh
 create mode 100755 test/check_docs_accessibility.sh

diff --git a/.github/workflows/docs-accessibility.yml b/.github/workflows/docs-accessibility.yml
new file mode 100644
index 00000000000..b4367da81e5
--- /dev/null
+++ b/.github/workflows/docs-accessibility.yml
@@ -0,0 +1,21 @@
+name: Docs Accessibility
+
+on:
+  push:
+    paths:
+      - '**/*.md'
+  pull_request:
+    paths:
+      - '**/*.md'
+
+jobs:
+  lint:
+    name: "Check Docs Accessibility"
+    runs-on: ubuntu-latest
+    # Pull requests from the same repository won't trigger this checks as they were already triggered by the push
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository)
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Run check
+        run: make test-docs-accessibility
diff --git a/Makefile b/Makefile
index 6c21602d513..8b61b0cdc25 100644
--- a/Makefile
+++ b/Makefile
@@ -234,6 +234,10 @@ test-external-plugin: install  ## Run tests for external plugin
 test-spaces:  ## Run the trailing spaces check
 	./test/check_spaces.sh
 
+.PHONY: test-docs-accessibility
+test-docs-accessibility:  ## Run the documentation accessibility check
+	./test/check_docs_accessibility.sh
+
 ## TODO: Remove me when go/v4 plugin be removed
 ## Deprecated
 .PHONY: test-legacy
diff --git a/docs/book/src/cronjob-tutorial/cronjob-tutorial.md b/docs/book/src/cronjob-tutorial/cronjob-tutorial.md
index f87ae89d94c..d958fb8e4a5 100644
--- a/docs/book/src/cronjob-tutorial/cronjob-tutorial.md
+++ b/docs/book/src/cronjob-tutorial/cronjob-tutorial.md
@@ -19,9 +19,9 @@ once, seeing them to completion.
 Instead of trying to tackle rewriting the Job controller as well, we'll
 use this as an opportunity to see how to interact with external types.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Following Along vs Jumping Ahead</h1>
+<p class="note-title">Following Along vs Jumping Ahead</p>
 
 Note that most of this tutorial is generated from literate Go files that
 live in the book source directory:
@@ -52,7 +52,7 @@ cd project
 kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project
 ```
 
-<aside class="note">
+<aside class="note" role="note">
 
 Your project's name defaults to that of your current working directory.
 You can pass `--project-name=<dns1123-label-string>` to set a different project name.
@@ -62,9 +62,9 @@ You can pass `--project-name=<dns1123-label-string>` to set a different project
 Now that we've got a project in place, let's take a look at what
 Kubebuilder has scaffolded for us so far...
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Developing in <code>$GOPATH</code></h1>
+<p class="note-title">Developing in <code>$GOPATH</code></p>
 
 If your project is initialized within [`GOPATH`][GOPATH-golang-docs], the implicitly called `go mod init` will interpolate the module path for you.
 Otherwise `--repo=<module path>` must be set.
diff --git a/docs/book/src/cronjob-tutorial/running-webhook.md b/docs/book/src/cronjob-tutorial/running-webhook.md
index 0ac135becc5..451355545ba 100644
--- a/docs/book/src/cronjob-tutorial/running-webhook.md
+++ b/docs/book/src/cronjob-tutorial/running-webhook.md
@@ -12,8 +12,8 @@ Run the following command to build your image locally.
 make docker-build docker-push IMG=<some-registry>/<project-name>:tag
 ```
 
-<aside class="note">
-<h1> Using Kind </h1>
+<aside class="note" role="note">
+<p class="note-title"> Using Kind </p>
 
 Consider incorporating Kind into your workflow for a faster, more efficient local development and CI experience.
 Note that, if you're using a Kind cluster, there's no need to push your image to a remote container registry.
@@ -73,8 +73,8 @@ kubectl create -f config/samples/batch_v1_cronjob.yaml
 You can also try to create an invalid CronJob (e.g. use an ill-formatted
 schedule field). You should see a creation failure with a validation error.
 
-<aside class="warning">
-<h3>The Bootstrapping Problem</h3>
+<aside class="warning" role="note">
+<p class="note-title">The Bootstrapping Problem</p>
 
 When you deploy a webhook into the same cluster that it will validate, you can run into a *bootstrapping issue*:
 the webhook may try to validate the creation of its own Pod before it’s actually running.
diff --git a/docs/book/src/cronjob-tutorial/running.md b/docs/book/src/cronjob-tutorial/running.md
index 7e745c2c441..d6794e29992 100644
--- a/docs/book/src/cronjob-tutorial/running.md
+++ b/docs/book/src/cronjob-tutorial/running.md
@@ -16,9 +16,9 @@ manifests using controller-tools, if needed:
 make install
 ```
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Too long annotations error</h1>
+<p class="note-title">Too long annotations error</p>
 
 If you encounter errors when applying the CRDs, due to `metadata.annotations` exceeding the
 262144 bytes limit, please refer to the specific entry in the [FAQ section](/faq#the-error-too-long-must-have-at-most-262144-bytes-is-faced-when-i-run-make-install-to-apply-the-crd-manifests-how-to-solve-it-why-this-error-is-faced).
@@ -29,9 +29,9 @@ Now that we've installed our CRDs, we can run the controller against our
 cluster.  This will use whatever credentials that we connect to the
 cluster with, so we don't need to worry about RBAC just yet.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Running webhooks locally</h1>
+<p class="note-title">Running webhooks locally</p>
 
 If you want to run the webhooks locally, you'll have to generate
 certificates for serving the webhooks, and place them in the right
@@ -82,8 +82,8 @@ make docker-build docker-push IMG=<some-registry>/<project-name>:tag
 make deploy IMG=<some-registry>/<project-name>:tag
 ```
 
-<aside class="note">
-<h1>Registry Permission</h1>
+<aside class="note" role="note">
+<p class="note-title">Registry Permission</p>
 
 This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment.
 Make sure you have the proper permission to the registry if the above commands don't work.
@@ -98,7 +98,7 @@ kind load docker-image <your-image-name>:tag --name <your-kind-cluster-name>
 
 To know more, see: [Using Kind For Development Purposes and CI](./../reference/kind.md)
 
-<h1>RBAC errors</h1>
+<p class="note-title">RBAC errors</p>
 
 If you encounter RBAC errors, you may need to grant yourself cluster-admin
 privileges or be logged in as admin. See [Prerequisites for using Kubernetes RBAC on GKE cluster v1.11.x and older][pre-rbc-gke] which may be your case.
diff --git a/docs/book/src/cronjob-tutorial/webhook-implementation.md b/docs/book/src/cronjob-tutorial/webhook-implementation.md
index ea4b4375a42..e1d7d3787a6 100644
--- a/docs/book/src/cronjob-tutorial/webhook-implementation.md
+++ b/docs/book/src/cronjob-tutorial/webhook-implementation.md
@@ -37,8 +37,8 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob --defaultin
 
 This changes the path in the webhook marker annotation but does not change where the webhook files are scaffolded. The webhook files will still be created in `internal/webhook/v1/`.
 
-<aside class="note">
-<h1>Version Requirements</h1>
+<aside class="note" role="note">
+<p class="note-title">Version Requirements</p>
 
 Custom webhook paths require **controller-runtime v0.21+**. In earlier versions (< `v0.21`), the webhook path must follow a specific pattern and cannot be customized. The path is automatically generated based on the resource's group, version, and kind (e.g., `/mutate-batch-v1-cronjob`).
 
diff --git a/docs/book/src/cronjob-tutorial/writing-tests.md b/docs/book/src/cronjob-tutorial/writing-tests.md
index 1c758956c63..f0593002860 100644
--- a/docs/book/src/cronjob-tutorial/writing-tests.md
+++ b/docs/book/src/cronjob-tutorial/writing-tests.md
@@ -9,8 +9,8 @@ The basic approach is that, in your generated `suite_test.go` file, you will use
 
 If you want to tinker with how your envtest cluster is configured, see section [Configuring envtest for integration tests](../reference/envtest.md) as well as the [`envtest docs`](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest?tab=doc).
 
-<aside class="note">
-<h1>Other Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Other Examples</p>
 
 If you would like to see additional examples of controller tests generated by Kubebuilder, take a look at the <a href="../plugins/available/deploy-image-plugin-v1-alpha.md">Deploy Image plugin (deploy-image/v1-alpha)</a>.
 This plugin scaffolds APIs and controllers for managing an Operand (container image) on a cluster, following recommended patterns.
diff --git a/docs/book/src/faq.md b/docs/book/src/faq.md
index 3b7a55d7843..024dab3fc5b 100644
--- a/docs/book/src/faq.md
+++ b/docs/book/src/faq.md
@@ -1,8 +1,8 @@
 
 # FAQ
 
-<aside class="note">
-<h1> Controller-Runtime FAQ </h1>
+<aside class="note" role="note">
+<p class="note-title"> Controller-Runtime FAQ </p>
 
 Kubebuilder is developed on top of the [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime)
 and [controller-tools](https://github.com/kubernetes-sigs/controller-tools) libraries. We recommend you also check
diff --git a/docs/book/src/getting-started.md b/docs/book/src/getting-started.md
index 90683b2b19b..b4bd1d82b84 100644
--- a/docs/book/src/getting-started.md
+++ b/docs/book/src/getting-started.md
@@ -7,8 +7,8 @@ We will create a sample project to let you know how it works. This sample will:
 - Not allow more instances than the size defined in the CR which will be applied
 - Update the Memcached CR status
 
-<aside class="note">
-<h1>Why Operators?</h1>
+<aside class="note" role="note">
+<p class="note-title">Why Operators?</p>
 
 By following the [Operator Pattern][k8s-operator-pattern], it’s possible not only to provide all expected resources
 but also to manage them dynamically, programmatically, and at execution time. To illustrate this idea, imagine if
@@ -17,8 +17,8 @@ without any human intervention.
 
 </aside>
 
-<aside class="note">
-<h1>Following Along vs Jumping Ahead</h1>
+<aside class="note" role="note">
+<p class="note-title">Following Along vs Jumping Ahead</p>
 
 Note that most of this tutorial is generated from literate Go files that
 form a runnable project, and live in the book source directory:
@@ -38,8 +38,8 @@ cd $GOPATH/memcached-operator
 kubebuilder init --domain=example.com
 ```
 
-<aside class="note">
-<h1>Developing in $GOPATH</h1>
+<aside class="note" role="note">
+<p class="note-title">Developing in $GOPATH</p>
 
 If your project is initialized within [`GOPATH`][GOPATH-golang-docs], the implicitly called `go mod init` will interpolate the module path for you.
 Otherwise `--repo=<module path>` must be set.
@@ -66,8 +66,8 @@ By leveraging the Kubebuilder tool, we can define our APIs and objects represent
 While we've added only one Kind of resource in this example, we can have as many `Groups` and `Kinds` as necessary.
 To make it easier to understand, think of CRDs as the definition of our custom Objects, while CRs are instances of them.
 
-<aside class="note">
-<h1> Please ensure that you check </h1>
+<aside class="note" role="note">
+<p class="note-title"> Please ensure that you check </p>
 
 [Groups and Versions and Kinds, oh my!][group-kind-oh-my].
 
@@ -106,8 +106,8 @@ type MemcachedStatus struct {
 }
 ```
 
-<aside class="note">
-<h1> Status Conditions </h1>
+<aside class="note" role="note">
+<p class="note-title"> Status Conditions </p>
 
 Kubernetes has established conventions, and because of this, we use
 Status Conditions here. We want our custom APIs and controllers to behave
@@ -197,8 +197,8 @@ reconcile App {
 }
 ```
 
-<aside class="note">
-<h1> Return Options </h1>
+<aside class="note" role="note">
+<p class="note-title"> Return Options </p>
 
 The following are a few possible return options to restart the Reconcile:
 
@@ -356,9 +356,9 @@ if err := ctrl.SetControllerReference(memcached, dep, r.Scheme); err != nil {
 }
 ```
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1><code>ownerRef</code> and Cascading Events</h1>
+<p class="note-title"><code>ownerRef</code> and Cascading Events</p>
 
 The ownerRef is crucial not only for allowing us to observe changes on the specific resource but also because,
 if we delete the Memcached Custom Resource (CR) from the cluster, we want all resources owned by it to be automatically
@@ -435,8 +435,8 @@ see: [Run It On the Cluster](./quick-start#run-it-on-the-cluster)
 - To delve deeper into developing your solution, consider going through the [CronJob Tutorial][cronjob-tutorial]
 - For insights on optimizing your approach, refer to the [Best Practices][best-practices] documentation.
 
-<aside class="note">
-<h1> Using Deploy Image plugin to generate APIs and source code </h1>
+<aside class="note" role="note">
+<p class="note-title"> Using Deploy Image plugin to generate APIs and source code </p>
 
 Now that you have a better understanding, you might want to check out the [Deploy Image][deploy-image] Plugin.
 This plugin allows users to scaffold APIs/Controllers to deploy and manage an Operand (image) on the cluster.
diff --git a/docs/book/src/migration/ai-helpers.md b/docs/book/src/migration/ai-helpers.md
index 2424330468a..712836a1130 100644
--- a/docs/book/src/migration/ai-helpers.md
+++ b/docs/book/src/migration/ai-helpers.md
@@ -2,9 +2,9 @@
 
 AI can assist manual migrations by reducing repetitive work and helping resolve breaking changes. It won't replace the [Manual Migration Process](./manual-process.md), but it can help reduce effort and accomplish the goal.
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Important</h1>
+<p class="note-title">Important</p>
 
 These AI instructions are provided as examples to help guide your migration. Always validate AI output carefully - you remain responsible for ensuring correctness.
 
diff --git a/docs/book/src/migration/discovery-commands.md b/docs/book/src/migration/discovery-commands.md
index 73254c18667..296bad276d2 100644
--- a/docs/book/src/migration/discovery-commands.md
+++ b/docs/book/src/migration/discovery-commands.md
@@ -2,9 +2,9 @@
 
 Use AI to analyze your (now reorganized) Kubebuilder project and generate all CLI commands needed to recreate it with the latest version.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>You May Not Need This</h1>
+<p class="note-title">You May Not Need This</p>
 
 **If you have a PROJECT file** and used Kubebuilder CLI to scaffold **all** resources (APIs, controllers, webhooks), you can use `kubebuilder alpha generate` instead.
 
@@ -17,9 +17,9 @@ The `alpha generate` command re-scaffolds everything tracked in your PROJECT fil
 
 </aside>
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>When to Use This</h1>
+<p class="note-title">When to Use This</p>
 
 Use AI discovery if your project has:
 - APIs not tracked in the PROJECT file (manually created)
@@ -33,9 +33,9 @@ AI scans your entire codebase to discover everything, ensuring nothing is missed
 
 ## Instructions to provide to your AI assistant
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Standard Kubebuilder Layout Only</h1>
+<p class="note-title">Standard Kubebuilder Layout Only</p>
 
 These instructions work for projects using **standard Kubebuilder directory layout**:
 - API types in `api/` directory (some projects use `apis/`)
diff --git a/docs/book/src/migration/manual-process.md b/docs/book/src/migration/manual-process.md
index eb63e482527..ef92f757047 100644
--- a/docs/book/src/migration/manual-process.md
+++ b/docs/book/src/migration/manual-process.md
@@ -16,8 +16,8 @@ Also, before starting, it is recommended to check [What's in a basic project?][b
 to better understand the project layouts and structure.
 
 
-<aside class="warning">
-<h1>About Manual Migration</h1>
+<aside class="warning" role="note">
+<p class="note-title">About Manual Migration</p>
 
 Manual migration is more complex than automated methods but gives you complete control. Use manual migration when:
 - Your project has significant customizations
@@ -53,9 +53,9 @@ git checkout -b reorganize
 
 ### 1.2 Reorganize file locations
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Skip if Using AI Migration Helper</h1>
+<p class="note-title">Skip if Using AI Migration Helper</p>
 
 If you used [Step 1: Reorganize to New Layout](./reorganize-layout.md) AI migration helper, your project is already reorganized. Skip to [Phase 2](#phase-2-migrate-to-latest-version).
 
@@ -152,9 +152,9 @@ find . -not -path './.git*' -not -name '.' -not -name '..' -delete
 
 Identify the information you'll need for initialization from your backup.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Skip if Using AI Migration Helper</h1>
+<p class="note-title">Skip if Using AI Migration Helper</p>
 
 If you used [Step 2: Discovery CLI Commands](./discovery-commands.md) AI migration helper, you already have a complete script with all commands. Execute it and skip to [Step 4: Port Your Custom Code](#step-4-port-your-custom-code).
 
@@ -208,8 +208,8 @@ kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io
 
 Replace with your actual domain and repository (module path).
 
-<aside class="note">
-<h1>Understanding init options</h1>
+<aside class="note" role="note">
+<p class="note-title">Understanding init options</p>
 
 - `--domain`: The domain for your API groups (e.g., `tutorial.kubebuilder.io`). Your full API groups will be `<group>.<domain>`.
 - `--repo`: Your Go module path (same as in `go.mod`)
@@ -241,8 +241,8 @@ You can also check your backup's `PROJECT` file for `multigroup: true`.
 kubebuilder edit --multigroup=true
 ```
 
-<aside class="warning">
-<h1>Important</h1>
+<aside class="warning" role="note">
+<p class="note-title">Important</p>
 
 This must be done before creating any APIs to ensure they're scaffolded in the multi-group structure.
 
@@ -282,8 +282,8 @@ resources:
     version: v1
 ```
 
-<aside class="note">
-<h1>Tip</h1>
+<aside class="note" role="note">
+<p class="note-title">Tip</p>
 
 Make a list of all APIs with their group, version, kind, and whether they have a controller.
 This will help you systematically re-scaffold everything.
@@ -320,8 +320,8 @@ See the [Quick Start][quick-start] guide for a detailed walkthrough of the API c
 
 Repeat this process for **ALL** APIs in your project.
 
-<aside class="note">
-<h1>Using External Types (controllers for types not defined in your project)</h1>
+<aside class="note" role="note">
+<p class="note-title">Using External Types (controllers for types not defined in your project)</p>
 
 If your project has controllers for Kubernetes built-in types (like `Deployment`, `Pod`) or types from other projects:
 
@@ -388,8 +388,8 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob --defaultin
 
 If your project has multi-version APIs with conversion webhooks, you need to set up the hub-spoke conversion pattern.
 
-<aside class="note">
-<h1>Understanding Hub-Spoke Conversion</h1>
+<aside class="note" role="note">
+<p class="note-title">Understanding Hub-Spoke Conversion</p>
 
 In Kubernetes multi-version APIs, the **hub** is the version that all other versions (spokes) convert to and from:
 - **Hub version**: Usually the most complete/stable version (often the storage version)
@@ -430,8 +430,8 @@ The command generates method stubs that you'll fill in during Step 4:
 
 See the [Multi-Version Tutorial][multiversion-tutorial] for comprehensive guidance on implementing the conversion logic.
 
-<aside class="note">
-<H1> Forget a type of webhook ? </h1>
+<aside class="note" role="note">
+<p class="note-title"> Forget a type of webhook ? </p>
 
 If you forget a webhook type, use `--force` to re-run the command:
 
@@ -440,8 +440,8 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob --defaultin
 ```
 </aside>
 
-<aside class="note">
-<h1>Webhook for External Types</h1>
+<aside class="note" role="note">
+<p class="note-title">Webhook for External Types</p>
 
 **For external types**, you can also create webhooks:
 
@@ -460,9 +460,9 @@ make manifests && make build
 
 ## Step 4: Port Your Custom Code
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Using AI Migration Helper</h1>
+<p class="note-title">Using AI Migration Helper</p>
 
 If you used [Step 3: Port Custom Code](./port-code.md) AI migration helper, your code is already ported.
 
@@ -472,8 +472,8 @@ You may skip to [Step 5](#step-5-test-and-verify). However, it's still recommend
 
 Manually port your custom business logic and configurations from the backup to the new project.
 
-<aside class="note">
-<h1>Use diff tools</h1>
+<aside class="note" role="note">
+<p class="note-title">Use diff tools</p>
 
 Use IDE diff tools or commands like `diff -r ../migration-backup/ .` to compare directories and identify all customizations you need to port.
 Most modern IDEs support directory-level comparison which makes this process much easier.
@@ -561,8 +561,8 @@ Webhooks have changed location between Kubebuilder versions. Be aware of the pat
 4. **Helper functions** - Any validation or defaulting helper functions
 5. **Webhook markers** - Usually auto-generated, but verify they match your needs
 
-<aside class="note">
-<h1>Important</h1>
+<aside class="note" role="note">
+<p class="note-title">Important</p>
 
 Even if the webhook file is in a different location, the implementation logic remains largely the same.
 Copy the method implementations, not just the entire file.
@@ -646,8 +646,8 @@ For dependencies, run `go mod tidy` or copy `go.mod`/`go.sum` from backup for co
 Check for additional customizations (Makefile, Dockerfile, test files). Use diff tools to compare with backup and identify missed files.
 
 
-<aside class="note">
-<h1>Using diff tools</h1>
+<aside class="note" role="note">
+<p class="note-title">Using diff tools</p>
 
 Use your IDE's diff tools to compare the current directory with your backup (`../migration-backup/`) or use git to compare
 your current branch with your main branch. This helps identify any files you may have missed.
@@ -676,9 +676,9 @@ make test && make lint-fix
 
 Deploy to a test cluster (e.g. [kind][kind-doc]) and verify the changes (i.e. validate expected behavior, run regression checks, confirm the full CI pipeline still passes, and execute the e2e tests).
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>If You Have a Helm Chart</h1>
+<p class="note-title">If You Have a Helm Chart</p>
 
 If you had a Helm chart to distribute your project, you may want to regenerate it with the [helm/v2-alpha plugin](../plugins/available/helm-v2-alpha.md), then apply your customizations.
 
diff --git a/docs/book/src/migration/multi-group.md b/docs/book/src/migration/multi-group.md
index e90a19bdec8..11949ce4171 100644
--- a/docs/book/src/migration/multi-group.md
+++ b/docs/book/src/migration/multi-group.md
@@ -4,9 +4,9 @@ Kubebuilder scaffolds single-group projects by default to keep things simple, as
 
 See the [design doc][multigroup-design] for the rationale behind this design decision.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>What's a Multi-Group Project?</h1>
+<p class="note-title">What's a Multi-Group Project?</p>
 
 Multi-group layout is useful when you're building APIs for different purposes or domains. For example, you might have:
 - A `batch` group for job-related resources (CronJob, Job)
@@ -19,9 +19,9 @@ See [Groups and Versions and Kinds, oh my!][gvks] to better understand API group
 
 </aside>
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>AI-Assisted Migration</h1>
+<p class="note-title">AI-Assisted Migration</p>
 
 This migration involves repetitive file moving and import path updates. If you're using an AI coding assistant, see the [AI-Assisted Migration](#ai-assisted-migration) section for ready-to-use instructions.
 
@@ -51,8 +51,8 @@ You can tell which layout you're using by checking your `PROJECT` file for `mult
 
 The following steps migrate the [CronJob example][cronjob-tutorial] from single-group to multi-group layout.
 
-<aside class="note">
-<h1>Starting new projects with multigroup</h1>
+<aside class="note" role="note">
+<p class="note-title">Starting new projects with multigroup</p>
 
 If you're starting a **new project** and already know you want multigroup layout, you can use the `--multigroup` flag during initialization:
 
@@ -76,8 +76,8 @@ This command updates your `PROJECT` file by adding `multigroup: true`. After thi
 - **New APIs** you create will automatically use the multi-group structure (`api/<group>/<version>/`)
 - **Existing APIs** remain in their current location and must be migrated manually (steps 3-9 below)
 
-<aside class="note">
-<h1>What this command changes</h1>
+<aside class="note" role="note">
+<p class="note-title">What this command changes</p>
 
 The command adds or updates this line in your PROJECT file:
 
@@ -271,9 +271,9 @@ make build          # Build the project
 
 If you're using an AI coding assistant (Cursor, GitHub Copilot, etc.), you can automate most of the migration steps.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>AI Migration Instructions</h1>
+<p class="note-title">AI Migration Instructions</p>
 
 **Prerequisites:**
 1. First, identify the API group name from `api/v1/groupversion_info.go` (look for `+groupName=<group>.<domain>`)
diff --git a/docs/book/src/migration/namespace-scoped.md b/docs/book/src/migration/namespace-scoped.md
index b805a5e3530..733d1ac8329 100644
--- a/docs/book/src/migration/namespace-scoped.md
+++ b/docs/book/src/migration/namespace-scoped.md
@@ -2,8 +2,8 @@
 
 This guide covers converting **existing cluster-scoped projects** to namespace-scoped deployment.
 
-<aside class="note">
-<h1>Creating New Namespace-Scoped Projects</h1>
+<aside class="note" role="note">
+<p class="note-title">Creating New Namespace-Scoped Projects</p>
 
 If you're creating a **new project**, simply use:
 
@@ -28,8 +28,8 @@ By default, Kubebuilder scaffolds cluster-scoped managers that watch and manage
 - Managing cluster-scoped resources (Nodes, ClusterRoles, Namespaces, etc.)
 - Single manager instance managing resources across all namespaces
 
-<aside class="note">
-<h1>AI-Assisted Migration</h1>
+<aside class="note" role="note">
+<p class="note-title">AI-Assisted Migration</p>
 
 This migration involves updating RBAC markers across multiple controller files. If you're using an AI coding assistant, see the [AI-Assisted Migration](#ai-assisted-migration) section for ready-to-use instructions.
 
@@ -44,8 +44,8 @@ This migration involves updating RBAC markers across multiple controller files.
 4. Run `make manifests` - regenerate RBAC from updated markers
 5. Verify and deploy
 
-<aside class="warning">
-<h2>Manual Steps Required</h2>
+<aside class="warning" role="note">
+<p class="note-title">Manual Steps Required</p>
 
 The `edit` command scaffolds RBAC files and updates manager.yaml automatically (with `--force`), but **cannot** update existing controller files or cmd/main.go.
 
@@ -143,8 +143,8 @@ if err != nil {
 }
 ```
 
-<aside class="note">
-<h1>If You Didn't Use --force</h1>
+<aside class="note" role="note">
+<p class="note-title">If You Didn't Use --force</p>
 
 If you ran `kubebuilder edit --namespaced` without `--force`, manually add WATCH_NAMESPACE to `config/manager/manager.yaml`:
 
@@ -196,8 +196,8 @@ func (r *CronJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ct
 
 Replace `project-system` with your namespace (found in `config/default/kustomization.yaml` under the `namespace:` field).
 
-<aside class="note">
-<h1>New Controllers Get This Automatically</h1>
+<aside class="note" role="note">
+<p class="note-title">New Controllers Get This Automatically</p>
 
 After running `kubebuilder edit --namespaced --force`, any new controllers created will automatically have the `namespace=` parameter:
 
@@ -239,8 +239,8 @@ metadata:
   # Note: namespace is added by kustomize during build, not in source
 ```
 
-<aside class="note">
-<h1>Metrics Auth Role Stays Cluster-Scoped</h1>
+<aside class="note" role="note">
+<p class="note-title">Metrics Auth Role Stays Cluster-Scoped</p>
 
 The `config/rbac/metrics_auth_role.yaml` will remain `kind: ClusterRole` - this is correct. The metrics authentication uses cluster-scoped APIs (TokenReview, SubjectAccessReview) and must stay cluster-scoped even in namespace-scoped projects.
 
@@ -270,9 +270,9 @@ kubectl apply -f config/samples/ -n <manager-namespace>
 kubectl apply -f config/samples/ -n other-namespace
 ```
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Webhooks and Namespace-Scoped Mode</h1>
+<p class="note-title">Webhooks and Namespace-Scoped Mode</p>
 
 If your project has webhooks, the manager cache is restricted to `WATCH_NAMESPACE`, but webhooks receive requests from all namespaces by default.
 
@@ -292,9 +292,9 @@ See the [Webhook Bootstrap Problem](../reference/webhook-bootstrap-problem.html)
 
 If you're using an AI coding assistant (Cursor, GitHub Copilot, etc.), you can automate the manual migration steps.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>AI Migration Instructions</h1>
+<p class="note-title">AI Migration Instructions</p>
 
 **Instructions to provide to your AI assistant:**
 
diff --git a/docs/book/src/migration/port-code.md b/docs/book/src/migration/port-code.md
index f78c0a2344e..f162e5448dc 100644
--- a/docs/book/src/migration/port-code.md
+++ b/docs/book/src/migration/port-code.md
@@ -2,9 +2,9 @@
 
 After reorganizing your project (Step 1) and executing scaffolding commands from discovery (Step 2), use AI to port your custom code to the new project.
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Important: Best Effort Only</h1>
+<p class="note-title">Important: Best Effort Only</p>
 
 The AI instructions below are provided as an **example** to help you get started. Due to the complexity and variety of Kubebuilder projects, we **cannot guarantee** it will work perfectly for all projects or be 100% accurate.
 
@@ -18,9 +18,9 @@ The instructions may help you understand how to approach certain migration scena
 
 </aside>
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Prerequisites</h1>
+<p class="note-title">Prerequisites</p>
 
 Before using these AI instructions:
 1. You've reorganized your project using Step 1 (`make build` succeeds)
@@ -275,9 +275,9 @@ The AI will:
 
 **Critical: Review carefully!**
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Manual Review Required</h1>
+<p class="note-title">Manual Review Required</p>
 
 After AI ports the code:
 
@@ -385,9 +385,9 @@ After AI ports your code:
 1. Check if nothing is missed, broken or wrongly ported
 2. Deploy to test cluster - Verify behavior
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>If You Have a Helm Chart</h1>
+<p class="note-title">If You Have a Helm Chart</p>
 
 If you had a Helm chart to distribute your project, you may want to consider regenerate with the [helm/v2-alpha plugin](../plugins/available/helm-v2-alpha.md)
 and then applying your customizations on top.
diff --git a/docs/book/src/migration/reorganize-layout.md b/docs/book/src/migration/reorganize-layout.md
index 655bb1de840..ef530caa5c1 100644
--- a/docs/book/src/migration/reorganize-layout.md
+++ b/docs/book/src/migration/reorganize-layout.md
@@ -11,9 +11,9 @@ Reorganize files to match the new directory layout.
 
 **If ALL are already in the new layout**, skip to [Step 2](./discovery-commands.md)
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Important: Best Effort Only</h1>
+<p class="note-title">Important: Best Effort Only</p>
 
 These AI instructions work for projects using **standard Kubebuilder directory layout**. Projects with heavily customized structures may require manual reorganization.
 
diff --git a/docs/book/src/migrations.md b/docs/book/src/migrations.md
index f264a90d694..b33fefafc50 100644
--- a/docs/book/src/migrations.md
+++ b/docs/book/src/migrations.md
@@ -7,8 +7,8 @@ Migration may involve updating to a newer plugin version (e.g., from `go.kubebui
 
 Kubebuilder provides multiple migration paths to suit your workflow. Choose the approach that best fits your needs.
 
-<aside class="note">
-<h1>Understanding the PROJECT File</h1>
+<aside class="note" role="note">
+<p class="note-title">Understanding the PROJECT File</p>
 
 From Kubebuilder `v3.0.0` onwards, all inputs used by Kubebuilder are tracked in the [PROJECT][project-config] file.
 If you use the CLI to generate your scaffolds, this file will record the project's configuration and metadata,
@@ -21,8 +21,8 @@ which automation tools (alpha update, alpha generate, autoupdate plugin) depend
 
 </aside>
 
-<aside class="warning">
-<h1>Project Customizations</h1>
+<aside class="warning" role="note">
+<p class="note-title">Project Customizations</p>
 
 After using the CLI to create your project, you are free to customize the business logic and add features as you see fit.
 However, it is not recommended to deviate from the proposed project layout unless you know what you are doing.
@@ -58,8 +58,8 @@ for projects that follow the standard scaffold.
 kubebuilder edit --plugins="autoupdate/v1-alpha"
 ```
 
-<aside class="note">
-<h1>Requirements and Limitations</h1>
+<aside class="note" role="note">
+<p class="note-title">Requirements and Limitations</p>
 
 - Requires GitHub repository (GitHub Actions workflow)
 - Requires branch protection rules for safety (recommended)
@@ -81,8 +81,8 @@ kubebuilder alpha update
 This command uses the same underlying mechanism as the AutoUpdate Plugin. You can migrate your project,
 resolve any conflicts if needed, and then push a Pull Request from your local environment.
 
-<aside class="note">
-<h1>Requirements and Limitations</h1>
+<aside class="note" role="note">
+<p class="note-title">Requirements and Limitations</p>
 
 - Requires projects created with Kubebuilder **`v4.5.0`** or later
 - For projects created before `v4.6.0`: the CLI version is not tracked in the `PROJECT` file, so you may need to use `alpha generate` first to establish a baseline
@@ -108,8 +108,8 @@ establish a baseline for future automated updates.
 kubebuilder alpha generate
 ```
 
-<aside class="note">
-<h1>Requirements and Limitations</h1>
+<aside class="note" role="note">
+<p class="note-title">Requirements and Limitations</p>
 
 - Requires a `PROJECT` file (projects created with Kubebuilder **v3.0.0** or later)
 - Only re-scaffolds resources that were created using the CLI and tracked in the `PROJECT` file
@@ -131,8 +131,8 @@ webhooks, and other resources. Then, manually copy your business logic and custo
 
 To streamline this one-time migration, [AI Migration Helpers](./migration/ai-helpers.md) have been added to automate repetitive tasks.
 
-<aside class="note">
-<h1>When to Use Manual Migration</h1>
+<aside class="note" role="note">
+<p class="note-title">When to Use Manual Migration</p>
 
 Use this approach when:
 - Your project was created with Kubebuilder versions **before `v3.0.0`** (no `PROJECT` file)
diff --git a/docs/book/src/multiversion-tutorial/conversion.md b/docs/book/src/multiversion-tutorial/conversion.md
index 4166992e419..b66ccd45a1b 100644
--- a/docs/book/src/multiversion-tutorial/conversion.md
+++ b/docs/book/src/multiversion-tutorial/conversion.md
@@ -13,8 +13,8 @@ The above command will generate the `cronjob_conversion.go` next to our
 `cronjob_types.go` file, to avoid
 cluttering up our main types file with extra functions.
 
-<aside class="note">
-<h1>Conversion Webhooks and Custom Paths</h1>
+<aside class="note" role="note">
+<p class="note-title">Conversion Webhooks and Custom Paths</p>
 
 Unlike defaulting and validation webhooks, conversion webhooks do not support custom paths
 via command-line flags. Conversion webhooks use CRD conversion configuration
diff --git a/docs/book/src/multiversion-tutorial/deployment.md b/docs/book/src/multiversion-tutorial/deployment.md
index 617f0b35dd7..83f4e0578b5 100644
--- a/docs/book/src/multiversion-tutorial/deployment.md
+++ b/docs/book/src/multiversion-tutorial/deployment.md
@@ -81,9 +81,9 @@ respectively.  Notice that each has a different API version.
 Finally, if we wait a bit, we should notice that our CronJob continues to
 reconcile, even though our controller is written against our v1 API version.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>kubectl and Preferred Versions</h1>
+<p class="note-title">kubectl and Preferred Versions</p>
 
 When we access our API types from Go code, we ask for a specific version
 by using that version's Go type (e.g. `batchv2.CronJob`).
diff --git a/docs/book/src/multiversion-tutorial/tutorial.md b/docs/book/src/multiversion-tutorial/tutorial.md
index 192b7498a08..ad69d593ae5 100644
--- a/docs/book/src/multiversion-tutorial/tutorial.md
+++ b/docs/book/src/multiversion-tutorial/tutorial.md
@@ -11,9 +11,9 @@ different versions are supported by our CronJob project.
 If you haven't already, make sure you've gone through the base [CronJob
 Tutorial](/cronjob-tutorial/cronjob-tutorial.md).
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Following Along vs Jumping Ahead</h1>
+<p class="note-title">Following Along vs Jumping Ahead</p>
 
 Note that most of this tutorial is generated from literate Go files that
 form a runnable project, and live in the book source directory:
diff --git a/docs/book/src/plugins/available/autoupdate-v1-alpha.md b/docs/book/src/plugins/available/autoupdate-v1-alpha.md
index 2fd9cc313f9..98af2a6cc49 100644
--- a/docs/book/src/plugins/available/autoupdate-v1-alpha.md
+++ b/docs/book/src/plugins/available/autoupdate-v1-alpha.md
@@ -7,8 +7,8 @@ Kubebuilder release is available — keeping your project **maintained, secure,
 This automation uses the [`kubebuilder alpha update`][alpha-update-command] command with a **3-way merge strategy** to
 refresh your project scaffold, and wraps it in a GitHub Actions workflow that opens an **Issue** with a **Pull Request compare link** so you can create the PR and review it.
 
-<aside class="warning">
-<h3>Protect your branches</h3>
+<aside class="warning" role="note">
+<p class="note-title">Protect your branches</p>
 
 This workflow by default **only** creates and pushes the merged files to a branch
 called `kubebuilder-update-from-<from-version>-to-<to-version>`.
@@ -47,8 +47,8 @@ If you want AI-generated summaries in your update issues:
 kubebuilder edit --plugins="autoupdate/v1-alpha" --use-gh-models
 ```
 
-<aside class="note">
-<h1>Permissions required to use GitHub Models in GitHub Actions</h1>
+<aside class="note" role="note">
+<p class="note-title">Permissions required to use GitHub Models in GitHub Actions</p>
 
 To use GitHub Models in your workflows, organization and repository administrators must grant this permission.
 
diff --git a/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
index cfa88033e98..2fe650d61db 100644
--- a/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
+++ b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
@@ -9,8 +9,8 @@ By using this plugin, you will get:
 - Custom resource samples updated with the necessary specifications.
 - Environment variable support for managing the Operand (image) within the manager.
 
-<aside class="note">
-<h1>Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Examples</p>
 
 See the `project-v4-with-plugins` directory under the [testdata][testdata]
 directory in the Kubebuilder project to check an example
@@ -65,8 +65,8 @@ kubebuilder create api \
    kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,--memory-limit=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha"
    ```
 
-<aside class="warning">
-<h1>Note on make run:</h1>
+<aside class="warning" role="note">
+<p class="note-title">Note on make run:</p>
 
 When running the project locally with `make run`, the Operand image
 provided will be stored as an environment variable in the
diff --git a/docs/book/src/plugins/available/go-v4-plugin.md b/docs/book/src/plugins/available/go-v4-plugin.md
index b16b21034bf..6813740d875 100644
--- a/docs/book/src/plugins/available/go-v4-plugin.md
+++ b/docs/book/src/plugins/available/go-v4-plugin.md
@@ -10,8 +10,8 @@ that helps in constructing sets of [controllers][controller-runtime].
 By following the [quickstart][quickstart] and creating any project,
 you will be using this plugin by default.
 
-<aside class="note">
-<h1>Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Examples</p>
 
 You can check samples using this plugin by looking at the `project-v4-<options>` projects under the [testdata][testdata]
 directory on the root directory of the Kubebuilder project.
diff --git a/docs/book/src/plugins/available/grafana-v1-alpha.md b/docs/book/src/plugins/available/grafana-v1-alpha.md
index d086fe17f09..f9647f3bb35 100644
--- a/docs/book/src/plugins/available/grafana-v1-alpha.md
+++ b/docs/book/src/plugins/available/grafana-v1-alpha.md
@@ -5,8 +5,8 @@ scaffold Grafana Dashboards to allow you to check out the
 default metrics which are exported by projects
 using [controller-runtime][controller-runtime].
 
-<aside class="note">
-<h1>Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Examples</p>
 
 You can check its default scaffold by looking at the `project-v4-with-plugins` projects
 under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
@@ -32,7 +32,7 @@ collected by Prometheus via [Grafana][grafana].
   - Prometheus Data source
     ![pre][prometheus-data-source]
 
-<aside class="note">
+<aside class="note" role="note">
 
 Check the [metrics][reference-metrics-doc] to know how to enable the metrics for your projects scaffold with Kubebuilder.
 
diff --git a/docs/book/src/plugins/available/helm-v1-alpha.md b/docs/book/src/plugins/available/helm-v1-alpha.md
index a27f3ea8b72..539b1d3f752 100644
--- a/docs/book/src/plugins/available/helm-v1-alpha.md
+++ b/docs/book/src/plugins/available/helm-v1-alpha.md
@@ -1,7 +1,7 @@
 # Helm Plugin (`helm/v1-alpha`) - **DEPRECATED**
 
-<aside class="warning">
-<h1> Deprecated Plugin</h1>
+<aside class="warning" role="note">
+<p class="note-title"> Deprecated Plugin</p>
 
 The `helm/v1-alpha` plugin is **deprecated**. Please use [`helm/v2-alpha`](./helm-v2-alpha.md) instead.
 
@@ -30,8 +30,8 @@ kubectl apply -f https://raw.githubusercontent.com/<org>/project-v4/<tag or bran
 However, in many scenarios, you might prefer to provide a Helm chart to package your solution.
 If so, you can use this plugin to generate the Helm chart under the `dist` directory.
 
-<aside class="note">
-<h1>Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Examples</p>
 
 You can check the plugin usage by looking at `project-v4-with-plugins` samples
 under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
@@ -50,8 +50,8 @@ under the [testdata][testdata] directory on the root directory of the Kubebuilde
   under `dist/chart/values.yaml`, and the `templates/manager/manager.yaml`, you will need to manually reapply your customizations on top
   of the latest changes after regenerating the Helm chart.
 
-<aside class="note">
-<H1> Why CRDs are added under templates? </H1>
+<aside class="note" role="note">
+<p class="note-title"> Why CRDs are added under templates? </p>
 
 Although [Helm best practices](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#method-1-let-helm-do-it-for-you) recommend placing CRDs under a top-level `crds/` directory, the Kubebuilder Helm plugin intentionally places them under `templates/crd`.
 
@@ -92,8 +92,8 @@ kubebuilder init
 make manifests
 kubebuilder edit --plugins=helm/v1-alpha
 ```
-<aside class="note">
-  <h1>Use the edit command to update the Helm Chart with the latest changes</h1>
+<aside class="note" role="note">
+  <p class="note-title">Use the edit command to update the Helm Chart with the latest changes</p>
 
   After making changes to your project, ensure that you run `make manifests` and then
   use the command `kubebuilder edit --plugins=helm/v1-alpha` to update the Helm Chart.
diff --git a/docs/book/src/plugins/available/helm-v2-alpha.md b/docs/book/src/plugins/available/helm-v2-alpha.md
index a5abe12145c..dd14dc76cb8 100644
--- a/docs/book/src/plugins/available/helm-v2-alpha.md
+++ b/docs/book/src/plugins/available/helm-v2-alpha.md
@@ -123,8 +123,8 @@ The plugin creates a chart layout that matches your `config/`:
         └── my-config.yaml
 ```
 
-<aside class="note">
-<H1>Chart Structure</H1>
+<aside class="note" role="note">
+<p class="note-title">Chart Structure</p>
 
 The chart structure mirrors your project's resources:
 
@@ -136,8 +136,8 @@ By default, `make build-installer` does not include samples in `dist/install.yam
 
 </aside>
 
-<aside class="note">
-<H1> Why CRDs are added under templates? </H1>
+<aside class="note" role="note">
+<p class="note-title"> Why CRDs are added under templates? </p>
 
 Although [Helm best practices](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#method-1-let-helm-do-it-for-you) recommend placing CRDs under a top-level `crds/` directory, the Kubebuilder Helm plugin intentionally places them under `templates/crd`.
 
@@ -357,8 +357,8 @@ The Makefile targets use sensible defaults extracted from your project configura
 | **--output-dir** string | Output directory for chart (default: `dist`)                                |
 | **--force**         | Regenerates preserved files except `Chart.yaml` (`values.yaml`, `NOTES.txt`, `_helpers.tpl`, `.helmignore`, `test-chart.yml`) |
 
-<aside class="note">
-<H1> Examples </H1>
+<aside class="note" role="note">
+<p class="note-title"> Examples </p>
 
 You can find example projects in [testdata/project-v4-with-plugins](https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/project-v4-with-plugins).
 
diff --git a/docs/book/src/plugins/available/kustomize-v2.md b/docs/book/src/plugins/available/kustomize-v2.md
index 929b96457ed..dc979d02c91 100644
--- a/docs/book/src/plugins/available/kustomize-v2.md
+++ b/docs/book/src/plugins/available/kustomize-v2.md
@@ -16,8 +16,8 @@ updates across multiple language plugins. This approach allows the
 creation of "helper" plugins that work with different projects
 and languages.
 
-<aside class="note">
-<h1>Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Examples</p>
 
 You can check the kustomize content by looking at the `config/` directory provided in the sample `project-v4-*`
 under the [testdata][testdata] directory of the Kubebuilder project.
@@ -72,8 +72,8 @@ The kustomize plugin implements the following subcommands:
 * create api (`$ kubebuilder create api [OPTIONS]`)
 * create webhook (`$ kubebuilder create api [OPTIONS]`)
 
-<aside class="note">
-<h1>Create API and Webhook</h1>
+<aside class="note" role="note">
+<p class="note-title">Create API and Webhook</p>
 
 The implementation for the `create api` subcommand scaffolds the kustomize
 manifests specific to each API. See more [here][kustomize-create-api].
diff --git a/docs/book/src/plugins/extending.md b/docs/book/src/plugins/extending.md
index fb5b5e75aea..fa67e1d10fa 100644
--- a/docs/book/src/plugins/extending.md
+++ b/docs/book/src/plugins/extending.md
@@ -15,8 +15,8 @@ Kubebuilder’s CLI can be extended through custom plugins, allowing you to:
 This flexibility enables you to create custom project
 setups tailored to specific needs.
 
-<aside class="note">
-<h1>Why use the Kubebuilder style?</h1>
+<aside class="note" role="note">
+<p class="note-title">Why use the Kubebuilder style?</p>
 
 Kubebuilder and SDK are both broadly adopted projects which leverage the [controller-runtime][controller-runtime] project. They both allow users to build solutions using the [Operator Pattern][operator-pattern] and follow common standards.
 
diff --git a/docs/book/src/plugins/extending/custom-markers.md b/docs/book/src/plugins/extending/custom-markers.md
index 69adfe02322..72dd5b70193 100644
--- a/docs/book/src/plugins/extending/custom-markers.md
+++ b/docs/book/src/plugins/extending/custom-markers.md
@@ -77,8 +77,8 @@ func formatPrefix(prefix string) string {
 }
 ```
 
-<aside class="note">
-<h1>Implementation Reference</h1>
+<aside class="note" role="note">
+<p class="note-title">Implementation Reference</p>
 
 The `formatPrefix` implementation shown above is adapted from Kubebuilder's internal
 [markerPrefix function](https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/machinery/marker.go).
diff --git a/docs/book/src/plugins/extending/external-plugins.md b/docs/book/src/plugins/extending/external-plugins.md
index 49126066620..bf226e9a1e1 100644
--- a/docs/book/src/plugins/extending/external-plugins.md
+++ b/docs/book/src/plugins/extending/external-plugins.md
@@ -106,7 +106,7 @@ structures.
 ```
 
 <aside>
-<H1> </H1>
+<p class="note-title"> </p>
 
 Avoid printing directly to `stdout` in your external plugin.
 Since communication between Kubebuilder and the plugin occurs through
@@ -139,8 +139,8 @@ External plugins can support the following Kubebuilder subcommands:
 - `metadata`: Provide plugin descriptions and examples with the `--help` flag.
 - `flags`: Inform Kubebuilder of supported flags, enabling early error detection.
 
-<aside class="note">
-<h1>More about `flags` subcommand</h1>
+<aside class="note" role="note">
+<p class="note-title">More about `flags` subcommand</p>
 
 The `flags` subcommand in an external plugin allows for early error detection by informing Kubebuilder about the flags the plugin supports. If an unsupported flag is identified, Kubebuilder can issue an error before the plugin is called to execute.
 If a plugin does not implement the `flags` subcommand, Kubebuilder will pass all flags to the plugin, making it the external plugin's responsibility to handle any invalid flags.
diff --git a/docs/book/src/plugins/kustomize-v2.md b/docs/book/src/plugins/kustomize-v2.md
index 03d0e6f3d56..96349266e60 100644
--- a/docs/book/src/plugins/kustomize-v2.md
+++ b/docs/book/src/plugins/kustomize-v2.md
@@ -10,8 +10,8 @@ what is scaffolded by default. With this approach we do not need to keep manuall
 which uses the same and we are also
 able to create "helper" plugins which can work with many projects and languages.
 
-<aside class="note">
-<h1>Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Examples</p>
 
 You can check the kustomize content by looking at the `config/` directory provide on the sample `project-v4-*` under the [testdata][testdata]
 directory of the Kubebuilder project.
@@ -80,8 +80,8 @@ The kustomize plugin implements the following subcommands:
 * create api (`$ kubebuilder create api [OPTIONS]`)
 * create webhook (`$ kubebuilder create api [OPTIONS]`)
 
-<aside class="note">
-<h1>Create API and Webhook</h1>
+<aside class="note" role="note">
+<p class="note-title">Create API and Webhook</p>
 
 Its implementation for the subcommand create api will scaffold the kustomize manifests
 which are specific for each API, see [here][kustomize-create-api]. The same applies
diff --git a/docs/book/src/plugins/plugins-versioning.md b/docs/book/src/plugins/plugins-versioning.md
index a0a34dada38..b474c1bb7a9 100644
--- a/docs/book/src/plugins/plugins-versioning.md
+++ b/docs/book/src/plugins/plugins-versioning.md
@@ -28,9 +28,9 @@ You must also add a migration guide to the [migrations][migrations]
 section of the Kubebuilder book in your PR. It should detail the steps required
 for users to upgrade their projects from `vX` to `v(X+1)-alpha`.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Example</h1>
+<p class="note-title">Example</p>
 
 Kubebuilder scaffolds projects with plugin `go.kubebuilder.io/v4` by default.
 
diff --git a/docs/book/src/quick-start.md b/docs/book/src/quick-start.md
index b1a2b47107d..f1495680542 100644
--- a/docs/book/src/quick-start.md
+++ b/docs/book/src/quick-start.md
@@ -14,8 +14,8 @@ This Quick Start guide will cover:
 - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) version v1.11.3+.
 - Access to a Kubernetes v1.11.3+ cluster.
 
-<aside class="note">
-<h1>Versions Compatibility and Supportability</h1>
+<aside class="note" role="note">
+<p class="note-title">Versions Compatibility and Supportability</p>
 
 Please, ensure that you see the [guidance](./versions_compatibility_supportability.md).
 
@@ -31,16 +31,16 @@ curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go
 chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/
 ```
 
-<aside class="note">
-<h1>Using the Master Branch</h1>
+<aside class="note" role="note">
+<p class="note-title">Using the Master Branch</p>
 
 You can work with the master branch by cloning the repository and running `make install` to generate the binary.
 Please follow the steps in the section **How to Build Kubebuilder Locally** from the [Contributing Guide](https://github.com/kubernetes-sigs/kubebuilder/blob/master/CONTRIBUTING.md#how-to-build-kubebuilder-locally).
 
 </aside>
 
-<aside class="note">
-<h1>Enabling shell autocompletion</h1>
+<aside class="note" role="note">
+<p class="note-title">Enabling shell autocompletion</p>
 
 Kubebuilder provides autocompletion support via the command `kubebuilder completion <bash|fish|powershell|zsh>`, which can save you a lot of typing. For further information see the [completion](./reference/completion.md) document.
 
@@ -56,8 +56,8 @@ cd ~/projects/guestbook
 kubebuilder init --domain my.domain --repo my.domain/guestbook
 ```
 
-<aside class="note">
-<h1>Developing in $GOPATH</h1>
+<aside class="note" role="note">
+<p class="note-title">Developing in $GOPATH</p>
 
 If your project is initialized within [`GOPATH`][GOPATH-golang-docs], the implicitly called `go mod init` will interpolate the module path for you.
 Otherwise `--repo=<module path>` must be set.
@@ -74,8 +74,8 @@ Run the following command to create a new API (group/version) as `webapp/v1` and
 kubebuilder create api --group webapp --version v1 --kind Guestbook
 ```
 
-<aside class="note">
-<h1>Press Options</h1>
+<aside class="note" role="note">
+<p class="note-title">Press Options</p>
 
 If you press `y` for Create Resource [y/n] and for Create Controller [y/n] then this will create the files `api/v1/guestbook_types.go` where the API is defined
 and the `internal/controller/guestbook_controller.go` where the reconciliation business logic is implemented for this Kind(CRD).
@@ -145,8 +145,8 @@ type Guestbook struct {
 </details>
 
 
-<aside class="note">
-<h1> `+kubebuilder` markers </h1>
+<aside class="note" role="note">
+<p class="note-title"> `+kubebuilder` markers </p>
 
 `+kubebuilder` are [markers][markers] processed by [controller-gen][controller-gen]
 to generate CRDs and RBAC. Kubebuilder also provides [scaffolding markers][scaffolding-markers]
@@ -160,8 +160,8 @@ You'll need a Kubernetes cluster to run against. You can use
 [KinD][kind] to get a local cluster for testing, or
 run against a remote cluster.
 
-<aside class="note">
-<h1>Context Used</h1>
+<aside class="note" role="note">
+<p class="note-title">Context Used</p>
 
 Your controller will automatically use the current context in your
 kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
@@ -228,8 +228,8 @@ Deploy the controller to the cluster with image specified by `IMG`:
 make deploy IMG=<some-registry>/<project-name>:tag
 ```
 
-<aside class="note">
-<h1>Registry Permission</h1>
+<aside class="note" role="note">
+<p class="note-title">Registry Permission</p>
 
 This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment.
 Make sure you have the proper permission to the registry if the above commands don't work.
@@ -245,7 +245,7 @@ kind load docker-image <your-image-name>:tag --name <your-kind-cluster-name>
 It is highly recommended to use [Kind][kind] for development purposes and CI.
 To know more, see: [Using Kind For Development Purposes and CI](./reference/kind.md)
 
-<h1>RBAC errors</h1>
+<p class="note-title">RBAC errors</p>
 
 If you encounter RBAC errors, you may need to grant yourself cluster-admin
 privileges or be logged in as admin. See [Prerequisites for using Kubernetes RBAC on GKE cluster v1.11.x and older][pre-rbc-gke] which may be your case.
@@ -272,8 +272,8 @@ make undeploy
 Kubebuilder design is based on [Plugins][plugins] and you can use
 [available plugins][available-plugins] to add optional features to your project.
 
-<aside class="note">
-<h1>References and Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">References and Examples</p>
 
 Use the [Deploy Image Plugin (deploy-image/v1-alpha)][deploy-image-v1-alpha] as a reference when creating your project. It follows Kubernetes conventions and recommended good practices. For example:
 
@@ -283,8 +283,8 @@ kubebuilder create api --group webapp --version v1alpha1 --kind Busybox --image=
 
 </aside>
 
-<aside class="note">
-<h1> Keeping your project up to date with ecosystem changes </h1>
+<aside class="note" role="note">
+<p class="note-title"> Keeping your project up to date with ecosystem changes </p>
 
 Use [AutoUpdate Plugin][autoupdate-v1-alpha] to keep your project
 aligned with the latest ecosystem changes. When a new release is available,
diff --git a/docs/book/src/reference/admission-webhook.md b/docs/book/src/reference/admission-webhook.md
index 222d49f7437..2891846f124 100644
--- a/docs/book/src/reference/admission-webhook.md
+++ b/docs/book/src/reference/admission-webhook.md
@@ -22,8 +22,8 @@ basic auth, bearer token, or a cert to authenticate itself to the webhooks.
 You can find detailed steps
 [here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#authenticate-apiservers).
 
-<aside class="note">
-<H1>Execution Order</H1>
+<aside class="note" role="note">
+<p class="note-title">Execution Order</p>
 
 **Validating webhooks run after all mutating webhooks**, so you don't need to worry about another webhook changing an
 object after your validation has accepted it.
@@ -53,8 +53,8 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob \
   --defaulting-path=/custom-mutate --validation-path=/custom-validate
 ```
 
-<aside class="note">
-<h1>Version Requirements</h1>
+<aside class="note" role="note">
+<p class="note-title">Version Requirements</p>
 
 Custom webhook paths require **controller-runtime v0.21+**. In earlier versions (< `v0.21`), the webhook path follows a
 fixed pattern based on the resource's group, version, and kind, and cannot be customized.
@@ -63,8 +63,8 @@ fixed pattern based on the resource's group, version, and kind, and cannot be cu
 
 ## Handling Resource Status in Admission Webhooks
 
-<aside class="warning">
-<H1>Modify status</H1>
+<aside class="warning" role="note">
+<p class="note-title">Modify status</p>
 
 **You cannot modify or default the status of a resource using a mutating admission webhook**.
 Set initial status in your controller when you first see a new object.
diff --git a/docs/book/src/reference/alpha_commands.md b/docs/book/src/reference/alpha_commands.md
index c1beec917a9..14a07dc8c2a 100644
--- a/docs/book/src/reference/alpha_commands.md
+++ b/docs/book/src/reference/alpha_commands.md
@@ -6,8 +6,8 @@ project migration and scaffold regeneration.
 These commands are designed to simplify tasks that were previously manual and error-prone
 by automating or partially automating the process.
 
-<aside class="warning">
-    <h3>Alpha commands are experimental</h3>
+<aside class="warning" role="note">
+    <p class="note-title">Alpha commands are experimental</p>
 
 Alpha commands are under active development and may change or be removed in future releases.
 They make local changes to your project and may delete files during execution.
diff --git a/docs/book/src/reference/artifacts.md b/docs/book/src/reference/artifacts.md
index 03ef63a9ba9..445465f866d 100644
--- a/docs/book/src/reference/artifacts.md
+++ b/docs/book/src/reference/artifacts.md
@@ -16,8 +16,8 @@ and you can find the list of available versions at: [envtest-releases.yaml](http
 When you run `make envtest` or `make test`, the necessary tarballs are downloaded and properly
 configured for your project.
 
-<aside class="note">
-<h1>Setup ENV TEST tool</h1>
+<aside class="note" role="note">
+<p class="note-title">Setup ENV TEST tool</p>
 
 To learn more about the tooling used to configure ENVTEST, which is utilized in the `setup-envtest`
 target in the Makefile of projects built with Kubebuilder, see the [README](https://github.com/kubernetes-sigs/controller-runtime/blob/main/tools/setup-envtest/README.md)
@@ -26,8 +26,8 @@ of its tooling. Additionally, you can find more information by reviewing the Kub
 </aside>
 
 
-<aside class="warning">
-    <h3>IMPORTANT: Action Required: Ensure that you no longer use https://storage.googleapis.com/kubebuilder-tools </h3>
+<aside class="warning" role="note">
+    <p class="note-title">IMPORTANT: Action Required: Ensure that you no longer use https://storage.googleapis.com/kubebuilder-tools </p>
 
 **Artifacts provided under [https://storage.googleapis.com/kubebuilder-tools](https://storage.googleapis.com/kubebuilder-tools) are deprecated and Kubebuilder maintainers are no longer able to support, build, or ensure the promotion of these artifacts.**
 
diff --git a/docs/book/src/reference/commands/alpha_generate.md b/docs/book/src/reference/commands/alpha_generate.md
index 46c79163d08..bd4f6cfa5de 100644
--- a/docs/book/src/reference/commands/alpha_generate.md
+++ b/docs/book/src/reference/commands/alpha_generate.md
@@ -12,8 +12,8 @@ in newer Kubebuilder releases.
 You may choose to re-scaffold the project in-place (overwriting existing files) or in a separate
 directory for diff-based inspection and manual integration.
 
-<aside class="warning">
-    <h3>Deletes files during scaffold regeneration</h3>
+<aside class="warning" role="note">
+    <p class="note-title">Deletes files during scaffold regeneration</p>
 When executed in-place, this command deletes all files except `.git` and `PROJECT`.
 
 Always back up your project or use version control before running this command.
@@ -38,8 +38,8 @@ It is also useful if your project was created with an older CLI version and does
 This approach allows you to compare changes between your current branch and upstream
 scaffold updates (e.g., from the main branch), and helps you overlay custom code atop the new scaffold.
 
-<aside class="note tip">
-<h1>Looking for a more automated migration?</h1>
+<aside class="note tip" role="note">
+<p class="note-title">Looking for a more automated migration?</p>
 
 If you want to upgrade your project scaffold with less manual work,
 try [`kubebuilder alpha update`](./alpha_update.md).
diff --git a/docs/book/src/reference/commands/alpha_update.md b/docs/book/src/reference/commands/alpha_update.md
index 0f602e0d855..5ec0347e203 100644
--- a/docs/book/src/reference/commands/alpha_update.md
+++ b/docs/book/src/reference/commands/alpha_update.md
@@ -9,8 +9,8 @@ not re-applying your code.
 By default, the final result is **squashed into a single commit** on a dedicated output branch.
 If you prefer to keep the full history (no squash), use `--show-commits`.
 
-<aside class="note">
-<H1> Automate this process </H1>
+<aside class="note" role="note">
+<p class="note-title"> Automate this process </p>
 
 You can reduce the burden of keeping your project up to date by using the
 [AutoUpdate Plugin][autoupdate-plugin] which
@@ -218,8 +218,8 @@ kubebuilder alpha update \
   --git-config rerere.enabled=true
 ```
 
-<aside class="warning">
-    <h3>You might need to upgrade your project first</h3>
+<aside class="warning" role="note">
+    <p class="note-title">You might need to upgrade your project first</p>
 
 This command uses `kubebuilder alpha generate` under the hood.
 We support projects created with <strong>v4.5.0+</strong>.
@@ -254,8 +254,8 @@ We use that value to pick the correct CLI for re-scaffolding.
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/J8zonID__8k?si=WC-FXOHX0mCjph71" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<aside class="note">
-<h1>About this demo</h1>
+<aside class="note" role="note">
+<p class="note-title">About this demo</p>
 
 This video was recorded with Kubebuilder release `v7.0.1`.
 Since then, the command has been improved,
diff --git a/docs/book/src/reference/completion.md b/docs/book/src/reference/completion.md
index 507474bc1f3..459be735d82 100644
--- a/docs/book/src/reference/completion.md
+++ b/docs/book/src/reference/completion.md
@@ -4,8 +4,8 @@ Note that sourcing the completion script in your shell enables Kubebuilder autoc
 
 ## Bash
 
-<aside class="note">
-<h1>Prerequisites for Bash</h1>
+<aside class="note" role="note">
+<p class="note-title">Prerequisites for Bash</p>
 
 The completion Bash script depends on [bash-completion](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed). Also, ensure that your Bash version is 4.1+.
 
diff --git a/docs/book/src/reference/controller-gen.md b/docs/book/src/reference/controller-gen.md
index 97225650ca3..ee290b80871 100644
--- a/docs/book/src/reference/controller-gen.md
+++ b/docs/book/src/reference/controller-gen.md
@@ -37,9 +37,9 @@ Output rules configure how a given generator outputs its results. There is
 always one global "fallback" output rule (specified as `output:<rule>`),
 plus per-generator overrides (specified as `output:<generator>:<rule>`).
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Default Rules</h1>
+<p class="note-title">Default Rules</p>
 
 When no fallback rule is specified manually, a set of default
 per-generator rules are used which result in YAML going to
diff --git a/docs/book/src/reference/crd-scope.md b/docs/book/src/reference/crd-scope.md
index 0f57139f115..8b8599b8577 100644
--- a/docs/book/src/reference/crd-scope.md
+++ b/docs/book/src/reference/crd-scope.md
@@ -2,8 +2,8 @@
 
 This document explains CustomResourceDefinition (CRD) scope in Kubernetes: how CRDs can be defined as namespace-scoped or cluster-scoped resources.
 
-<aside class="note">
-<h1>CRD Scope vs Manager Scope</h1>
+<aside class="note" role="note">
+<p class="note-title">CRD Scope vs Manager Scope</p>
 
 CRD scope is independent from manager scope. See [Understanding Scopes](./scopes.md) for an explanation of how these two concepts differ.
 </aside>
@@ -153,8 +153,8 @@ After updating markers, regenerate manifests:
 make manifests
 ```
 
-<aside class="warning">
-<h1>Scope Changes Are Breaking</h1>
+<aside class="warning" role="note">
+<p class="note-title">Scope Changes Are Breaking</p>
 
 Changing CRD scope from Namespaced to Cluster (or vice versa) is a **breaking change**:
 - Existing custom resources will become invalid
@@ -226,8 +226,8 @@ rules:
   verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
 ```
 
-<aside class="note">
-<h1>Important</h1>
+<aside class="note" role="note">
+<p class="note-title">Important</p>
 
 Even if your manager is namespace-scoped (watches only one namespace), if it manages cluster-scoped CRDs, it still needs `ClusterRole` permissions for those resources.
 
diff --git a/docs/book/src/reference/envtest.md b/docs/book/src/reference/envtest.md
index 757efd7ca6d..84a8ef00400 100644
--- a/docs/book/src/reference/envtest.md
+++ b/docs/book/src/reference/envtest.md
@@ -95,8 +95,8 @@ err = testEnv.Stop()
 
 Logs from the test runs are prefixed with `test-env`.
 
-<aside class="note">
-<h1>Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Examples</p>
 
 You can use the plugin [DeployImage](../plugins/available/deploy-image-plugin-v1-alpha.md) to check examples. This plugin allows users to scaffold API/Controllers to deploy and manage an Operand (image) on the cluster following the guidelines and best practices. It abstracts the complexities of achieving this goal while allowing users to customize the generated code.
 
@@ -159,8 +159,8 @@ var _ = AfterSuite(func() {
 })
 ```
 
-<aside class="note">
-<h1>ENV TEST Config Options</h1>
+<aside class="note" role="note">
+<p class="note-title">ENV TEST Config Options</p>
 
 You can look at the controller-runtime docs to know more about its configuration options, see [here](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest#Environment). On top of that, if you are
 looking to use ENV TEST to test your webhooks then you might want to give a look at its install [options](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest#WebhookInstallOptions).
@@ -201,9 +201,9 @@ expectedOwnerReference := v1.OwnerReference{
 Expect(deployment.ObjectMeta.OwnerReferences).To(ContainElement(expectedOwnerReference))
 ```
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h2>Namespace usage limitation</h2>
+<p class="note-title">Namespace usage limitation</p>
 
 EnvTest does not support namespace deletion. Deleting a namespace will seem to succeed, but the namespace will just be put in a Terminating state, and never actually be reclaimed. Trying to recreate the namespace will fail. This will cause your reconciler to continue reconciling any objects left behind, unless they are deleted.
 
@@ -342,8 +342,8 @@ testEnv = &envtest.Environment{
 }
 ```
 
-<aside class="note">
-<h1>Setup ENV TEST tool</h1>
+<aside class="note" role="note">
+<p class="note-title">Setup ENV TEST tool</p>
 To know more about the tooling used to configure ENVTEST which is used in the setup-envtest target in the Makefile
 of the projects build with Kubebuilder see the [README][readme]
 of its tooling.
diff --git a/docs/book/src/reference/good-practices.md b/docs/book/src/reference/good-practices.md
index 70b0e574632..2ef89fb6151 100644
--- a/docs/book/src/reference/good-practices.md
+++ b/docs/book/src/reference/good-practices.md
@@ -55,8 +55,8 @@ We recommend you manage your solutions using Status Conditionals following the [
 - **Observability**: Status conditions can be monitored and tracked by cluster administrators and external monitoring tools, enabling better visibility into the state of the custom resources managed by the Operator.
 - **Compatibility**: By adopting the common pattern of using conditions in Kubernetes APIs, Operator authors ensure their custom resources align with the broader ecosystem, which helps users to have a consistent experience when interacting with multiple Operators and resources in their clusters.
 
-<aside class="note">
-<h1> Example of Usage </h1>
+<aside class="note" role="note">
+<p class="note-title"> Example of Usage </p>
 
 Check out the [Deploy Image Plugin][deploy-image]. This plugin allows users to scaffold API/Controllers to deploy and manage an Operand (image) on the cluster following the guidelines and best practices. It abstracts the
 complexities of achieving this goal while allowing users to customize the generated code.
diff --git a/docs/book/src/reference/manager-scope.md b/docs/book/src/reference/manager-scope.md
index 6b172ff4faf..a09c80ac324 100644
--- a/docs/book/src/reference/manager-scope.md
+++ b/docs/book/src/reference/manager-scope.md
@@ -2,8 +2,8 @@
 
 Manager scope determines which namespace(s) your manager watches and manages resources in.
 
-<aside class="note">
-<h1>Manager Scope vs CRD Scope</h1>
+<aside class="note" role="note">
+<p class="note-title">Manager Scope vs CRD Scope</p>
 
 Manager scope is independent from CRD scope. See [Understanding Scopes](./scopes.md) for an explanation of how these two concepts differ.
 </aside>
@@ -137,17 +137,17 @@ kubectl apply -f dist/install.yaml
 
 The `setupCacheNamespaces` helper function automatically handles both single and multiple namespaces without conditional logic.
 
-<aside class="note">
-<h1>Example</h1>
+<aside class="note" role="note">
+<p class="note-title">Example</p>
 
 The `testdata/project-v4-with-plugins` in the Kubebuilder repository demonstrates a complete namespace-scoped manager configuration.
 
 See: [testdata/project-v4-with-plugins](https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/project-v4-with-plugins)
 </aside>
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Webhooks and Namespace-Scoped Mode</h1>
+<p class="note-title">Webhooks and Namespace-Scoped Mode</p>
 
 If your project has webhooks, the manager cache is restricted to `WATCH_NAMESPACE`, but webhooks receive requests from all namespaces by default.
 
diff --git a/docs/book/src/reference/markers.md b/docs/book/src/reference/markers.md
index 0520717b0f2..5424ab8d806 100644
--- a/docs/book/src/reference/markers.md
+++ b/docs/book/src/reference/markers.md
@@ -15,8 +15,8 @@ a marker name, optionally followed by some marker specific configuration:
 // +kubebuilder:printcolumn:JSONPath=".status.replicas",name=Replicas,type=string
 ```
 
-<aside class="note">
-<h1>difference between <code>// +optional</code> and <code>// +kubebuilder:validation:Optional</code></h1>
+<aside class="note" role="note">
+<p class="note-title">difference between <code>// +optional</code> and <code>// +kubebuilder:validation:Optional</code></p>
 
 Controller-gen supports both (see the output of `controller-gen crd -www`). `+kubebuilder:validation:Optional` and `+optional` can be applied to fields.
 
diff --git a/docs/book/src/reference/markers/crd-validation.md b/docs/book/src/reference/markers/crd-validation.md
index e9a890b9c79..edf57f43cb0 100644
--- a/docs/book/src/reference/markers/crd-validation.md
+++ b/docs/book/src/reference/markers/crd-validation.md
@@ -6,8 +6,8 @@ schema option.
 
 See [Generating CRDs](/reference/generating-crd.md) for examples.
 
-<aside class="note">
-<h1>Understanding Marker Grouping in Documentation</h1>
+<aside class="note" role="note">
+<p class="note-title">Understanding Marker Grouping in Documentation</p>
 
 Certain markers may seem duplicated. However, these markers are grouped based on their context of use
 — such as fields, types, or arrays. For instance, a marker like `+kubebuilder:validation:Enum` can be applied to
@@ -17,8 +17,8 @@ The grouping ensures clarity by showing how the same marker can be reused for di
 
 </aside>
 
-<aside class="note">
-<h1>Schema & Validation</h1>
+<aside class="note" role="note">
+<p class="note-title">Schema & Validation</p>
 
 Custom resources are validated using the generated OpenAPI v3 schema and must comply with Kubernetes structural schema rules.
 Only field types and constraints that can be represented in the CRD schema are enforced by the API server.
diff --git a/docs/book/src/reference/markers/scaffold.md b/docs/book/src/reference/markers/scaffold.md
index 2068a77b9d8..aab1b5485aa 100644
--- a/docs/book/src/reference/markers/scaffold.md
+++ b/docs/book/src/reference/markers/scaffold.md
@@ -5,8 +5,8 @@ files where additional code will be injected as new resources (such as controlle
 This enables Kubebuilder to seamlessly integrate newly generated components into the project without affecting
 user-defined code.
 
-<aside class="warning">
-    <h3>If you delete or change the `+kubebuilder:scaffold` markers</h3>
+<aside class="warning" role="note">
+    <p class="note-title">If you delete or change the `+kubebuilder:scaffold` markers</p>
 
 The Kubebuilder CLI specifically looks for these markers in expected
 files during code generation. If the marker is moved or removed, the CLI will
@@ -109,8 +109,8 @@ properly registered with the manager, so that the controller can reconcile the r
 | `+kubebuilder:scaffold:manifestskustomizesamples`                              | `config/samples`             | Marks where Kustomize sample manifests are injected.                            |
 | `+kubebuilder:scaffold:e2e-webhooks-checks`                                    | `test/e2e`                   | Adds e2e checks for webhooks depending on the types of webhooks scaffolded.      |
 | `+kubebuilder:scaffold:e2e-metrics-webhooks-readiness`                         | `test/e2e`                   | Adds readiness logic so metrics e2e tests wait for webhook service endpoints before creating pods. |
-<aside class="warning">
-    <h3> **(No longer supported)** `+kubebuilder:scaffold:crdkustomizecainjectionpatch` </h3>
+<aside class="warning" role="note">
+    <p class="note-title"> **(No longer supported)** `+kubebuilder:scaffold:crdkustomizecainjectionpatch` </p>
 
 If you find this marker in your code please:
 
@@ -164,8 +164,8 @@ For further guidance, you can refer to examples in the `testdata/` directory in
 
 </aside>
 
-<aside class="note">
-<h1>Creating Your Own Markers</h1>
+<aside class="note" role="note">
+<p class="note-title">Creating Your Own Markers</p>
 
 If you are using Kubebuilder as a library to create [your own plugins](./../../plugins/creating-plugins.md) and extend its CLI functionalities,
 you have the flexibility to define and use your own markers. To implement your own markers, refer to the [kubebuilder/v4/pkg/machinery](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/machinery),
diff --git a/docs/book/src/reference/metrics.md b/docs/book/src/reference/metrics.md
index a93e21f9c30..91a5d10ede9 100644
--- a/docs/book/src/reference/metrics.md
+++ b/docs/book/src/reference/metrics.md
@@ -4,8 +4,8 @@ By default, controller-runtime builds a global prometheus registry and
 publishes [a collection of performance metrics](/reference/metrics-reference.md) for each controller.
 
 
-<aside class="warning">
-    <h3>IMPORTANT: If you are using `kube-rbac-proxy`</h3>
+<aside class="warning" role="note">
+    <p class="note-title">IMPORTANT: If you are using `kube-rbac-proxy`</p>
 
 Please stop using the image `gcr.io/kubebuilder/kube-rbac-proxy` as soon as possible.
 Your projects will be affected and may fail to work if the image cannot be pulled.
@@ -73,8 +73,8 @@ config/rbac/metrics_reader_role.yaml
 
 This file contains the required RBAC rules to allow access to the metrics endpoint.
 
-<aside class="note">
-<H1>This ClusterRole is only a helper </H1>
+<aside class="note" role="note">
+<p class="note-title">This ClusterRole is only a helper </p>
 
 Kubebuilder **does not scaffold a RoleBinding or ClusterRoleBinding by default.**
 This is an intentional design choice to avoid:
@@ -112,8 +112,8 @@ subjects:
   namespace: system # Replace 'system' with your controller-manager's namespace
 ```
 
-<aside class="note">
-<H1>Why this is manual:</H1>
+<aside class="note" role="note">
+<p class="note-title">Why this is manual:</p>
 
 Kubebuilder avoids scaffolding RoleBindings by default because it might:
  - Bind to the wrong ServiceAccount
@@ -157,8 +157,8 @@ curl -v -k -H "Authorization: Bearer $TOKEN" \
   https://<project-name>-controller-manager-metrics-service.<project-name>-system.svc.cluster.local:8443/metrics
 ```
 
-<aside class="note">
-<H1>Notes</H1>
+<aside class="note" role="note">
+<p class="note-title">Notes</p>
 
 - Replace `<project-name>`, `<namespace>`, and `<service-account-name>` accordingly.
 - Ensure TLS is enabled and certificates are valid if not skipping verification (`-k`).
@@ -240,16 +240,16 @@ spec:
 
 ### **(Recommended)** Enabling certificates for Production (Disabled by default)
 
-<aside class="warning">
-<h1>Why Is This Not Enabled by Default?</h1>
+<aside class="warning" role="note">
+<p class="note-title">Why Is This Not Enabled by Default?</p>
 
 This option is not enabled by default because it introduces a dependency on CertManager.
 To keep the project as lightweight and beginner-friendly as possible, it is disabled by default.
 
 </aside>
 
-<aside class="warning">
-<h1>Recommended for Production</h1>
+<aside class="warning" role="note">
+<p class="note-title">Recommended for Production</p>
 
 The default scaffold in `cmd/main.go` uses a **controller-runtime feature** to
 automatically generate a self-signed certificate to secure the metrics server.
@@ -394,9 +394,9 @@ NAME                                         AGE
 monitor-controller-manager-metrics-monitor   2m8s
 ```
 
-<aside class="warning">
-<h2>If you are using Prometheus Operator ensure that you have the required
-permissions</h2>
+<aside class="warning" role="note">
+<p class="note-title">If you are using Prometheus Operator ensure that you have the required
+permissions</p>
 
 If you are using Prometheus Operator, be aware that, by default, its RBAC
 rules are only enabled for the `default` and `kube-system namespaces`. See its
@@ -455,8 +455,8 @@ func init() {
 You may then record metrics to those collectors from any part of your
 reconcile loop. These metrics can be evaluated from anywhere in the operator code.
 
-<aside class="note">
-<h1>Enabling metrics in Prometheus UI</h1>
+<aside class="note" role="note">
+<p class="note-title">Enabling metrics in Prometheus UI</p>
 
 In order to publish metrics and view them on the Prometheus UI, the Prometheus instance would have to be configured to select the Service Monitor instance based on its labels.
 
@@ -467,8 +467,8 @@ other openmetrics systems to scrape.
 
 ![Screen Shot 2021-06-14 at 10 15 59 AM](https://user-images.githubusercontent.com/37827279/121932262-8843cd80-ccf9-11eb-9c8e-98d0eda80169.png)
 
-<aside class="note">
-<h1>Controller-Runtime Auth/Authz Feature Current Known Limitations and Considerations</h1>
+<aside class="note" role="note">
+<p class="note-title">Controller-Runtime Auth/Authz Feature Current Known Limitations and Considerations</p>
 
 Some known limitations and considerations have been identified. The settings for `cache TTL`, `anonymous access`, and
 `timeouts` are currently hardcoded, which may lead to performance and security concerns due to the inability to
diff --git a/docs/book/src/reference/platform.md b/docs/book/src/reference/platform.md
index 9f2fddb3f21..b3d27a2e660 100644
--- a/docs/book/src/reference/platform.md
+++ b/docs/book/src/reference/platform.md
@@ -130,8 +130,8 @@ Template: corev1.PodTemplateSpec{
     },
 ```
 
-<aside class="note">
-<h1> Example(s) </h1>
+<aside class="note" role="note">
+<p class="note-title"> Example(s) </p>
 
 You can look for some code examples by checking the code which is generated via the Deploy
 Image plugin. ([More info](../plugins/available/deploy-image-plugin-v1-alpha.md))
@@ -176,8 +176,8 @@ Therefore, ensure that you uncomment the following code in the `config/manager/m
 #               - linux
 ```
 
-<aside class="note">
-<h1>Building images for releases</h1>
+<aside class="note" role="note">
+<p class="note-title">Building images for releases</p>
 
 You will probably want to automate the releases of your projects to ensure that the images are always built for the
 same platforms. Note that Goreleaser also supports [docker buildx][buildx]. See its [documentation][goreleaser-buildx] for more detail.
@@ -208,8 +208,8 @@ Note that when you run `make docker-build` OR `make docker-build IMG=myregistry/
 an image will be built from the client host (local environment) and produce an image for
 the client os/arch, which is commonly linux/amd64 or linux/arm64.
 
-<aside class="note">
-<h1>Mac Os</h1>
+<aside class="note" role="note">
+<p class="note-title">Mac Os</p>
 
 If you are running from an Mac Os environment then, Docker also will consider it as linux/$arch. Be aware that
 when, for example, is running Kind on a Mac OS operational system the nodes will
diff --git a/docs/book/src/reference/pprof-tutorial.md b/docs/book/src/reference/pprof-tutorial.md
index e4b4b2a0dfd..8c42c1cc408 100644
--- a/docs/book/src/reference/pprof-tutorial.md
+++ b/docs/book/src/reference/pprof-tutorial.md
@@ -2,8 +2,8 @@
 
 [Pprof][github], a Go profiling tool, helps identify performance bottlenecks in areas like CPU and memory usage. It's integrated with the controller-runtime library's HTTP server, enabling profiling via HTTP endpoints. You can visualize the data using go tool pprof. Since [Pprof][github] is built into controller-runtime, no separate installation is needed. [Manager options][manager-options-doc] make it easy to enable pprof and gather runtime metrics to optimize controller performance.
 
-<aside class="warning">
-    <h3>Not Recommended for Production</h3>
+<aside class="warning" role="note">
+    <p class="note-title">Not Recommended for Production</p>
 
 While [Pprof][github] is an excellent tool for profiling and debugging, it is not recommended to leave it enabled in production environments. The primary reasons are:
 
diff --git a/docs/book/src/reference/raising-events.md b/docs/book/src/reference/raising-events.md
index 91954d8e1a1..147b902aaf8 100644
--- a/docs/book/src/reference/raising-events.md
+++ b/docs/book/src/reference/raising-events.md
@@ -4,8 +4,8 @@ It is often useful to publish *Event* objects from the controller Reconcile func
 
  Recent Events for an object can be viewed by running `$ kubectl describe <resource kind> <resource name>`. Also, they can be checked by running `$ kubectl get events`.
 
-<aside class="warning">
-<h1>Events should be raised in certain circumstances only</h1>
+<aside class="warning" role="note">
+<p class="note-title">Events should be raised in certain circumstances only</p>
 
 Be aware that it is **not** recommended to emit Events for all operations. If authors raise too many events, it brings bad UX experiences for those consuming the solutions on the cluster, and they may find it difficult to filter an actionable event from the cluster. For more information, please take a look at the [Kubernetes APIs convention][Events].
 
@@ -28,8 +28,8 @@ Eventf(regarding, related runtime.Object, eventtype, reason, action, message str
 
 
 
-<aside class="note">
-<h1>Example Usage</h1>
+<aside class="note" role="note">
+<p class="note-title">Example Usage</p>
 
 Following is an example of a code implementation that raises an Event.
 
diff --git a/docs/book/src/reference/submodule-layouts.md b/docs/book/src/reference/submodule-layouts.md
index ed67b18a862..98744f36c87 100644
--- a/docs/book/src/reference/submodule-layouts.md
+++ b/docs/book/src/reference/submodule-layouts.md
@@ -4,8 +4,8 @@ This part describes how to modify a scaffolded project for use with multiple `go
 
 Sub-Module Layouts (in a way you could call them a special form of [Monorepo's][monorepo]) are a special use case and can help in scenarios that involve reuse of APIs without introducing indirect dependencies that should not be available in the project consuming the API externally.
 
-<aside class="note">
-<h1>Using External Resources/APIs</h1>
+<aside class="note" role="note">
+<p class="note-title">Using External Resources/APIs</p>
 
 If you are looking to do operations and reconcile via a controller a Type(CRD) which are owned by another project
 or By Kubernetes API then, please see [Using an external Resources/API](/reference/using_an_external_type.md)
@@ -29,8 +29,8 @@ They introduce however multiple caveats into typical projects which is one of th
 - There is always the possibility to extract your APIs into a new repository and arguably also have more control over the release process in a project spanning multiple repos relying on the same API types.
 - It requires at least one [replace directive][replace-directives] either through `go.work` which is at least 2 more files plus an environment variable for build environments without GO_WORK or through `go.mod` replace, which has to be manually dropped and added for every release.
 
-<aside class="warning">
-    <h3>Implications on Maintenance efforts</h3>
+<aside class="warning" role="note">
+    <p class="note-title">Implications on Maintenance efforts</p>
 
 When deciding to deviate from the standard kubebuilder `PROJECT` setup or the extended layouts offered by its plugins, it can result in increased maintenance overhead as there can be breaking changes in upstream that could break with the custom module structure described here.
 
@@ -133,8 +133,8 @@ go mod tidy
 Note that we used the placeholder version `v0.0.0` of the API Module. In case you already released your API module once,
 you can use the real version as well. However this will only work if the API Module is already available in the VCS.
 
-<aside class="warning">
-    <h3>Implications on controller releases</h3>
+<aside class="warning" role="note">
+    <p class="note-title">Implications on controller releases</p>
 
 Since the main `go.mod` file now has a replace directive, it is important to drop it again before releasing your controller module.
 To achieve this you can simply run
diff --git a/docs/book/src/reference/using_an_external_resource.md b/docs/book/src/reference/using_an_external_resource.md
index 9234999d664..16f98bff22b 100644
--- a/docs/book/src/reference/using_an_external_resource.md
+++ b/docs/book/src/reference/using_an_external_resource.md
@@ -31,8 +31,8 @@ For example, if you're managing Certificates from Cert Manager:
 kubebuilder create api --group certmanager --version v1 --kind Certificate --controller=true --resource=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 --external-api-domain=io
 ```
 
-<aside class="note">
-<h1>Pinning External API Versions</h1>
+<aside class="note" role="note">
+<p class="note-title">Pinning External API Versions</p>
 
 You can pin a specific version of the external API dependency using the `--external-api-module` flag:
 
diff --git a/docs/book/src/versions_compatibility_supportability.md b/docs/book/src/versions_compatibility_supportability.md
index b388da3e339..be6ab321104 100644
--- a/docs/book/src/versions_compatibility_supportability.md
+++ b/docs/book/src/versions_compatibility_supportability.md
@@ -33,8 +33,8 @@ Currently, Kubebuilder officially supports macOS and Linux platforms. If you are
 
 Contributions towards supporting Windows are not planned.
 
-<aside class="warning">
-    <h3>Project customizations</h3>
+<aside class="warning" role="note">
+    <p class="note-title">Project customizations</p>
 
 After using the CLI to create your project, you are free to customize how
 you see fit. Bear in mind, that it is not recommended to deviate from
diff --git a/docs/book/theme/css/markers.css b/docs/book/theme/css/markers.css
index 0a7ab272f7f..0ba91fae40d 100644
--- a/docs/book/theme/css/markers.css
+++ b/docs/book/theme/css/markers.css
@@ -325,33 +325,48 @@ details.collapse-code > summary::-webkit-details-marker {
     stroke: none;
 }
 
-/* notes */
-aside.note {
-    border: 1px solid var(--searchbar-border-color);
+/* notes - base styles for both info and warning */
+aside.note,
+aside.warning {
+    border: 1px solid var(--searchbar-border-color) !important;
+    border-left: 1px solid var(--searchbar-border-color) !important;
     border-radius: 3px;
     margin-top: 1em;
+    padding: 0 !important;
+    background: transparent !important;
 }
 
-aside.note > * {
+/* Hide mdBook's default callout icons that appear outside the box */
+aside.note::before,
+aside.warning::before {
+    display: none !important;
+    content: none !important;
+}
+
+aside.note > *,
+aside.warning > * {
     margin-left: 1em;
     margin-right: 1em;
 }
 
-/* note title */
-aside.note > h1 {
+/* note title - default styling (info/regular notes) */
+aside.note > .note-title,
+aside.warning > .note-title {
     border-bottom: 1px solid var(--searchbar-border-color);
-    margin: 0;
+    margin: 0 !important;
+    margin-left: 0 !important;
+    margin-right: 0 !important;
     padding: 0.5em 1em;
     font-size: 100%;
     font-weight: normal;
     background: var(--quote-bg);
 }
 
-/* warning notes */
-aside.note.warning > h1 {
+/* warning notes - orange styling with icon */
+aside.warning > .note-title {
     background: var(--warning-note-background-color, #fcf8f2);
 }
-aside.note.warning > h1::before {
+aside.warning > .note-title::before {
     /* TODO(directxman12): fill in these colors in theme.
      * If you're good with colors, feel free to play around with this
      * in dark mode. */
diff --git a/hack/docs/check.sh b/hack/docs/check.sh
index b41e41bfc67..858c52ff0d9 100755
--- a/hack/docs/check.sh
+++ b/hack/docs/check.sh
@@ -36,3 +36,8 @@ if [[ $(git status ${check_directory} --porcelain) ]]; then
 else
   echo "Generate Docs passed!"
 fi
+
+# Check documentation accessibility
+echo ""
+echo "Checking documentation accessibility..."
+$(dirname "$0")/../../test/check_docs_accessibility.sh
diff --git a/hack/docs/fix_note_accessibility.sh b/hack/docs/fix_note_accessibility.sh
new file mode 100755
index 00000000000..4d51775cf9b
--- /dev/null
+++ b/hack/docs/fix_note_accessibility.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+
+# Copyright 2026 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Fix accessibility issues in documentation notes.
+# This script:
+# 1. Adds role="note" to all <aside> elements
+# 2. Replaces <h1>, <h2>, <h3> tags inside <aside> with <p class="note-title">
+#
+# This maintains the exact same visual rendering while fixing the document
+# structure for screen readers and other assistive tools.
+
+set -euo pipefail
+
+docs_dir="docs/book/src"
+
+function fix_aside_role {
+  echo "Adding role=\"note\" to <aside> elements..."
+  local count=0
+
+  # Find all markdown files with aside elements
+  while IFS= read -r file; do
+    # Use perl for in-place editing (compatible with both GNU and BSD sed)
+    if perl -i -pe 's/<aside\s+class="([^"]+)"(?!\s+role=)>/<aside class="$1" role="note">/g' "$file"; then
+      count=$((count + 1))
+    fi
+  done < <(grep -rl '<aside' "$docs_dir" --include="*.md" || true)
+
+  echo "Updated $count files"
+}
+
+function fix_headings_in_aside {
+  echo "Replacing heading tags inside <aside> elements..."
+  local count=0
+
+  # Find all markdown files
+  while IFS= read -r file; do
+    local tmpfile
+    tmpfile=$(mktemp)
+    local inside_aside=0
+    local modified=0
+
+    while IFS= read -r line; do
+      # Check if we're entering an aside block
+      if echo "$line" | grep -q '<aside'; then
+        inside_aside=1
+        echo "$line" >> "$tmpfile"
+        continue
+      fi
+
+      # Check if we're exiting an aside block
+      if echo "$line" | grep -q '</aside>'; then
+        inside_aside=0
+        echo "$line" >> "$tmpfile"
+        continue
+      fi
+
+      # Replace heading tags if inside aside
+      if [ $inside_aside -eq 1 ]; then
+        # Handle inline headings (opening and closing on same line)
+        if echo "$line" | grep -iq '<h[123]>.*</h[123]>'; then
+          line=$(echo "$line" | sed -E 's|<[hH]([123])>(.*)</[hH][123]>|<p class="note-title">\2</p>|g')
+          modified=1
+        # Handle opening tags
+        elif echo "$line" | grep -iq '<h[123]>'; then
+          line=$(echo "$line" | sed -E 's|<[hH][123]>|<p class="note-title">|g')
+          modified=1
+        # Handle closing tags
+        elif echo "$line" | grep -iq '</h[123]>'; then
+          line=$(echo "$line" | sed -E 's|</[hH][123]>|</p>|g')
+          modified=1
+        fi
+      fi
+
+      echo "$line" >> "$tmpfile"
+    done < "$file"
+
+    if [ $modified -eq 1 ]; then
+      mv "$tmpfile" "$file"
+      count=$((count + 1))
+    else
+      rm "$tmpfile"
+    fi
+  done < <(find "$docs_dir" -name "*.md" -type f)
+
+  echo "Fixed $count files"
+}
+
+echo "Fixing documentation accessibility issues..."
+echo ""
+
+fix_aside_role
+echo ""
+fix_headings_in_aside
+echo ""
+echo "Done! Please run 'make test-docs-accessibility' to verify."
diff --git a/hack/docs/generate.sh b/hack/docs/generate.sh
index 91612c58e8f..42dc95c6cd7 100755
--- a/hack/docs/generate.sh
+++ b/hack/docs/generate.sh
@@ -25,4 +25,8 @@ chmod -R +w docs/book/src/getting-started/testdata/project/
 docs_gen_directory="$(dirname "$0")/../../hack/docs/generate_samples.go"
 go run ${docs_gen_directory}
 
+# Fix documentation accessibility after generating docs
+echo "Fixing documentation accessibility..."
+$(dirname "$0")/fix_note_accessibility.sh
+
 
diff --git a/test/check_docs_accessibility.sh b/test/check_docs_accessibility.sh
new file mode 100755
index 00000000000..fc1275bff30
--- /dev/null
+++ b/test/check_docs_accessibility.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+
+# Copyright 2026 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Validate accessibility of documentation notes.
+# This ensures that:
+# 1. All <aside> elements have role="note" for assistive tools
+# 2. No heading tags (h1, h2, h3) are used inside <aside> elements
+#    (they break the document outline for screen readers)
+
+function check_aside_role {
+  echo "Checking for <aside> elements without role=\"note\"..."
+  if grep -rn '<aside[^>]*class=' docs/book/src --include="*.md" | grep -v 'role="note"'; then
+    echo "ERROR: Found <aside> elements without role=\"note\""
+    echo "Please add role=\"note\" to all aside elements for accessibility."
+    return 1
+  fi
+  echo "All <aside> elements have role=\"note\""
+  return 0
+}
+
+function check_headings_in_aside {
+  echo "Checking for heading tags inside <aside> elements..."
+  local files_with_issues=()
+
+  # Find all markdown files and check for headings inside aside blocks
+  while IFS= read -r file; do
+    if awk '/<aside/,/<\/aside>/' "$file" | grep -iq '<h[123]>'; then
+      files_with_issues+=("$file")
+    fi
+  done < <(find docs/book/src -name "*.md" -type f)
+
+  if [ ${#files_with_issues[@]} -gt 0 ]; then
+    echo "ERROR: Found heading tags inside <aside> elements in the following files:"
+    printf '%s\n' "${files_with_issues[@]}"
+    echo ""
+    echo "Heading tags (h1, h2, h3) inside <aside> elements break the document outline"
+    echo "for assistive tools like screen readers. Please use <p class=\"note-title\"> instead."
+    echo ""
+    echo "To fix automatically, run:"
+    echo "  ./hack/docs/fix_note_accessibility.sh"
+    return 1
+  fi
+
+  echo "No heading tags found inside <aside> elements"
+  return 0
+}
+
+function validate_docs_accessibility {
+  local failed=0
+
+  check_aside_role || failed=1
+  echo ""
+  check_headings_in_aside || failed=1
+
+  if [ $failed -eq 1 ]; then
+    echo ""
+    echo "Documentation accessibility validation FAILED"
+    exit 1
+  else
+    echo ""
+    echo "Documentation accessibility validation PASSED"
+  fi
+}
+
+validate_docs_accessibility