Skip to content

Bring the editorial marketing design to the docs site - #7137

Draft
Alek99 wants to merge 56 commits into
mainfrom
codex/docs-editorial-refresh
Draft

Alek99 wants to merge 56 commits into
mainfrom
codex/docs-editorial-refresh

Conversation

@Alek99

@Alek99 Alek99 commented Sep 14, 2026

Copy link
Copy Markdown
Member

Bring the documentation into the editorial design introduced in marketing PR #102, with consistent typography, neutral light/dark colors, restrained borders, and shared navigation and footer styling.

Changes

  • Refresh the docs landing page with separate Build with AI and Explore Framework entry points, interactive framework tabs and diagrams, a working counter example, and a unified cloud deployment illustration.
  • Add a Build with AI overview inside the docs sidebar. Recommend Reflex Build as the integrated workflow and offer Agent Toolkit for developers using Claude Code, Codex, or Cursor.
  • Restyle article navigation, breadcrumbs, component catalogs, API tables, dialogs, and both footer layouts. The component library uses a compact list with aligned headings and consistent link states.
  • Refine sidebar disclosures with smaller chevrons, tighter child rows, subtle hover backgrounds, and a soft active-page highlight. Keep the sidebar and navbar white in light mode. The Reflex Docs logo returns to /docs/.
  • Match footer social icons to the marketing site, remove the forum icon, and integrate newsletter signup into the footer layout.
  • Preserve meaningful colors in live examples, syntax highlighting, screenshots, and brand marks. Remove high_contrast from the introduction counter and correct invalid nesting in integration cards and the low-level form example.

The shared package exposes the visual system through SharedSiteStylesPlugin(editorial=True). Existing consumers can retain the default theme.

Validation

  • Production preview builds successfully.
  • Full pre-commit run --all-files and git diff --check pass.
  • Latest targeted browser checks pass for the docs-logo destination, sidebar disclosure and keyboard navigation, AI workflow destinations, and responsive light/dark sidebar styling.
  • The PR includes browser coverage for navigation, responsive layouts, forms, examples, framework tabs, footers, and hydration regressions. Desktop and mobile screenshots were reviewed during implementation.

The custom-component gallery's external data endpoint is not configured in the local preview, so populated gallery results were not visually verified. No external forms were submitted.

Type of change

  • New feature (non-breaking change)
  • Documentation update

Package news fragments are included.

@greptile-apps

greptile-apps Bot commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

The PR is not yet safe to merge because default-theme sidebar consumers still lose visible current-page and keyboard-focus treatments, and several explicit repository requirements remain unsatisfied.

Findings

  1. P1 Default sidebar states disappear
  2. P2 Primary alpha colors stay violet
  3. P2 Legacy text element used
  4. P2 News Fragment Is Too Long
  5. P2 Sort Identifiers Are Duplicated

Summary

The PR applies the editorial visual system to the documentation site, adds AI and framework landing experiences, and updates shared navigation, sidebar, footer, catalog, and theme infrastructure.

  • Introduces an opt-in editorial theme while retaining the shared package’s default mode.
  • Adds AI workflow pages, interactive framework content, illustrations, and refreshed documentation navigation.
  • Restyles documentation catalogs, examples, API controls, footers, dialogs, and responsive layouts.
  • Adds browser and unit coverage for the redesigned experiences.

Reviews (52) · Last reviewed commit: "Enclose the compact theme controls in a ..."

--primary-5: var(--c-slate-5);
--primary-6: var(--c-slate-6);
/* Internal inputs retain their flush focus treatment, using neutral ink. */
--primary-a6: var(--secondary-a6);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Primary alpha colors stay violet

The editorial theme changes the solid --primary-* colors to neutral slate, but only changes --primary-a6 in the alpha scale. Existing components still use the other violet alpha colors—for example, docs page actions combine neutral --primary-7 with violet --primary-a8 and use violet --primary-a3 and --primary-a4 backgrounds in dark mode. This leaves mismatched violet tints in the new neutral theme; please map the full primary alpha scale to matching neutral values.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@codspeed-hq

codspeed-hq Bot commented Sep 14, 2026

Copy link
Copy Markdown

Merging this PR will not alter performance

✅ 40 untouched benchmarks
⏩ 8 skipped benchmarks1


Comparing codex/docs-editorial-refresh (4a29f26) with main (2f63cb3)

Open in CodSpeed

Footnotes

  1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

Comment thread docs/app/reflex_docs/pages/docs/library.py Outdated
Comment thread docs/app/reflex_docs/pages/docs/library.py Outdated
Comment on lines 199 to 203
rx.text(
"pip install " + category["package_name"],
as_="p",
class_name="font-small truncate flex-1 min-w-0",
class_name="font-mono text-xs truncate flex-1 min-w-0",
),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Legacy text element used

The new install-command control renders its label with rx.text. The docs-app directive requires UI elements to use rx.el.* with Tailwind instead of legacy primitives such as rx.text, so this repository requirement must be satisfied before merging.

Suggested change
rx.text(
"pip install " + category["package_name"],
as_="p",
class_name="font-small truncate flex-1 min-w-0",
class_name="font-mono text-xs truncate flex-1 min-w-0",
),
rx.el.p(
"pip install " + category["package_name"],
class_name="font-mono text-xs truncate flex-1 min-w-0",
),

Context Used: docs/app/CLAUDE.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Comment on lines 133 to +144
rx.link(
rx.cond(
active,
rx.el.div(
class_name="absolute left-0 top-1/2 -translate-y-1/2 w-full h-8 rounded-lg bg-secondary-3 z-[-1]",
),
rx.fragment(),
),
rx.flex(
rx.cond(
active,
rx.el.div(
class_name="pointer-events-none absolute -bottom-1 -top-1 left-0 w-px bg-primary-10",
),
rx.fragment(),
),
rx.text(
title,
class_name=rx.cond(
active,
"m-0 pl-4 text-sm font-[525] text-primary-10 transition-color",
"m-0 w-full text-sm font-[525] text-secondary-11 transition-color hover:text-secondary-12",
),
),
class_name=rx.cond(
active,
f"relative {guide_margin_class} flex h-8 max-w-[14rem] items-center",
"relative flex h-8 items-center pl-4",
class_name="m-0 w-full text-sm",
),
class_name="relative flex items-center px-3",
),
href=href,
underline="none",
class_name=rx.cond(
active,
"relative block w-full",
f"block w-full {guide_margin_class}",
),
aria_current=rx.cond(active, "page", "false"),
class_name=f"docs-sidebar-leaf relative block {guide_margin_class}",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Default sidebar states disappear

The shared sidebar leaf now exposes its active state only through aria-current and classes whose visible active, hover, and focus treatments are defined in the opt-in editorial stylesheet. Consumers using the default non-editorial SharedSiteStylesPlugin therefore lose the visible current-page indicator and keyboard-focus treatment. Keep baseline state styling in the shared component or provide equivalent styling through the default theme.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant