React Bits Design

Overview

Connect design decisions to implementation: lock a design system first, select React Bits components by semantic fit, then audit evidence and repair only the failing region. Do not substitute accumulated animation for art direction.

Load Resources by Task

• Read references/design-systems.md before choosing a visual family, creating DESIGN.md, or remixing brands.
• Read references/react-bits.md before searching, installing, or integrating a component.
• Read references/quality-gate.md before reviewing or delivering a UI.
• Copy assets/DESIGN.template.md when creating a design system from scratch.
• Resolve all relative resource paths from this skill directory.

Workflow

1. Inspect the Existing Project

Identify the framework, package manager, TypeScript usage, styling approach, existing tokens, component conventions, and available build/test commands. Preserve the project stack unless the user requests migration. Read existing DESIGN.md, theme files, and CSS variables before inventing tokens.

Skip style-selection questions for a narrow component request. For a full visual redesign with no established direction, ask only the missing questions from the family picker in references/design-systems.md; do not repeat answers already present in context.

2. Lock the Design Source

Choose one primary aesthetic family and one memorable differentiator. Create or update DESIGN.md with all nine canonical sections when the task needs a reusable design system.

Treat the existing project tokens and explicit DESIGN.md as the source of truth for color, type, spacing, radius, and component styling. Apply generic anti-slop rules only where they do not contradict that source. Mark inferred values as inferred and unknown fonts as unknown.

3. Select Components Semantically

Translate the design intent into concise English search terms before calling the catalog tool. Prefer components by user goal: content reveal, navigation, data display, input feedback, background atmosphere, or decorative spectacle.

python3 scripts/react_bits.py search "split text" --category "Text Animations" --limit 5
python3 scripts/react_bits.py search "navigation menu" --limit 5
python3 scripts/react_bits.py info SplitText --variant TS-TW

Do not invent component names or variants. Do not select several heavy WebGL, cursor, or background effects merely because they are available. Choose one primary motion idea and make secondary motion subordinate.

4. Detect, Preview, and Install

Detect the project variant, then run the default dry-run to inspect the exact registry item, dependencies, files, and command:

python3 scripts/react_bits.py detect --project /absolute/path/to/project
python3 scripts/react_bits.py install SplitText --project /absolute/path/to/project --variant TS-TW

When the user asked for implementation and the plan matches the project, execute the same selection:

python3 scripts/react_bits.py install SplitText --project /absolute/path/to/project --variant TS-TW --execute

Use the direct official registry URL by default. Do not modify components.json merely to add a namespace. Use --cli jsrepo only when the project already uses jsrepo or the user requests it.

5. Integrate with the Design System

Read the installed component and its local usage examples before wiring props. Connect colors, spacing, typography, and radii to project tokens rather than adding competing literals. Preserve semantic HTML and application state outside decorative effects.

Add reduced-motion behavior and a static fallback where the upstream variant lacks them. Keep inputs, links, menus, and focusable controls keyboard-operable. Pause or simplify continuous effects when offscreen or when the document is hidden.

6. Audit and Repair Locally

Run the project build, typecheck, and relevant tests after installation. Apply the seven-dimension review in references/quality-gate.md: hierarchy, spacing, color, accessibility, AI-slop, motion, and copy.

Report only verified findings. Distinguish source inspection from rendered-browser verification; mark unavailable visual checks as unverified. Fix P0 issues first and patch only the offending token, component, or region rather than regenerating the whole page.

Guardrails

• Use the public official catalog as the default component universe; exclude hidden registry entries unless explicitly requested by exact name.
• Do not guess props, dependencies, file targets, or CLI identifiers. Inspect catalog metadata and installed source.
• Do not add Pro components, paid templates, or external services as prerequisites.
• Do not require Claude Design, Figma, a hosted browser, or a particular MCP server. Use local source and optional browser evidence when available.
• Do not claim accessibility or performance compliance from static patterns alone.
• Do not overwrite an existing design direction with generic anti-default rules.

Completion Contract

Deliver working code rather than a component list alone. State the chosen design direction, exact installed component IDs, changed files, and verification results. Include remaining unverified visual or runtime checks explicitly.