Improve Lighthouse scores and add landing page benchmark

- Wrap blank template in rx.el.main landmark with page title/description
- Add aria_label/title to ColorModeIconButton and StickyBadge
- Add landing page prod benchmark alongside blank template test
- Document page structure and metadata best practices

Author: FarhanAliRaza

.github/workflows/performance.yml

@@ -67,6 +67,7 @@ jobs:
         env:
           REFLEX_RUN_LIGHTHOUSE: "1"
         run: |
+          mkdir -p .pytest-tmp/lighthouse
           uv run pytest tests/integration/test_lighthouse.py -q -s --tb=no --basetemp=.pytest-tmp/lighthouse
 
       - name: Upload Lighthouse artifacts

packages/reflex-base/src/reflex_base/.templates/apps/blank/code/blank.py

@@ -11,26 +11,37 @@ class State(rx.State):
 
 def index() -> rx.Component:
     # Welcome Page (Index)
-    return rx.container(
-        rx.color_mode.button(position="top-right"),
-        rx.vstack(
-            rx.heading("Welcome to Reflex!", size="9"),
-            rx.text(
-                "Get started by editing ",
-                rx.code(f"{config.app_name}/{config.app_name}.py"),
-                size="5",
+    return rx.el.main(
+        rx.container(
+            rx.color_mode.button(position="top-right"),
+            rx.vstack(
+                rx.heading("Welcome to Reflex!", size="9"),
+                rx.text(
+                    "Get started by editing ",
+                    rx.code(f"{config.app_name}/{config.app_name}.py"),
+                    size="5",
+                ),
+                rx.button(
+                    rx.link(
+                        "Check out our docs!",
+                        href="https://reflex.dev/docs/getting-started/introduction/",
+                        is_external=True,
+                        underline="none",
+                    ),
+                    as_child=True,
+                    high_contrast=True,
+                ),
+                spacing="5",
+                justify="center",
+                min_height="85vh",
             ),
-            rx.link(
-                rx.button("Check out our docs!"),
-                href="https://reflex.dev/docs/getting-started/introduction/",
-                is_external=True,
-            ),
-            spacing="5",
-            justify="center",
-            min_height="85vh",
         ),
     )
 
 
 app = rx.App()
-app.add_page(index)
+app.add_page(
+    index,
+    title="Welcome to Reflex",
+    description="A starter Reflex app.",
+)

packages/reflex-components-core/src/reflex_components_core/core/sticky.py

@@ -84,6 +84,8 @@ def create(cls):
             desktop_only(StickyLabel.create()),
             href="https://reflex.dev",
             target="_blank",
+            aria_label="Built with Reflex",
+            title="Built with Reflex",
             width="auto",
             padding="0.375rem",
             align="center",

packages/reflex-components-radix/src/reflex_components_radix/themes/color_mode.py

@@ -147,6 +147,8 @@ def create(
         props.setdefault("background", "transparent")
         props.setdefault("color", "inherit")
         props.setdefault("z_index", "20")
+        props.setdefault("aria_label", "Toggle color mode")
+        props.setdefault("title", "Toggle color mode")
         props.setdefault(":hover", {"cursor": "pointer"})
 
         if allow_system:

pyi_hashes.json

@@ -1,4 +1,6 @@
 {
+  "packages/reflex-components-core/src/reflex_components_core/core/sticky.pyi": "4b34eca0e7338ec80ac5985345717bc9",
+  "packages/reflex-components-radix/src/reflex_components_radix/themes/color_mode.pyi": "3a419f78071b0dd6be55dc55e7334a1b",
   "reflex/__init__.pyi": "5de3d4af8ea86e9755f622510b868196",
   "reflex/components/__init__.pyi": "f39a2af77f438fa243c58c965f19d42e",
   "reflex/experimental/memo.pyi": "c10cbc554fe2ffdb3a008b59bc503936"

reflex/docs/getting_started/project-structure.md

@@ -64,6 +64,8 @@ Initializing your project creates a directory with the same name as your app. Th
 
 Reflex generates a default app within the `{app_name}/{app_name}.py` file. You can modify this file to customize your app.
 
+The starter page also includes explicit page metadata. As you customize the app, update the page `title` and `description` in `app.add_page(...)` or `@rx.page(...)` so your production pages describe your project clearly.
+
 ## Python Project Files
 
 `pyproject.toml` defines your Python project metadata and dependencies. `uv add reflex` records the Reflex dependency there before you initialize the app.

reflex/docs/pages/overview.md

@@ -45,6 +45,26 @@ In this example we create three pages:
 # Video: Pages and URL Routes
 ```
 
+## Page Structure and Accessibility
+
+For better accessibility and Lighthouse scores, wrap your page content in an `rx.el.main` element. This provides the `<main>` HTML landmark that screen readers and search engines use to identify the primary content of the page.
+
+```python
+def index():
+    return rx.el.main(
+        navbar(),
+        rx.container(
+            rx.heading("Welcome"),
+            rx.text("Page content here."),
+        ),
+        footer(),
+    )
+```
+
+```md alert
+# Every page should have exactly one `<main>` landmark. Without it, accessibility tools like Lighthouse will flag the "Document does not have a main landmark" audit.
+```
+
 ## Page Decorator
 
 You can also use the `@rx.page` decorator to add a page.
@@ -207,6 +227,8 @@ You can add page metadata such as:
 {meta_data}
 ```
 
+For production apps, set `title` and `description` explicitly on each public page with `@rx.page(...)` or `app.add_page(...)`. Reflex will use what you provide there, so it is best to treat page metadata as part of the page definition rather than something to fill in later.
+
 ## Getting the Current Page
 
 You can access the current page from the `router` attribute in any state. See the [router docs](/docs/utility_methods/router_attributes) for all available attributes.

scripts/run_lighthouse.py

@@ -1,41 +1,72 @@
-"""Run the local Lighthouse benchmark with persistent caching."""
+"""Run the local Lighthouse benchmark with a fresh app build."""
 
 from __future__ import annotations
 
 import contextlib
 import io
+import shutil
+from collections.abc import Callable
 from pathlib import Path
 
 from tests.integration.lighthouse_utils import (
-    get_local_cached_app_root,
+    LIGHTHOUSE_APP_NAME,
+    LIGHTHOUSE_LANDING_APP_NAME,
+    LighthouseBenchmarkResult,
     run_blank_prod_lighthouse_benchmark,
+    run_landing_prod_lighthouse_benchmark,
 )
 
 
-def main() -> int:
-    """Run the Lighthouse benchmark and print a compact summary.
+def _run_benchmark(
+    run_fn: Callable[..., LighthouseBenchmarkResult],
+    app_root: Path,
+    report_path: Path,
+) -> LighthouseBenchmarkResult:
+    """Run a single benchmark, suppressing internal output.
 
     Returns:
-        The process exit code.
+        The benchmark result.
     """
-    app_root = get_local_cached_app_root()
-    report_path = Path(".states") / "lighthouse" / "blank-prod-lighthouse.json"
-
+    shutil.rmtree(app_root, ignore_errors=True)
     stdout_buffer = io.StringIO()
     stderr_buffer = io.StringIO()
     with (
         contextlib.redirect_stdout(stdout_buffer),
         contextlib.redirect_stderr(stderr_buffer),
     ):
-        result = run_blank_prod_lighthouse_benchmark(
-            app_root=app_root,
-            report_path=report_path,
-        )
-
-    print(result.summary)  # noqa: T201
-    if result.failures:
-        return 1
-    return 0
+        return run_fn(app_root=app_root, report_path=report_path)
+
+
+def main() -> int:
+    """Run the Lighthouse benchmarks and print compact summaries.
+
+    Returns:
+        The process exit code.
+    """
+    report_dir = Path(".states") / "lighthouse"
+    all_failures = []
+
+    benchmarks = [
+        (
+            LIGHTHOUSE_APP_NAME,
+            run_blank_prod_lighthouse_benchmark,
+            report_dir / "blank-prod-lighthouse.json",
+        ),
+        (
+            LIGHTHOUSE_LANDING_APP_NAME,
+            run_landing_prod_lighthouse_benchmark,
+            report_dir / "landing-prod-lighthouse.json",
+        ),
+    ]
+
+    for name, run_fn, report_path in benchmarks:
+        app_root = Path(".states") / name
+        result = _run_benchmark(run_fn, app_root, report_path)
+        print(result.summary)  # noqa: T201
+        print()  # noqa: T201
+        all_failures.extend(result.failures)
+
+    return 1 if all_failures else 0
 
 
 if __name__ == "__main__":