Repository navigation
perf: site-wide frontend overhaul — appearance system, reading experience, accessibility & i18n fixes - #24
Conversation
发布:dev 合入 master(XRobot Style 首页)
Replace snapshot transitions with CSS color fades, add visual option cards and an animation switch, and improve active navigation indicators and dark-mode logo visibility.
Refresh English UI, sidebar, and footer translations; show reading progress on English docs routes; use Mermaid's dark theme in dark mode.
Strip NUL bytes from generated HTML, improve dialog focus management, fix code fold aria controls, and report clipboard failures correctly.
Reviewer's GuideThis PR adds a persisted, SSR-safe appearance and accessibility layer across the Docusaurus site, including live accent/theme controls, reading aids, code folding, navigation and community surfaces, while hardening build output, clipboard feedback, localization, and type-checking without modifying docs content or default appearance. Sequence diagram for opening the accessible appearance panelsequenceDiagram
actor User
participant Navbar as NavbarItem
participant Host as AppearancePanelHost
participant Panel as AppearancePanel
User->>Navbar: click palette button
Navbar->>Host: dispatch xr-toggle-appearance-panel
Host->>Host: open panel and capture previous focus
Host->>Panel: render dialog
Host->>Panel: focus container
User->>Host: Tab or Shift+Tab
Host->>Host: cycle focus within dialog
User->>Host: press Escape or click outside
Host->>Host: close panel
Host->>Host: restore previous focus
Sequence diagram for persisted appearance initializationsequenceDiagram
participant Browser
participant Init as appearance-init.js
participant Storage as localStorage
participant CSS as xrstyle-appearance.css
participant Site as Docusaurus site
Browser->>Init: execute synchronously in head
Init->>Storage: read appearance preferences
Storage-->>Init: hue, font, decor, navbar, background, motion
Init->>CSS: set html data attributes and --xr-hue
CSS-->>Site: apply stored appearance before first paint
Site->>Site: hydrate AppearancePanel
Flow diagram for reading progress and back-to-top behaviorflowchart TD
Scroll[User scrolls] --> RAF[requestAnimationFrame throttle]
RAF --> Progress[updateProgress]
Progress --> Bar[Update top progress bar]
Progress --> Route{Docs route?}
Route -->|Yes| Circle[Update progress circle and aria-label]
Route -->|No| NoCircle[Keep circle hidden]
Progress --> Threshold{scrollY greater than 200?}
Threshold -->|Yes| Show[Show back-to-top button]
Threshold -->|No| Hide[Hide back-to-top button]
Show --> Click[User clicks Top]
Click --> ScrollTop[scrollToTop]
Flow diagram for long-code foldingflowchart TD
Code[CodeBlock] --> Count[Count lines during render]
Count --> Threshold{More than 15 lines?}
Threshold -->|No| Full[Render expanded code]
Threshold -->|Yes| Fold[Render 8-line collapsed preview]
Fold --> Expand[User activates Expand]
Expand --> Full
Full --> Collapse[User activates Collapse]
Collapse --> Fold
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
There was a problem hiding this comment.
Hey - I've found 9 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="package.json" line_range="8" />
<code_context>
"start": "docusaurus start",
- "prebuild": "node scripts/fetch-commits.js",
+ "prestart": "node scripts/copy-fonts.js",
+ "prebuild": "node scripts/fetch-commits.js && node scripts/copy-fonts.js",
"build": "docusaurus build",
"deploy": "docusaurus deploy",
</code_context>
<issue_to_address>
**Deploy skips build fixes**
When CI or a maintainer publishes with the standard `npm run deploy` command rather than deploying a separately prepared build, the standard `npm run deploy` command invokes `docusaurus deploy`, not `npm run build`, so npm does not run these `prebuild` and `postbuild` hooks; the published output retains the NUL characters and omits the ignored, copied font assets, leaving broken text/anchors and WenKai unavailable.
Make deployment run the hooked build and publish that output, or explicitly run font copying and NUL stripping on the build produced by the deploy path.
Also at `package.json:11`.
</issue_to_address>
### Comment 2
<location path="src/components/appearance/AppearancePanel.tsx" line_range="108" />
<code_context>
+ return (
+ <div
+ className={styles.panel}
+ role="dialog"
+ aria-label={translate({ id: 'appearance.panelTitle', message: '外观设置' })}>
+ {/* 1. 字体样式 */}
</code_context>
<issue_to_address>
**Background remains available**
When a screen-reader user opens the appearance panel, the dialog has no modal state, so assistive technology continues exposing page content behind the panel while it is open.
Add `aria-modal="true"` to the dialog.
</issue_to_address>
### Comment 3
<location path="src/components/appearance/AppearancePanelHost.tsx" line_range="51-53" />
<code_context>
+ const first = focusables[0];
+ const last = focusables[focusables.length - 1];
+ const current = document.activeElement as HTMLElement;
+ if (event.shiftKey && (current === first || !container.contains(current))) {
+ event.preventDefault();
+ last.focus();
+ } else if (!event.shiftKey && (current === last || !container.contains(current))) {
+ event.preventDefault();
</code_context>
<issue_to_address>
**Focus escapes open panel**
When a keyboard user presses Shift-Tab immediately after the panel opens, the host initially focuses the container, but the Tab handler treats it as an ordinary in-container focus target. Shift-Tab is not prevented and moves focus to the page behind the panel.
Treat the focused container as a reverse-Tab edge and move focus to the last control.
Also at `src/components/appearance/AppearancePanelHost.tsx:34`.
</issue_to_address>
### Comment 4
<location path="src/theme/NavbarItem/index.tsx" line_range="36" />
<code_context>
+ description: 'The aria-label of the appearance settings (palette) navbar button',
+ })}
+ onClick={() => {
+ if (mobileSidebar.shown) {
+ mobileSidebar.toggle();
+ }
</code_context>
<issue_to_address>
**Focus returns to detached trigger**
When the panel is opened from the mobile sidebar, `NavbarItem` closes the sidebar before the host records `document.activeElement`, so the trigger is unmounted and the host saves a stale or fallback target. Closing the panel then returns focus to the page instead of a usable navbar control.
Preserve a mounted focus-return target before closing the sidebar and restore focus to it when the panel closes.
Also at `src/components/appearance/AppearancePanelHost.tsx:31-34`, `src/components/appearance/AppearancePanelHost.tsx:75`.
</issue_to_address>
### Comment 5
<location path="src/utils/appearance.ts" line_range="68-79" />
<code_context>
+ * Write the accent state: pass a hue (0-360) for hue mode, null to go back to
+ * the mono accent (removes the storage key and sets data-accent="mono").
+ */
+export function writeAccentHue(hue: number | null): void {
+ if (hue === null) {
+ removeStorage(ACCENT_HUE_KEY);
+ } else {
+ writeStorage(ACCENT_HUE_KEY, String(hue));
+ }
+ const root = document.documentElement;
+ root.dataset.accent = hue === null ? 'mono' : 'hue';
</code_context>
<issue_to_address>
**Other tabs keep stale appearance**
When one tab changes a saved appearance preference while the site is open in multiple tabs, the other tab does not handle the storage change to update its root attributes or an open panel’s controls, so its rendered appearance and displayed settings remain stale.
Handle storage events by applying the changed preferences to the root attributes and refreshing the panel controls.
Also at `src/utils/motion.ts:24-32`, `src/components/appearance/AppearancePanel.tsx:42-54`.
</issue_to_address>
### Comment 6
<location path="src/utils/clipboard.ts" line_range="20-24" />
<code_context>
+ area.style.opacity = '0';
+ document.body.appendChild(area);
+ area.select();
+ const ok = document.execCommand('copy');
+ area.remove();
+ return ok;
+ } catch {
+ return false;
+ }
+}
</code_context>
<issue_to_address>
**Failed copies leave textareas**
When the legacy `execCommand` fallback throws after the textarea is appended, the catch path returns without calling `area.remove()`, leaving an invisible, focusable textarea in the document; repeated failures accumulate them.
Remove the textarea in a `finally` block so it is cleaned up whether the copy succeeds or throws.
</issue_to_address>
### Comment 7
<location path="src/components/appearance/AppearancePanel.module.css" line_range="18" />
<code_context>
+ border: 1px solid var(--line);
+ border-radius: var(--ifm-button-border-radius);
+ box-shadow: 0 12px 40px rgb(0 0 0 / 0.18);
+ animation: panel-in 0.2s ease;
+}
+
</code_context>
<issue_to_address>
**Motion preference is ignored**
When animations are disabled or reduced motion is active, the panel entrance and theme-toggle icon transitions still run because the motion-off rules do not cover these animations, so opening the panel or switching themes animates against the user’s preference.
Add motion-off and reduced-motion rules that disable the panel entrance and theme-toggle icon transitions.
Also at `src/theme/ColorModeToggle/index.module.css:28-30`.
</issue_to_address>
### Comment 8
<location path="static/appearance-init.js" line_range="27-36" />
<code_context>
+ var hue = read('xr-accent-hue');
+ if (hue !== null) {
+ var parsed = parseInt(hue, 10);
+ if (isNaN(parsed)) {
+ parsed = 0;
+ }
+ if (parsed < 0) {
+ parsed = 0;
+ }
+ if (parsed > 360) {
+ parsed = 360;
+ }
+ root.setAttribute('data-accent', 'hue');
+ root.style.setProperty('--xr-hue', String(parsed));
+ } else {
</code_context>
<issue_to_address>
**Hue setting disagrees with controls**
When localStorage contains a non-numeric value for `xr-accent-hue`, `appearance-init.js` coerces the value to `0` and enables hue mode, while `readAccentHue()` returns `null` and the panel displays mono mode. The page therefore renders a hue accent while the controls indicate mono.
Handle malformed stored hues consistently in the initializer and `readAccentHue()` so the rendered accent and selected control agree.
Also at `src/utils/appearance.ts:59-60`.
</issue_to_address>
### Comment 9
<location path="src/css/xrstyle-appearance.css" line_range="472-478" />
<code_context>
+}
+
+/* Blockquote: a 3px accent bar (round-cornered) on a sunken panel. */
+.markdown blockquote {
+ padding: var(--space-3) var(--space-4);
+ background-color: color-mix(in oklch, var(--paper-sunken) 60%, transparent);
+ border-left: 3px solid color-mix(in oklch, var(--xr-accent) 30%, transparent);
+ border-radius: 3px;
+}
+
+/* Tables: one outer frame, hairline row rules, no double borders. Infima's
+ * block display + overflow:auto stays, so wide tables still scroll inside
</code_context>
<issue_to_address>
**Default prose styling changes**
When a visitor uses the default appearance, the `.markdown` rules apply unconditionally, so blockquotes and other prose elements change even in the default appearance; the claimed identical default look is not preserved.
Either make the prose changes opt-in or revise the claim that the default appearance is identical.
</issue_to_address>Sourcery assessment
Needs a human reviewer. 9 findings to address first, and this changes site-wide runtime behavior and the production build output, including generated HTML, navigation, persisted appearance settings, and a newly packaged font dependency. A bad result could leave incorrect deployed pages or broken anchors until the site is rebuilt and redeployed; reverting the code and regenerating the build repairs it.
Blocking findings: package.json:8, src/components/appearance/AppearancePanel.tsx:108, src/components/appearance/AppearancePanelHost.tsx:53, src/theme/NavbarItem/index.tsx:36, src/utils/appearance.ts:79, and 4 more
- Remove the appearance panel (hue accent, rounded cards, auto-hiding frosted navbar, background textures, LXGW WenKai) together with its navbar item, init script, font dependency and translations; a small static/motion-init.js keeps applying the animation switch before paint. - Rename xrstyle-appearance.css to xrstyle-reading.css and keep the reading features (theme fade, reading progress, back-to-top, prose details, current-page indication, long-code folding) in ink with square corners; the sidebar's current item uses paper-sunken instead of a solid grey. - Theme fade, smooth scrolling and code-fold scrolling follow only the page animation switch, like the showcase widgets. - Home hero: drop the wavy underline; the contact tags stay coloured but sit straight, apart, without shadows. - Rewrite /qq in XRobot Style and crop the QR image to the code. - About: add @xiaoshuaijie (website UI, MSPM0); @molqzone keeps DAPLink.
3886487 to
713a1ae
Compare
…s tabs - Remove the temporary textarea in a finally block, so a throwing execCommand leaves nothing behind. - useReducedMotion listens for storage events on xr-motion and applies the value from another tab.
Overview
Systematic frontend overhaul built entirely on the existing XRobot ink token system (
--paper / --ink / --lineplus the new--xr-accentaccent channel). Thedocs/directory is untouched (no content, frontmatter, or URL changes), and the default appearance is identical to the current site — every new capability is an opt-in enhancement.37 files changed, +3958 / −105, in 5 commits: appearance system, community page & navigation, smooth theme switching, i18n & progress fixes, build-output & accessibility fixes.
New features
Appearance panel (palette icon in the navbar)
lxgw-wenkai-screen-webfont, loaded on demand — zero font requests in the default mode)<head>script (no FOUC); SSR output keeps the default appearanceLight/dark switch animation (incl. a performance fix)
prefers-reduced-motionis set or the animation switch is off; re-entrant clicks are guardedReading progress & back-to-top
/en/docs), rAF-throttled with progress / ring / aria-label kept in syncLong-code folding
aria-expanded / aria-controls(pointing at the actual code region) +aria-liveannouncements; unfolds for print; 59 blocks affected site-wideHomepage hero & /qq community page
/qqpage: group QR code, one-click group-number copy, a "Join via QQ" button, and an "Organization & projects" list (GitHub / Gitee / Docs / OneMessage / MiniShell / MiniFlashDB, all copyable)Current-page indication
Other polish
Bug fixes
scripts/strip-nul.jsonpostbuild; after stripping, all 7452 in-page anchors across the build resolve with 0 failuressrc/utils/clipboard.ts)aria-controlspointed at an always-hidden text copyhome.hero.tag.qq = "QQ Group"mermaid.theme.darkchanged fromforesttodarksidebar.docs.category.消息系统 = "Message System"filter: invert(1)in dark theme, matched by filename (build rewrites the path with a hash)custom-prefix@docusaurus/useLocationunresolvable@docusaurus/routerRingBuffer/sim.ts(no behavior change)i18n
i18n/en/code.json: ~30 new keys (appearance panel / hero tags / /qq page / code folding / back-to-top)write-translations(24 categories); footer QQ Group keys corrected and a stale key removed/en/docsroutesNew dependencies
lxgw-wenkai-screen-webfont(runtime; copied tostatic/fonts/lxgw/byscripts/copy-fonts.jsduring build/start, gitignored — zero font requests in the default mode)typescript,@types/react,@types/react-dom(type-checking only, build pipeline unchanged)Testing
npm run build(including the postbuild NUL strip) andtsc --noEmitpass with zero errorsdocs/directory confirmed untouched (git)Upgrade notes
prebuild) and the NUL strip (postbuild); new dependencies require network accessSummary by Sourcery
Modernize the frontend with an opt-in appearance and reading experience while improving accessibility, internationalization, build output integrity, and community navigation.
New Features:
Bug Fixes:
Enhancements:
Build:
Documentation:
Tests: