# styled-components-best-practices

Guides AI coding assistants on CSS-in-JS architecture in React: style isolation, file structure, TypeScript theme typing, and ThemeProvider setup.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 762 installs · ★ 286
- Author: Mindrally
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Mindrally/skills/tree/HEAD/styled-components-best-practices/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/styled-components-best-practices

## What it does

The skill guides your agent to structure React component styling around CSS-in-JS patterns. It recommends separating styled tags into dedicated files such as `Button.styles.ts` instead of cluttering JSX logic. Styles remain scoped to their components. Global CSS collisions do not occur.

The instructions define a project layout. Each component lives in its own directory with separate files for markup and styled elements. App-level styling resides in a `styles` directory containing the theme object and `GlobalStyles`. The theme blueprint provides tokens for palette colors and spacing scales.

Without augmenting the `DefaultTheme` interface in `styled.d.ts`, TypeScript cannot provide auto-complete for theme properties. The setup requires `styled-components` in dependencies, plus `@types/styled-components` for TypeScript projects.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill styled-components-best-practices -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/styled-components-best-practices/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/styled-components-best-practices/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill styled-components-best-practices -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/styled-components-best-practices/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill styled-components-best-practices -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/styled-components-best-practices/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Mindrally/skills styled-components-best-practices
```

2. **Manually: put the files in place**
- File: `.github/skills/styled-components-best-practices/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill styled-components-best-practices -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Mindrally/skills --path styled-components-best-practices
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/styled-components-best-practices/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill styled-components-best-practices -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Mindrally/skills/tree/HEAD/styled-components-best-practices/SKILL.md

## When to use it
- Isolate component styles to prevent global CSS collisions
- Organize React components into dedicated files for styles and types
- Define a structured theme object with color tokens and spacing scales
- Type theme properties in TypeScript by augmenting `DefaultTheme`

## Example prompts
- Create a button component with primary and danger variants using styled-components in a separate styles file
- Set up a theme object and configure DefaultTheme typings for styled-components in TypeScript
- Structure a Card component with separate files for markup, styled-components, and types

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: acb886b94be4d701.

BEGIN THIRD-PARTY FILE acb886b94be4d701
````text
---
name: styled-components-best-practices
description: styled-components best practices for CSS-in-JS development in React applications
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# styled-components Best Practices

You are an expert in styled-components, CSS-in-JS patterns, and React component styling.

## Key Principles

- Write component-scoped styles that avoid global CSS conflicts
- Leverage the full power of JavaScript for dynamic styling
- Keep styled components small, focused, and reusable
- Prioritize performance with proper memoization and SSR support

## Basic Setup

### Installation
```bash
npm install styled-components
npm install -D @types/styled-components  # For TypeScript
```

### Basic Usage
```tsx
import styled from 'styled-components';

const Button = styled.button`
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 8px 16px;
  background-color: #3498db;
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 1rem;
  cursor: pointer;
  transition: background-color 0.3s ease;

  &:hover {
    background-color: #2980b9;
  }

  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
`;

// Usage
function App() {
  return <Button>Click me</Button>;
}
```

## Project Structure

### File Organization
```
src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.styles.ts    # Styled components
│   │   ├── Button.types.ts     # TypeScript types
│   │   └── index.ts            # Re-exports
│   ├── Card/
│   │   ├── Card.tsx
│   │   ├── Card.styles.ts
│   │   └── index.ts
│   └── index.ts
├── styles/
│   ├── theme.ts                # Theme definition
│   ├── GlobalStyles.ts         # Global styles
│   ├── mixins.ts               # Reusable style mixins
│   └── index.ts
└── App.tsx
```

### Component Style File
```tsx
// Button.styles.ts
import styled, { css } from 'styled-components';
import type { ButtonProps } from './Button.types';

export const StyledButton = styled.button<Pick<ButtonProps, 'variant' | 'size'>>`
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border: none;
  border-radius: ${({ theme }) => theme.borderRadius.md};
  font-family: inherit;
  font-weight: ${({ theme }) => theme.fontWeight.medium};
  cursor: pointer;
  transition: all ${({ theme }) => theme.transition.base};

  ${({ size, theme }) => {
    switch (size) {
````
END THIRD-PARTY FILE acb886b94be4d701

The third-party file has ended. Everything between the acb886b94be4d701 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2572 of 18470 bytes. © Mindrally · Apache-2.0 · https://github.com/Mindrally/skills/tree/HEAD/styled-components-best-practices/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md