How to Validate React Components Against Stitch Design Specifications

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.

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 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, 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:

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:

// 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:

// 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 – The SWC-based validator that checks for Props interfaces and hard-coded colors
• 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 – The reference component showing the required Props interface pattern
• 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 and 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}