Next React Fixing Patterns

Next / React Fixing Patterns

Reusable reference for AI agents working on UI code that must survive real project variability. The project may be a multi-theme product, a multilingual marketing site, a single-theme dashboard, a demo app, or a plain static site.

Use this skill as a pre-flight checklist before delivery, or as a diagnostic guide when visual bugs are reported.

Step 0 - Discover The Project Surface

Before changing code, inspect the project and identify which of these dimensions actually exist:

• Rendering/runtime: Next.js, React SPA, static HTML/CSS/JS, or another web stack
• Styling primitives: design tokens, CSS variables, utility classes, component variants, CSS modules, inline styles
• UI variants: themes, light/dark mode, brands, locales, density, RTL/LTR, card styles, feature flags
• Navigation model: SPA router, full-page navigation, modal flows, hash links
• Motion/media: canvas, particles, video, parallax, staggered transitions
• Demo-only behavior: intercepted links, fake forms, screenshot mode, mock data

Then choose only the applicable patterns below. Do not load irrelevant constraints into the active task.

Pattern 1 - Variant Consistency And State Architecture

Impact: Common failure mode. Agents implement the default visual state correctly and ignore the other supported states.

Symptoms

• Hardcoded colors, radii, fonts, or spacing that bypass the project's styling system
• One visual treatment reused across states that should differ
• Layout decisions tied to one theme, locale, or breakpoint only
• Variant logic duplicated inline across JSX, templates, or stylesheets

Fix Rules

1. Detect the project's variant mechanism first. It may be useTheme(), CSS variables, data attributes, server-provided config, component props, or a plain class switch.
2. Use the project's semantic styling layer when it exists. Prefer tokens, variables, named variants, or shared utility patterns over one-off literals.
3. Build variant maps only for states the product actually supports. Examples: theme, color mode, brand, locale, alignment mode, density, card style.
4. Centralize state-dependent decisions before markup when possible so the rendered structure stays readable.
5. If the project has no variant system, do not invent one just because the pattern mentions it. Keep the component simple and consistent with the existing codebase.
6. Two-pass workflow: after the first implementation, schedule a second pass for per-variant spacing, typography, and edge-case tuning. The first pass never catches everything.
7. Verify every supported state combination before delivery.

Examples

• React/Next project: useTheme(), context, or variant props may drive style choices.
• Static site: data-theme, lang, or page-level classes may drive style choices.
• Single-theme app: the correct outcome is often no new abstraction at all.

Pattern 2 - Responsive Design And Input Adaptation

Symptoms

• Layout fits desktop but breaks at the smallest supported viewport
• Buttons, chips, or nav items overflow narrow widths
• Hover interactions have no touch or keyboard equivalent
• Motion intensity is tuned for desktop only

Fix Rules

1. Start from the smallest supported viewport and scale up.
2. Use the project's existing responsive primitives: utility breakpoints, media queries, container queries, or layout helpers.
3. Provide touch and keyboard alternatives for essential hover-triggered behavior.
4. Scale motion, density, and content width by viewport when the UI uses heavy visual effects.
5. Prevent accidental text wrapping on controls only when that improves usability rather than causing overflow elsewhere.
6. Maintain semantic and ARIA parity across responsive variants — desktop and mobile versions of the same control must carry equivalent semantic state (see Pattern 12).

Pattern 3 - Contrast Across Supported Color Modes And Backgrounds

Symptoms

• Accent colors disappear on one mode or surface
• Status chips rely on opacity and become unreadable
• Text is legible on one page background but not another

Fix Rules

1. If the project supports multiple color modes or surface types, verify contrast in each supported mode and on each relevant background.
2. Build reusable color mappings for semantic states such as success, warning, error, and info when the project uses those states repeatedly.
3. Do not assume reduced opacity is a safe substitute for a proper alternate color.
4. If the project has only one mode, validate that mode thoroughly and skip mode-specific abstraction.

Pattern 4 - Typography Scaling And Content Resilience

Symptoms

• Display fonts overpower layouts at the same nominal size as body fonts
• Fixed-height text containers clip or overflow localized or scaled text
• Heading and body rhythm collapse when font sizes vary by theme or locale

Fix Rules

1. Detect whether the project has multiple font families, font scales, or locale-dependent text expansion.
2. Avoid fixed heights on text-heavy containers unless the design truly requires them and overflow behavior is explicitly handled.
3. Use scale-aware spacing and line-height rules when the project varies typography across themes, brands, or locales.
4. Test with longer strings when the project is localized or likely to be localized.
5. If the project uses one font system and one language, keep the typography model simple.

Pattern 5 - Layout Consistency, Equal Heights, And Alignment

Symptoms

• Cards in the same visual group end up with inconsistent heights
• Wrappers and inner containers fight each other, breaking stretch behavior
• Final row alignment looks accidental

Fix Rules

1. Apply stretch or equal-height rules to the full wrapper chain when the layout needs equal heights. The typical failure is fixing only one level — the fix must propagate from the outermost container through every intermediate wrapper to the innermost content.
2. Do not gate structural layout rules behind a theme or mode unless the layout itself genuinely changes by state.
3. Choose the grouping layout primitive that matches the behavior you need: grid for structure, flex for wrapping and centering, or an existing project abstraction.
4. If the design does not require equal heights, do not force them.

Pattern 6 - Performance And Motion Budget

Symptoms

• Motion-heavy sections feel janky on lower-end devices
• Decorative effects dominate interaction cost
• First-round performance reductions do not materially improve UX

Fix Rules

1. Start with conservative defaults for motion-heavy interfaces. If the first reduction is still slow, overshoot further rather than iterating incrementally — the first reduction is rarely sufficient.
2. Scale effect intensity by viewport, device capability, or project-specific performance controls when available.
3. Reduce count, blur, shadow, and animation overlap before adding more complexity.
4. Respect reduced-motion preferences when the project contains non-essential animation.

Pattern 7 - Dead Code And Incomplete Feature Removal

Symptoms

• A removed feature still exists in routes, translations, metadata, conditions, types, or assets
• UI appears gone but related behavior still leaks through the codebase

Fix Rules

Run a global search for all references. Check only the areas that exist in the project:

• Routes or navigation entries
• Translations or locale data
• SEO or metadata config
• Conditional logic and feature flags
• Type definitions or schemas
• CSS, utility classes, or style modules
• Asset files
• Build or config files
• Dependencies

Follow with a residual cleanup pass. The first removal rarely catches everything.

Pattern 8 - Design System And Brand Consistency

Fix Rules

1. Extract shared UI primitives when the same pattern appears repeatedly and the project already benefits from reuse.
2. When branding changes, update all affected surfaces in one pass: logo, metadata, SEO, localized copy, icons, or theme tokens as applicable.
3. Do not create a design system abstraction for a one-off component unless the project is clearly moving in that direction.

Pattern 9 - Framework And Runtime Boundaries

Symptoms

• Runtime crash caused by imports that belong to a different framework or router
• Component logic assumes APIs the current runtime does not provide

Fix Rules

1. Use framework-specific APIs only inside the framework that owns them.
2. When porting UI patterns, translate the dependency boundary as well as the visual markup.
3. Audit imports when mixing libraries or copying examples from other stacks.

SSR And Hydration Safety

When the project uses server-side rendering or static generation:

1. Preserve client-only rendering guards (deferred mounting, dynamic imports with SSR disabled). They are load-bearing — never remove them without understanding why they exist.
2. Do not use browser-only APIs (document, window, localStorage) in server code paths.
3. When porting UI across stacks, audit both imports and rendering assumptions — a component that works client-side may crash or produce mismatched markup when server-rendered.

Examples

• next/image, next/link, and next-themes belong in Next.js-aware codepaths.
• A Vite React SPA may need react-router-dom, plain <img>, or a custom theme context instead.
• A static site may need plain anchors, CSS variables, and no runtime theme hook at all.

Pattern 10 - Navigation, Testing, And UI Hygiene

Apply only the parts that match the project:

A. Navigation Reset

If the project is an SPA or app router, verify that navigating to a new route scrolls the viewport to the top. Implement a scroll-to-top handler on route change if one does not already exist.

B. Decorative Layers

All decorative overlays (dot patterns, gradient meshes, particle canvases) must have pointer-events-none or the equivalent so they never block interaction.

C. Visual Testing Mode

If the project uses visual regression testing or screenshot capture, provide a mode that forces all animations to their final state: set animation-duration and transition-duration to 0s, opacity to 1, and transform to none on all elements and pseudo-elements.

Pattern 11 - Demo And Showcase Behavior

If the project is a demo, template, or showcase rather than a live product:

1. Intercept actions that should not execute for real, such as tel:, mailto:, purchases, or destructive mutations.
2. Replace real effects with clear feedback.
3. Keep demo-specific wrappers synchronized with the active theme, locale, and routing model when those features exist.

Pattern 12 - Accessibility And Interaction Semantics

Impact: High. Incorrect ARIA is worse than no ARIA — it actively misleads assistive technology.

Symptoms

• Dropdown or popover uses role="menu" without full keyboard navigation (arrow keys, Home/End, typeahead)
• aria-controls points to an element that has been removed from the DOM by animation or conditional rendering
• Screen reader does not announce content that appears dynamically
• Desktop and mobile versions of the same control have different ARIA attributes
• Visual indicators (stars, status dots, icons) have no text alternative
• Buttons inside forms submit unexpectedly

Fix Rules

1. Default to disclosure semantics (aria-expanded + aria-controls) for dropdowns, popovers, and collapsible panels. Only use role="menu" when the full keyboard navigation contract is implemented.
2. Set aria-controls only when the referenced element exists in the DOM. If conditional rendering or animation removes the target, nullify the attribute.
3. Place aria-live on a persistent wrapper that is always in the DOM. If the region mounts together with its content, nothing is announced. Swap content inside the wrapper, not the wrapper itself.
4. Verify ARIA parity across responsive variants. Every semantic attribute on a desktop element must appear on its mobile or alternate-breakpoint counterpart.
5. Non-text indicators (icons, stars, status badges) that convey meaning must be exposed to assistive technology — via role="img" with aria-label, aria-labelledby, or visually hidden text. Purely decorative visuals and icons whose meaning is already conveyed by adjacent text must be hidden (aria-hidden="true" or equivalent).
6. Buttons inside forms default to type="submit". Every button that is not a submit trigger needs explicit type="button".
7. Escape-to-close is required for popovers, overlays, floating menus, and similar dismissible layers — not for plain disclosures like accordions or collapsible sections. Attach the keyboard listener only while the widget is open.
8. When the project is localized, all ARIA labels must come from the i18n system. Never hardcode fallback strings in a single language.

Pattern 13 - Internationalization And Localization Integrity

Apply this pattern when the project supports multiple locales or has an existing i18n system. Do not retrofit a translation mechanism into a single-language project just because this pattern exists.

Impact: Moderate individually, but errors compound — a single missed key causes runtime blanks or wrong-language text in production.

Symptoms

• Inline language conditionals (lang === 'x' ? ... : ...) instead of translation keys
• Adding a key to one locale but not others causes undefined rendering
• Translation strings contain {value} placeholders but call sites do not substitute them
• Cross-cutting UI strings (dismiss, close, skip-to-content) buried inside feature-specific translation namespaces
• Server-rendered or statically-built pages use client-side translation hooks that are unavailable at build time

Fix Rules

1. All user-facing strings must go through the project's existing translation mechanism. No inline language conditionals.
2. Locale data structures must maintain parity across all supported languages — identical keys, identical nesting. When a key is added or removed in one locale, update all others.
3. Every placeholder in a translation string ({value}, {count}, etc.) must have a matching substitution at every call site. Grep translation files for placeholders and verify each one.
4. Namespace translation keys by scope: nav.*, seo.*, ui.*, contact.*. Cross-cutting UI strings belong in a shared top-level namespace, not inside section-specific buckets.
5. Server-rendered or statically-built contexts must use the runtime-appropriate translation access pattern (direct imports, build-time resolution) instead of client-side hooks.

Pre-Delivery Checklist

YOU MUST verify all applicable items before declaring a UI component done.

Project Discovery

• Confirmed framework/runtime instead of assuming one
• Identified which state dimensions actually exist: theme, mode, locale, brand, density, feature flag, router state
• Identified the project's styling primitives and reused them

Variants And Styling

• No unnecessary abstraction added for unsupported variants
• State-dependent logic centralized where it improves clarity
• Hardcoded visual values avoided when shared tokens or variables already exist
• All supported theme/mode/locale combinations verified

Responsive And Interaction

• Tested at the smallest supported viewport
• Essential interactions work for mouse, touch, and keyboard
• Motion and density remain usable on smaller screens

Typography And Layout

• Text containers survive realistic content length
• Equal-height or stretch rules are correct when the design requires them
• Contrast holds on all supported surfaces and modes

Infrastructure And Hygiene

• Framework-specific imports match the actual runtime
• Client-only rendering guards intact when the project uses SSR
• No browser-only APIs in server code paths
• Decorative layers do not block interaction
• Removed features have no obvious residual references
• Demo or screenshot behavior is handled if the project needs it

Accessibility And ARIA Authoring

• Disclosure pattern (not menu) for dropdowns and popovers unless full keyboard nav is implemented
• aria-controls conditional on target element being in DOM
• aria-live on persistent wrapper, not conditionally mounted content
• ARIA attribute parity between desktop and mobile responsive variants
• Meaningful non-text indicators are exposed to assistive technology; decorative visuals are hidden
• Non-submit buttons inside forms have explicit type="button"
• Escape-to-close on popovers, overlays, and floating menus (not plain disclosures)
• ARIA labels from i18n system when the project is localized

Internationalization And Localization (when the project supports multiple locales)

• All user-facing strings come from the project's i18n system
• All locales have identical key structure
• Template placeholders have matching substitution at call sites
• Server or static contexts use appropriate translation access, not client-side hooks
• Cross-cutting UI strings in a shared namespace, not section-specific buckets