best-practices

Common Anti-Patterns to Avoid with the react-components Skill: A Complete Guide

July 18, 2026 google-labs-code/stitch-skills ↗

Violating the react-components skill's strict validation pipeline causes npm run validate to fail and produces unmaintainable React components.

The react-components skill in the google-labs-code/stitch-skills repository converts Stitch designs into a modular Vite/React codebase. Because the skill enforces a four-phase validation pipeline across retrieval, style extraction, architecture, and execution, bypassing any convention triggers hard failures. Below are the critical anti-patterns defined in plugins/stitch-build/skills/react-components/SKILL.md that break the workflow and how to avoid them.

Phase 1 Anti-Patterns: Design Retrieval

Skipping the mandatory metadata fetch or download protocols creates sync errors before code generation begins.

Reading HTML Files Directly Without MCP get_screen

Accessing .stitch/designs/*.html directly instead of calling the MCP get_screen tool skips the mandatory metadata fetch. This causes generated components to be out-of-sync with the source design, violating the retrieval gate defined in SKILL.md.

Bypassing the fetch-stitch.sh Script

The scripts/fetch-stitch.sh script handles redirects and security handshakes required by the Stitch CDN. Bypassing it leads to incomplete or corrupted HTML and screenshot assets, causing extraction failures in Phase 2.

Silently Overwriting Existing Design Files

The skill requires explicit user consent before overwriting local files in .stitch/. Replacing files without asking violates the workflow's data-loss prevention rules.

Skipping Visual Audit of PNG Screenshots

Failing to confirm the visual layout against .png screenshots means downstream style extraction may target the wrong design elements, producing incorrect Tailwind classes.

Outdated or Missing metadata.json

The validator compares timestamps against Last Sync Time in .stitch/metadata.json. An outdated file triggers a sync error during npm run validate, blocking the build.

Phase 2 Anti-Patterns: Style Extraction

Mismanaging design tokens breaks the theming system and dark-mode support.

Using Stale style-guide.json Without Verification

The validator expects resources/style-guide.json to reflect tokens extracted from the current HTML <head>. Using a stale file causes mismatched Tailwind classes and fails the style consistency check.

Hard-Coding Hex Colors Instead of Theme Tokens

Hard-coding hex values in components bypasses the design system entirely. The skill enforces theme-mapped classes from style-guide.json; raw colors break dark-mode support and fail validation.

/* Anti-pattern */
<div className="bg-[#3b82f6]">

/* Correct */
<div className="bg-primary-light dark:bg-primary-dark">

Phase 3 Anti-Patterns: Architectural Rules

Violating component architecture rules prevents the code from passing the modularity and logic isolation gates.

Monolithic Page Components

Packing all UI into a single page file fails the modularity gate. Reusable UI patterns must live as separate files under src/components/, as enforced by the architecture checklist in resources/architecture-checklist.md.

Inline Event Handlers Instead of Custom Hooks

Placing event-handler logic directly inside component bodies violates the "Logic isolation" rule. All logic must be isolated in custom hooks under src/hooks/.

// src/hooks/usePagination.ts
import { useState } from 'react';

export const usePagination = (totalItems: number, pageSize: number) => {
  const [page, setPage] = useState(1);
  const totalPages = Math.ceil(totalItems / pageSize);

  const next = () => setPage((p) => Math.min(p + 1, totalPages));
  const prev = () => setPage((p) => Math.max(p - 1, 1));

  return { page, totalPages, next, prev };
};

Hard-Coding Data Inside Components

Static text, image URLs, or data must reside in src/data/mockData.ts. Hard-coded values break the "Data decoupling" rule and prevent component reuse.

Missing Readonly TypeScript Props Interfaces

Every component must declare a [ComponentName]Props interface marked as Readonly. The validator in scripts/validate.js explicitly checks for this; missing it produces a compile-time error.

export interface ProductCardProps {
  readonly id: string;
  readonly title: string;
  readonly imageUrl: string;
  readonly price: number;
}

export const ProductCard: React.FC<ProductCardProps> = ({
  id,
  title,
  imageUrl,
  price,
}) => {
  return (
    <div className="rounded-lg bg-primary-light dark:bg-primary-dark p-4">
      <img src={imageUrl} alt={title} className="w-full h-auto" />
      <h2 className="mt-2 text-lg font-medium">{title}</h2>
      <p className="text-sm">{`$${price}`}</p>
      <Link to={`/product/${id}`} className="mt-2 inline-block text-primary">
        View details
      </Link>
    </div>
  );
};

Unconverted Anchor Tags

Leaving <a href="#"> links unchanged fails the "Navigation wiring" rule. All navigation must use React Router <Link> components to prevent dead links.

/* Anti-pattern */
<a href="#">Home</a>

/* Correct */
import { Link } from 'react-router-dom';
<Link to="/" className="text-primary">Home</Link>

Phase 4 Anti-Patterns: Execution

Premature execution or incomplete verification allows errors to slip into production builds.

Starting Dev Server Without User Permission

Starting the dev server or running browser audits without asking the user first violates the skill's optional-action protocol. These actions require explicit permission to prevent unintended side-effects.

Declaring Completion Without Validation

Marking the task "done" without running npm run validate or tsc --noEmit allows hidden compile errors to persist. Phase 4 requires successful execution of scripts/validate.js to ensure code meets the repository's strict quality standards.

Summary

  • Always use MCP get_screen to retrieve designs; never read .stitch/designs/*.html directly.
  • Run fetch-stitch.sh to handle secure downloads and avoid corrupted assets.
  • Update .stitch/metadata.json with accurate Last Sync Time to pass validation.
  • Reference style-guide.json tokens instead of hard-coding hex colors.
  • Isolate components in src/components/, hooks in src/hooks/, and data in src/data/mockData.ts.
  • Declare Readonly props interfaces for every component to satisfy TypeScript checks.
  • Use React Router <Link> components instead of <a> tags for navigation.
  • Execute npm run validate and obtain user permission before starting dev servers or finishing tasks.

Frequently Asked Questions

What happens if I skip the npm run validate step?

Skipping validation allows TypeScript errors, missing props interfaces, and architectural violations to remain undetected. The skill treats validation as a hard gate; without it, the workflow cannot complete successfully, and generated components may fail to compile or violate the project's quality standards.

Why must I use get_screen instead of reading the HTML files directly?

The MCP get_screen tool performs a mandatory metadata fetch that ensures the design files are synchronized with the latest Stitch source. Reading .stitch/designs/*.html directly bypasses this check, risking out-of-sync components and stale screenshot references that break the extraction pipeline.

Can I store helper functions inside my component files?

No. The react-components skill enforces strict logic isolation. Helper functions and stateful logic must be extracted into custom hooks under src/hooks/. Inline handlers or utility functions inside component bodies cause the "Logic isolation" validation check to fail.

How do I ensure my colors support dark mode?

Extract Tailwind theme tokens from the current HTML file and store them in resources/style-guide.json. Reference these tokens using Tailwind classes (e.g., bg-primary-light dark:bg-primary-dark) instead of hard-coding hex values. The validator checks against style-guide.json to ensure consistent theming and dark-mode compatibility.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →