diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 06bc3b3..6f54e0e 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -85,6 +85,11 @@ for (const variant of variants) { | `creativeRange` | `string` | `"EXPLORE"` | `"REFINE"`, `"EXPLORE"`, or `"REIMAGINE"` | | `aspects` | `string[]` | all | `"LAYOUT"`, `"COLOR_SCHEME"`, `"IMAGES"`, `"TEXT_FONT"`, `"TEXT_CONTENT"` | + +## Examples + +- [Design to React Component](examples/design-to-react) — Agent skill for interpreting HTML and extracting React components. + ## Tool Client (Agent Usage) For agents and orchestration scripts that need direct MCP tool access: diff --git a/packages/sdk/examples/design-to-react/README.md b/packages/sdk/examples/design-to-react/README.md new file mode 100644 index 0000000..e2805a0 --- /dev/null +++ b/packages/sdk/examples/design-to-react/README.md @@ -0,0 +1,22 @@ +# Design to React Component Agent Skill + +This example provides an Agent Skill (`SKILL.md`) and an accompanying script to demonstrate how an agent can translate a Stitch UI design into a modular React component. + +## What this does +The included `SKILL.md` file teaches an agent how to: +1. Interpret Stitch HTML output. +2. Use the provided script to extract the embedded Tailwind configuration and Google Fonts. +3. Convert the HTML structure into JSX. +4. Create a TypeScript `Props` interface for dynamic content mapping. + +## Prerequisites +Set your Stitch API key: +```bash +export STITCH_API_KEY="your_api_key_here" +``` + +## Usage +Agents should read the `SKILL.md` file for full instructions. To run the asset extraction script manually: +```bash +bun scripts/extract-assets.ts +``` diff --git a/packages/sdk/examples/design-to-react/SKILL.md b/packages/sdk/examples/design-to-react/SKILL.md new file mode 100644 index 0000000..2158073 --- /dev/null +++ b/packages/sdk/examples/design-to-react/SKILL.md @@ -0,0 +1,50 @@ +# Skill: Design to React Component + +This skill teaches an agent how to interpret Stitch HTML (which varies in structure per design), extract the necessary assets, identify semantic sections, and produce a modular React component with a Props interface. + +## Prerequisites +You need a `projectId` and `screenId` from the Stitch SDK. + +## Steps for the Agent + +1. **Extract Assets** + Run the included extraction script to pull out the Tailwind configuration and Google Fonts from the design's HTML. + ```bash + bun packages/sdk/examples/design-to-react/scripts/extract-assets.ts + ``` + - Save the Tailwind config object (if present) to your target `tailwind.config.ts`. + - Place any Google Fonts `` tags in your React application's root (e.g., `index.html` or Next.js `_document.tsx`/`layout.tsx`). + +2. **Analyze the HTML Body** + - Inspect the remaining HTML structure. + - Identify the major semantic sections (e.g., Header, Hero, Main Content, Footer). + +3. **Convert HTML to JSX** + - Transform `class="..."` to `className="..."`. + - Convert self-closing tags to JSX format (e.g., `` to ``, `` to ``). + - Apply the extracted Tailwind classes directly to your JSX elements. + +4. **Define Props Interface** + - Review the textual content and images within the generated design. + - Abstract hardcoded values into a TypeScript `Props` interface. + - Replace hardcoded text/images with the corresponding props in your component. + +## Example Output +Your final React component should look something like this: +```tsx +import React from 'react'; + +interface MyComponentProps { + title: string; + imageUrl: string; +} + +export const MyComponent: React.FC = ({ title, imageUrl }) => { + return ( +
+

{title}

+ {title} +
+ ); +}; +``` diff --git a/packages/sdk/examples/design-to-react/scripts/extract-assets.ts b/packages/sdk/examples/design-to-react/scripts/extract-assets.ts new file mode 100644 index 0000000..a3ded44 --- /dev/null +++ b/packages/sdk/examples/design-to-react/scripts/extract-assets.ts @@ -0,0 +1,59 @@ +/** + * Fetch HTML from a screen and parse out the Tailwind configuration + * and Google Fonts links to prepare for React component conversion. + * + * Usage: + * STITCH_API_KEY=your-key bun packages/sdk/examples/design-to-react/scripts/extract-assets.ts + */ +import "../../_require-key.js"; +import { stitch } from "@google/stitch-sdk"; + +const projectId = process.argv[2]; +const screenId = process.argv[3]; + +if (!projectId || !screenId) { + console.error("Usage: bun extract-assets.ts "); + process.exit(1); +} + +const project = stitch.project(projectId); + +// Fetch all screens and filter by ID as per standard usage +const screens = await project.screens(); +const screen = screens.find(s => s.id === screenId); + +if (!screen) { + console.error(`Screen ${screenId} not found in project ${projectId}`); + process.exit(1); +} + +console.log(`🎨 Fetching assets for screen ${screen.id}...`); + +const htmlOrUrl = await screen.getHtml(); +let html = htmlOrUrl; + +if (htmlOrUrl.startsWith("http")) { + const response = await fetch(htmlOrUrl); + if (!response.ok) { + throw new Error(`Failed to fetch HTML: ${response.statusText}`); + } + html = await response.text(); +} + +const configMatch = html.match(/