docs agent failed: overwrote custom css in docusaurus theme

TL;DR

Restore the overwritten CSS from git, then put custom styles only in src/css/custom.css and use swizzling for component changes, never edits inside the theme package. The agent broke styling because it edited generated theme files instead of the sanctioned customization points. Restore, then fence the agent to the right files.

docs agent failed: overwrote custom css in docusaurus theme

Steps

1. Confirm what was overwritten: run git diff --stat and git status --short after the agent run, looking at src/css and any theme files. Expected: a concrete list of style files the agent changed.
2. Restore the custom styles: git checkout -- src/css/custom.css (and any other style files you own). If the agent committed, revert that commit's style changes. Expected: git diff on your style files is empty and the site looks right again on a local build.
3. Move customizations to the sanctioned spots: plain style overrides go in src/css/custom.css, for example:

:root {
  --ifm-color-primary: #2e8555;
}

Component-level changes go through swizzling, which scaffolds an ejectable copy under src/theme that survives upgrades. Expected: the production build succeeds and your styles apply.

4. Fence the agent: it may write src/css/custom.css and files under src/theme, and must never touch theme files inside node_modules or the build output directory. Expected: a dry run of the agent's style task lists only allowed paths.
5. Rebuild and visually check: run the production build and confirm the custom styling is present. Expected: the built site shows your styles, not the theme defaults.

Use this when

• custom Docusaurus styles vanish after an agent run
• the site renders unstyled or with default theme colors after docs automation
• an agent edited files inside the theme package

Not for this skill when

• styles never worked in the first place (CSS or config bug, not an overwrite)
• a human edited the theme files directly (same fix applies, but no agent fence needed)
• the build fails on valid CSS (builder problem)

Variant phrasings

• agent wiped my docusaurus custom css
• docusaurus styles lost after docs agent run
• theme css overwritten by automation

Why it happens

Docusaurus themes ship their CSS inside the installed package, and the sanctioned override points (custom.css, swizzled components) are a convention, not a lock. An agent told to "update the styles" edits the first CSS it finds, which is the theme's own files, so the next install or build wipes or conflicts with its edits.

Edge cases

• A package reinstall wipes node_modules edits silently: that is why overrides must live in src/, never in the package.
• Swizzled components can go stale across major Docusaurus upgrades: re-swizzle and re-apply after upgrading.
• CSS variable names change between theme versions: check the variable still exists after an upgrade.
• If the agent also changed the docusaurus config stylesheets, review that diff too.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gwXht0-imJeD3aPAZLskcg