Skip to content

TheGoat395/Codex-Skills / skills/react-component-composition

react-component-composition

Verified

Define component boundaries, props and slots.

FileKindSize
SKILL.mdskill md726 B
agents/openai.yamlconfig288 B
references/react-component-composition-guide.mdmarkdown3.3 KB

references/react-component-composition-guide.md

View on GitHub
# React Component Composition Guide

## Purpose

Make React code feel designed and maintainable without flattening everything into generic components.

## Use When

- A React or Next.js page is large, repeated, or hard to scan.
- A website needs reusable sections, UI primitives, cards, media blocks, nav, forms, galleries, or product modules.
- The user wants a site that can be refined without rewriting a single giant file.

## Do Not Use When

- The change is a small one-line fix where extracting components adds noise.
- A local design system already dictates exact component structure.
- The project is not React and no React components are involved.

## Discovery Questions

- What is repeated because it is a true component versus repeated because the page needs varied composition?
- Which props describe content, state, variants, or behavior?
- Should this component be a primitive, section, or page-specific composition?
- Is the component server-rendered, client-interactive, or framework-neutral?

## Decision Tree

- Keep page files as composition maps when sections are complex.
- Extract primitives only when they reduce real duplication or clarify state.
- Use `children` or slots for flexible layout without prop explosions.
- Keep domain-specific components named by what they mean, not how they look.
- In Next.js, keep server/client boundaries in mind while composing.

## Implementation Rules

- Prefer clear component names over abstraction theater.
- Keep variants finite and visible; do not create a do-everything component.
- Let layout components own layout and content components own domain meaning.
- Keep visual polish in reusable primitives only when those primitives will actually repeat.
- Do not genericize away the unique site direction.

## Useful Patterns

- `HeroScene`, `ProofStrip`, `ProjectIndex`, `FeatureNarrative`, `EditorialMediaBand` for site-level sections.
- `Button`, `IconButton`, `TextLink`, `MediaFrame`, `Metric`, `Tag` for repeated primitives.
- Slot-based `SectionShell` only when spacing and heading behavior are truly consistent.

## Anti-Patterns

- Extracting every div into a component.
- Leaving a 900-line page because component splitting feels optional.
- Generic `Card` components used for every content type.
- Boolean prop overload such as `big`, `small`, `dark`, `fancy`, `special`.

## QA Checklist

- Read the page file: it should reveal the page story.
- Check component props for clarity and unused variants.
- Run type/lint/build checks.
- Verify visual output still has varied composition after extraction.

## Acceptance Criteria

- Components are reusable where helpful and specific where the design needs specificity.
- The code supports polish passes without turning into prop soup.
- The page remains visually non-generic.

## Shared scope

For applicable substantial web work, reuse the [shared scoped web contract](../../website-operating-rules/references/scoped-web-contract.md) when available. Preserve current authorization, stack and requested scope; this optional reference does not require another planning or approval cycle.

## Official Source Anchors

- React Learn: https://react.dev/learn
- React reference: https://react.dev/reference/react
- Server and Client Components: https://nextjs.org/docs/app/getting-started/server-and-client-components
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall