Overview

This skill analyzes styled-jsx usage to identify scoping leaks, overbroad :global usage, unsafe interpolations, and maintainability gaps. It surfaces findings with severity, and proposes minimal-refactor plans plus necessary test/story updates.

How This Skill Works

Using Read, Grep, and Glob, the audit scans components for global styles, excessive :global selectors, and deep descendant selectors. It flags unsafe interpolations, missing focus-visible states, brittle DOM-driven styling, and missing className pass-through, then outputs findings, severity, and a minimal-refactor plan along with test/story update guidance.

When to Use It

• Auditing a codebase with styled-jsx to detect scope leaks and global style bleed
• Reviewing PRs that touch CSS to surface unsafe interpolations or brittle selectors
• Before merging changes that tighten styling scope or refactor components
• During accessibility reviews to ensure focus-visible states exist on interactive controls
• While migrating away from brittle DOM-based styling toward safer, maintainable patterns

Quick Start

1. Step 1: Run the styled-jsx audit on the target path or component (path or ComponentName)
2. Step 2: Review findings by severity and identify high-risk areas (global usage, deep selectors, unsafe interpolations)
3. Step 3: Apply minimal refactors (scoped selectors, safer interpolations, proper focus styles) and update tests/stories

Best Practices

• Prefer tightly scoped selectors and minimize use of :global to prevent leaks
• Avoid deep descendant selectors; introduce explicit component-level classes as anchors
• Validate CSS interpolations to prevent unsafe or user-driven CSS injection
• Ensure interactive controls have focus-visible styles and accessible focus indicators
• Forward className props when wrapping or extending components to preserve styling

Example Use Cases

• Example: A button styled with :global(.btn) leaks into unrelated components; fix by scoping with component-level classes or styled-jsx blocks
• Example: Deep selectors like .card .header .title increase fragility; fix by adding a top-level class and reducing depth
• Example: Interpolating user data into a CSS string (e.g., ${dynamic} in a style tag); fix by sanitizing inputs or using CSS variables
• Example: Interactive controls lack focus-visible states; fix by adding :focus-visible and keyboard-accessible styles
• Example: Missing className pass-through in wrapper components causes styles to break; fix by forwarding className to the root element

Frequently Asked Questions