# How to Validate React Components Against Stitch Design Specifications

> Validate React components against Stitch design specifications using SWC parsing of TypeScript/TSX files. Enforce strict typing and Tailwind styling for seamless design system alignment.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-12

---

**Stitch validates React components by parsing TypeScript/TSX files with SWC to check for properly typed Props interfaces and enforce Tailwind-based styling rules, ensuring alignment with the design system defined in [`style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/style-guide.json).**

The `google-labs-code/stitch-skills` repository provides a validation framework that ensures React components conform to the Stitch design system. This validation performs static analysis on TypeScript/TSX files without executing them, checking for interface compliance and styling consistency. By integrating these checks into your development workflow, you can maintain strict design-system fidelity across your React codebase.

## The Three-Stage Validation Pipeline

The validator located at [`plugins/stitch-build/skills/react-components/scripts/validate.js`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/scripts/validate.js) executes a three-stage analysis pipeline to verify component compliance.

### Parsing TypeScript with SWC

The validator uses **@swc/core** to parse TypeScript/TSX files into an Abstract Syntax Tree (AST). This approach enables reliable static analysis without executing the code, allowing the validator to inspect component structure, imports, and JSX attributes programmatically.

### Validating Props Interface Declarations

The validator checks for a TypeScript interface whose name ends with `Props`. This naming convention guarantees that component inputs are explicitly typed, matching the design-system contract. Components must define an interface (e.g., `ButtonProps`, `CardProps`) rather than using inline type definitions or anonymous types.

### Enforcing Tailwind Styling Constraints

The validator flags any hard-coded hex colors in JSX `className` attributes as violations. The design system expects colors to be referenced via Tailwind utility classes or CSS custom properties defined in **[`style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/style-guide.json)**, ensuring consistent theming across the application.

## Validation Rules and Error Handling

The validator reports three distinct outcomes based on its analysis of the AST.

### Required Props Interface Pattern

Components must declare a dedicated interface ending with the `Props` suffix. This pattern ensures type safety and explicit documentation of component inputs. The validator traverses the AST to locate interface declarations and verifies the naming convention.

### Prohibited Hard-Coded Values

Raw hex color values (e.g., `bg-[#ff0000]`) in Tailwind classes trigger validation failures. The validator specifically scans `className` attributes for regex patterns matching hex color codes, rejecting any hard-coded values that bypass the design system's color tokens.

### Exit Codes and CI Integration

If both checks pass, the validator exits with status **0** and marks the component as **VALID**. If the component lacks a Props interface or contains hard-coded hex colors, the validator exits with status **1**, making it easy to integrate into CI pipelines for automated quality gates.

## Validating Components in Practice

Use the validator from the command line to check individual components or run it against your entire component library.

### Running the Validator

Execute the validation script against a specific TypeScript/TSX file:

```bash
node plugins/stitch-build/skills/react-components/scripts/validate.js path/to/MyComponent.tsx

```

### Compliant Component Example

The following component demonstrates the required Props interface pattern and proper Tailwind usage:

```typescript
// Example based on component-template.tsx
import React from 'react';

interface MyComponentProps {
  /** Optional CSS class */
  className?: string;
  /** Children render inside the component */
  children?: React.ReactNode;
}

export const MyComponent: React.FC<MyComponentProps> = ({
  children,
  className = '',
  ...props
}) => (
  <div className={`relative ${className}`} {...props}>
    {children}
  </div>
);

```

### Non-Compliant Component Example

This component fails validation due to hard-coded hex colors:

```typescript
// Validation will flag the raw hex value
export const BadComponent: React.FC = () => (
  <div className="bg-[#ff0000] p-4">
    Hello
  </div>
);

```

### Key Configuration Files

The validation process relies on these specific resources:

- **[`plugins/stitch-build/skills/react-components/scripts/validate.js`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/scripts/validate.js)** – The SWC-based validator that checks for Props interfaces and hard-coded colors
- **[`plugins/stitch-build/skills/react-components/resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/resources/style-guide.json)** – The central design-system definition containing colors, typography, and spacing tokens
- **[`plugins/stitch-build/skills/react-components/resources/component-template.tsx`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/resources/component-template.tsx)** – The reference component showing the required Props interface pattern
- **[`plugins/stitch-design/skills/extract-design-md/references/react-tailwind.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/references/react-tailwind.md)** – The detailed guide on extracting and interpreting Tailwind-based design specifications

## Summary

- **Stitch validates React components** using SWC to parse TypeScript/TSX files into an AST for static analysis.
- **Props interfaces must end with `Props`** to ensure explicit typing and design-system contract compliance.
- **Hard-coded hex colors in `className` attributes** trigger validation failures; use Tailwind utility classes or CSS custom properties instead.
- **Exit code 0 indicates success** while exit code 1 signals validation errors, enabling seamless CI/CD integration.
- **Reference implementations** are available in [`component-template.tsx`](https://github.com/google-labs-code/stitch-skills/blob/main/component-template.tsx) and [`style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/style-guide.json) within the `google-labs-code/stitch-skills` repository.

## Frequently Asked Questions

### What file does Stitch use to validate React components?

Stitch uses [`plugins/stitch-build/skills/react-components/scripts/validate.js`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/scripts/validate.js) to perform validation. This script leverages the SWC compiler to parse TypeScript/TSX files and checks for Props interface patterns and hard-coded color values.

### Why does the validator require Props interfaces to end with "Props"?

The naming convention ensures that component inputs remain explicitly typed and easily identifiable within the codebase. This requirement enforces consistency across the design system and makes component contracts immediately recognizable to developers and automated tools.

### How does Stitch handle hard-coded color values in Tailwind classes?

The validator scans `className` attributes for hex color patterns (e.g., `#ff0000`) and flags them as violations. The design system requires all colors to reference Tailwind utility classes or CSS custom properties defined in [`style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/style-guide.json) to maintain visual consistency.

### Can I integrate Stitch validation into a CI/CD pipeline?

Yes. The validator exits with status 0 for compliant components and status 1 for failures, following standard Unix conventions. This behavior allows you to add the validation script to pre-commit hooks or CI workflows to block merges that violate design specifications.