Integrating shadcn/ui Components with Generated Stitch Designs: From Mock-Up to Production

Stitch generates design assets that shadcn/ui components consume through shared CSS variables, enabling rapid conversion of AI-generated mock-ups into type-safe, accessible React interfaces.

The google-labs-code/stitch-skills repository provides AI-driven design generation capabilities that produce structured specifications and static HTML assets. By integrating these outputs with shadcn/ui—a collection of reusable, Tailwind-styled React components—you can transform visual mock-ups into production-ready codebases where design changes propagate automatically through the component layer.

End-to-End Workflow Overview

The integration follows a six-phase pipeline that bridges AI-generated design artifacts and component-based development.

1. Generate a design using the stitch::generate-design or stitch::extract-static-html skill to produce .stitch/DESIGN.md and corresponding HTML assets, as documented in plugins/stitch-design/skills/generate-design/SKILL.md.

2. Inspect the design specification contained in DESIGN.md, which defines the high-level design system including colors, spacing, and component intent, detailed in plugins/stitch-utilities/skills/design-md/SKILL.md.

3. Select shadcn/ui components from the catalog using the shadcn-ui skill to identify matches for UI primitives like Button, Card, or Dialog, referenced in plugins/stitch-build/skills/shadcn-ui/SKILL.md.

4. Install components into src/components/ui/ using the CLI or the skill's direct installation API, following the steps in plugins/stitch-build/skills/shadcn-ui/resources/setup-guide.md.

5. Wire components to the design by replacing placeholder HTML with imported components, feeding design-system values from globals.css into the components via the cn() utility, as shown in plugins/stitch-build/skills/shadcn-ui/resources/customization-guide.md.

6. Validate and publish by running type-checking, linting, and accessibility audits (axe, Jest) before committing changes.

Architecture and Implementation Details

Design-to-Component Mapping via CSS Variables

The DESIGN.md block defines CSS custom properties for colors, background, and foreground values. shadcn/ui reads these variables through its built-in cn() utility (see lines 15-25 of the skill file), ensuring components automatically inherit the design system created by Stitch. This variable bridge eliminates hard-coded values and keeps the UI synchronized with generated specifications.

Component Placement and Composition Patterns

shadcn/ui components are stored under src/components/ui/. Custom wrappers live in src/components/ outside the ui/ folder, allowing you to compose higher-level UI blocks without altering the original component source. The LoadingButton example (lines 86-104) demonstrates how to extend base functionality while preserving the underlying theme integration.

Tailwind Configuration and Theming

Tailwind is configured via tailwind.config.cjs generated by shadcn@latest init. The globals.css file provides the CSS variables that shadcn/ui consumes. Changing a variable in the stylesheet updates every component that references it, maintaining sync between the generated design and the live interface.

Type-Safe Variants with Class Variance Authority

shadcn/ui uses class-variance-authority (CVA) to define component variants such as button size and style. The design spec can dictate which variant to apply by passing the appropriate prop when rendering. The buttonVariants definition (lines 58-80) shows how these variants map to Tailwind classes, allowing the design system to drive component appearance through typed props.

Accessibility Guarantees

All shadcn/ui components are built on Radix UI primitives, providing keyboard navigation, ARIA attributes, and focus management out of the box. When customizing components, preserve the ARIA attributes and test with screen readers (see the Accessibility section, lines 22-30).

Step-by-Step Integration Tutorial

Follow this concrete implementation path to connect Stitch-generated designs with your component library.

First, generate your design assets and identify the required UI primitives from the DESIGN.md specification.

Install the necessary shadcn/ui components into your project:

npx shadcn@latest add button   # adds src/components/ui/button.tsx

npx shadcn@latest add card

Reference plugins/stitch-build/skills/shadcn-ui/resources/setup-guide.md for full initialization details.

Map the design tokens from DESIGN.md to your global stylesheet:

/* src/app/globals.css */
@layer base {
  :root {
    --primary: 221.2 83.2% 53.3%;   /* From DESIGN.md */
    --background: 0 0% 100%;
    /* … other variables … */
  }

  .dark {
    --primary: 221.2 83.2% 35%;    /* Dark-mode override */
    --background: 222 84% 4.9%;
  }
}

See plugins/stitch-build/skills/shadcn-ui/resources/customization-guide.md for the complete variable list.

Create wrapper components that bind design slots to shadcn/ui primitives:

// src/components/hero-cta.tsx
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";   // shadcn's cn() helper

export function HeroCTA({ label }: { label: string }) {
  return (
    <Button
      className={cn(
        "text-lg font-semibold",   // additional design-specific classes
        "bg-primary text-primary-foreground"
      )}
    >
      {label}
    </Button>
  );
}

The LoadingButton example (lines 86-104) provides a pattern for extending base components with additional logic.

Replace the static HTML generated by Stitch with your React component tree:

// src/app/page.tsx (Next.js example)
import { HeroCTA } from "@/components/hero-cta";

export default function HomePage() {
  return (
    <section className="flex flex-col items-center gap-6 py-12">
      {/* Generated design gave us a <div class="hero"> … */}
      <HeroCTA label="Get Started" />
    </section>
  );
}

Finally, validate your integration before committing:

# Type checking

tsc --noEmit

# Lint

npm run lint

# Accessibility audit (aXe)

npm exec axe ./out

See the validation checklist in plugins/stitch-build/skills/shadcn-ui/SKILL.md (lines 4-10) for additional quality gates.

Summary

• Stitch skills generate DESIGN.md and HTML assets that serve as the source of truth for visual design.
• shadcn/ui components consume design tokens through CSS variables defined in globals.css, ensuring automatic synchronization.
• The cn() utility merges Tailwind classes with design-system values, bridging the gap between generated specs and component props.
• Components are installed via npx shadcn@latest add into src/components/ui/, while custom wrappers reside in src/components/ to maintain clean separation.
• Class Variance Authority (CVA) provides type-safe variant control that maps design intent to component appearance.
• Built on Radix UI, the components maintain accessibility standards (ARIA, keyboard navigation) without additional configuration.

Frequently Asked Questions

How do Stitch-generated CSS variables connect to shadcn/ui components?

shadcn/ui components reference CSS custom properties (e.g., --primary, --background) defined in globals.css. The DESIGN.md file generated by Stitch skills specifies the values for these variables. When you copy the design tokens into your stylesheet, the cn() utility ensures components inherit these values automatically, creating a live bridge between the AI-generated design and your React code.

Can I customize shadcn/ui components without breaking the design sync?

Yes. Store custom wrappers in src/components/ (outside the ui/ folder) and import the base components from src/components/ui/. This pattern, illustrated in the LoadingButton example (lines 86-104), allows you to extend functionality or add design-specific classes while keeping the underlying component source—and its connection to the design system—intact.

Where should I place design-specific wrapper components?

Place reusable shadcn/ui primitives in src/components/ui/ as installed by the CLI. Store application-specific compositions and wrappers in src/components/ or appropriate feature directories. This separation prevents accidental overwrites when updating shadcn/ui components via npx shadcn@latest add while keeping your design-specific logic organized.

What accessibility standards do these integrated components meet?

All shadcn/ui components are built on Radix UI primitives, which provide WAI-ARIA compliant keyboard navigation, focus management, and screen-reader support out of the box. When integrating with Stitch designs, ensure you preserve the ARIA attributes provided by the base components and run automated accessibility audits using tools like axe-core to verify compliance with WCAG guidelines.

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