Rspress Custom Theme

Guide for customizing Rspress (v2) themes. Rspress offers four levels of customization, from lightest to heaviest. Always prefer the lightest approach that meets the requirement — lighter approaches are more maintainable and survive Rspress upgrades.

Workflow

1. Understand the user's goal — what do they want to change? (colors, layout, inject content, replace a component entirely?)
2. Pick the right level using the decision flow below
3. Set up theme/index.tsx if needed (Levels 1A, 3, 4 all need it)
4. Implement following the patterns in this skill and reference files
5. Verify the user's Rspress version is v2 (imports use @rspress/core/* not rspress/*)

Decision Flow