Drupal cache contexts describe the situations that make cached output vary. Theme planning should identify those variations before components are built, especially for navigation, account-aware blocks, language switches, and permission-sensitive page chrome.
Start With What Can Change For The Same Component
A Drupal theme can look inconsistent because the CSS is weak, but it can also look inconsistent because the team has not named the cached variants the theme must support. Cache contexts are Drupal’s way of saying that the same rendered element may need different versions depending on route, language, user, permissions, or another runtime condition.
Separate Styling Variation From Cache Variation
Theme planning should start by asking what can legitimately change. A menu item that highlights on one route is not the same problem as a price block that changes by user role. The first is usually route-aware presentation. The second may be permission or user-context output that needs a stronger conversation with the module or site-building layer.
Map Route And Language Before Twig Cleanup
A common mistake is treating all variation as a Twig cleanup task. If a language switcher, breadcrumb, local task, or account menu changes because Drupal is serving different cached render arrays, the theme cannot solve the problem by renaming classes alone. It needs acceptance criteria that say which contexts are expected and how each variant should be reviewed.
Treat User And Permission Differences As Product Requirements
User and permission differences deserve early product language. “Anonymous visitors see a sign-in link, authenticated editors see workflow links, and administrators see cache-clear tools” is a theme requirement, not a last-minute surprise. Once the team says it out loud, designers can provide states and developers can test the cached output without guessing.
A Header Planning Walkthrough For Cached Variants
For a header component, map the route highlight, active language, logged-in state, editor toolbar interaction, and responsive navigation state. Then decide which differences are Drupal-rendered variants and which are client-side interaction states. That distinction prevents a review from mixing cache correctness with ordinary CSS behavior.
| Component question | Likely context | Theme planning consequence |
|---|---|---|
| Does the output change by page path? | Route or URL context | Include active and inactive route screenshots |
| Does it change by role or login state? | User or permission context | Review anonymous, editor, and admin variants separately |
| Does language change labels or direction? | Language context | Plan translated labels, spacing, and direction-sensitive styling |
Use Core Documentation To Ground The Conversation
Drupal’s own cache contexts documentation explains the concept and common contexts. The Render API cacheability documentation is the companion reference when the question moves from theme review into render arrays and metadata.
Turn The Cache Map Into Theme Acceptance Criteria
The practical output is a cache-aware theme checklist for each shared component: routes to inspect, languages to compare, roles to test, and expected differences to screenshot. That sits naturally beside Layout Builder vs Paragraphs in Drupal when the team is deciding how much variation belongs in content modeling versus page presentation.
Worked Application For A Role-Aware Header
Worked application: take a Drupal header that shows a public navigation menu, a language switcher, and an editor shortcut when the user can edit content. The theme review should not ask for one screenshot called “the header.” It should ask for anonymous English, anonymous second language, authenticated editor, and administrator states on a content page and on a landing page. If the editor shortcut disappears for anonymous users, that is expected. If the active route styling disappears only after login, the team has a cache or render metadata question rather than a pure CSS issue.
That walkthrough gives the designer, Drupal developer, and QA reviewer the same vocabulary. Styling differences, role differences, route differences, and language differences become named variants. The team can then decide whether the component needs a template adjustment, a render-array cacheability fix, or simply clearer acceptance criteria. It also prevents performance fixes from being judged by the wrong screenshot, which is where many theme reviews lose time.