Parser

The parser module (pipeline/parser.ts) reads a raw Stitch HTML document and extracts everything the pipeline needs to generate a React project: font links, custom CSS, the Tailwind theme config, and a full hierarchical component tree built from HTML comment markers.

`parseStitchHtml`

function parseStitchHtml(html: string): StitchParseResult

The main parser entry point. Accepts a full Stitch HTML document and returns a StitchParseResult.

Component extraction algorithm

Stitch embeds  comment markers throughout the HTML at every level of nesting. The parser uses htmlparser2 with character position tracking to locate these markers and build a component tree:

Scan sibling nodes for uppercase HTML comments (, , etc.).
Each comment “claims” the next sibling block element as its component body.
After claiming an element, the parser recurses into it to find nested sub-components — producing a tree, not just a flat list.
Only root components (depth 0, no parent) appear in pageBodyHtml. Structural wrappers like <main> and <section> that don’t have a comment marker are preserved in the page file.

Label normalisation — raw comment text is normalised to a valid PascalCase component name before use:

Raw comment	Normalized name
`TopNavBar from JSON mapping`	`TopNavBar`
`Entry 1: Latest`	`Entry1`
`Bold Footer CTA`	`BoldFooterCta`
`HeroSection - dark`	`HeroSection`

A normalised name must be at least 3 characters and start with an uppercase letter, or the comment is ignored. Content threshold — elements that have no child elements and are under 300 characters are skipped as decorative. This prevents tiny <div> spacers from becoming empty components.

Return type: `StitchParseResult`

interface StitchParseResult {
  head: HeadAssets;
  tailwindConfig: ExtractedTailwindConfig | null;
  components: ParsedComponent[];
  pageBodyHtml: string;
  pageBodyComponentNames: string[];
  bodyHtml: string;
}

head

HeadAssets

Font links and custom CSS extracted from the <head>.

Show HeadAssets

fontLinks

string[]

Self-closing <link> tags for Google Fonts and icon fonts found in <head>. Includes both standard text fonts and Material Symbols / Material Icons CDN links.

globalCss

string

Concatenated content of all <style> blocks in <head>. Blocks larger than 50,000 characters are excluded. Written into globals.css (Next.js) or src/index.css (Vite).

tailwindConfig

ExtractedTailwindConfig | null

The Tailwind configuration extracted from a <script id="tailwind-config"> block or any <script> containing tailwind.config. Returns null if no config script is found.

Show ExtractedTailwindConfig

themeExtend

string

The raw JavaScript object literal for theme.extend, e.g. { colors: { primary: "#94cb04" }, fontFamily: { sans: ["Inter", ...] } }. Written verbatim into tailwind.config.js.

plugins

string

The raw JavaScript array for plugins, e.g. [] or [require('@tailwindcss/typography')]. Defaults to "[]" if not found.

darkMode

string | null

The darkMode strategy, e.g. "class" or "media". When "class", the generated <html> tag receives className="dark".

raw

string

The full raw script content, before any parsing. Useful for debugging config extraction issues.

components

ParsedComponent[]

All components extracted from the HTML, in tree order (parent before children). Each component has its direct child components replaced by <ChildName /> placeholders in its html field.

Show ParsedComponent

name

string

Normalised PascalCase component name derived from the HTML comment marker, e.g. "TopNavBar", "HeroSection".

html

string

Outer HTML of this component with its direct child components replaced by <ChildName />. This is the HTML that gets compiled to JSX for the component file.Example: if TimelineContainer contains <div>...</div>, its html will have <Entry1 /> in place of that block.

rawHtml

string

Outer HTML of this component, unmodified. Used for similarity comparison when the same component name appears on multiple screens.

depth

number

Depth within the component tree. 0 means a direct child of the page body (root component). 1 means nested inside a root component, and so on.

children

string[]

Names of direct child components. The component file imports these and uses them as JSX tags inside its return value.

pageBodyHtml

string

The page body HTML with all root components replaced by <ComponentName /> placeholders. Structural wrappers (<main>, <nav>, etc.) that wrap components without their own comment marker are preserved. This becomes the JSX inside the page file’s return statement.

pageBodyComponentNames

string[]

Names of root-level components only. These are the names the page file imports — child components are imported by their parent component files instead.

bodyHtml

string

Raw <body> content, unmodified. Used as a fallback when no comment markers are found — the entire body becomes a single component named after the screen.

`extractGoogleFonts`

function extractGoogleFonts(html: string): GoogleFontSpec[]

Scans a full HTML document for Google Fonts URLs — both in <link href="..."> tags and in @import url(...) statements — and returns structured font specifications for use with next/font/google. The function deduplicates by font family name, so a font referenced via both a <link> tag and a CSS @import is returned only once.

Return type: `GoogleFontSpec[]`

interface GoogleFontSpec {
  family: string;
  weights: string[];
  subsets: string[];
  variable: string;
}

family

string

Human-readable font family name with spaces, e.g. "Inter", "JetBrains Mono", "Roboto Condensed". Spaces are decoded from + in the Google Fonts URL.

weights

string[]

Array of weight strings to pass to next/font/google. If the URL uses a variable weight range (e.g. wght@100..900), the weights default to ["400", "500", "600", "700", "800"]. If specific weights are listed (e.g. wght@400;700), those are used directly. If no weight spec is present, defaults to ["400"].

subsets

string[]

Always ["latin"]. Stitch designs target Latin character sets.

variable

string

camelCase identifier derived from the family name — used as the variable name in the generated layout.tsx import. The first character is lowercased and spaces are converted to camelCase:

Family	Variable
`Inter`	`inter`
`JetBrains Mono`	`jetBrainsMono`
`Roboto Condensed`	`robotoCondensed`
`DM Sans`	`dMSans`

Icon font handling

Font families in the Material Symbols and Material Icons families ("Material Symbols Outlined", "Material Icons", etc.) are excluded from GoogleFontSpec results. These fonts cannot be loaded via next/font/google and must remain as CDN @import links in globals.css. The pipeline filters them out before calling extractGoogleFonts for the next/font/google optimization path.

Example

import { extractGoogleFonts } from './pipeline/parser';

const html = `
  <head>
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700&display=swap" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400..700&display=swap" rel="stylesheet">
  </head>
`;

const fonts = extractGoogleFonts(html);
// [
//   { family: "Inter", weights: ["400", "500", "700"], subsets: ["latin"], variable: "inter" },
//   { family: "JetBrains Mono", weights: ["400", "500", "600", "700", "800"], subsets: ["latin"], variable: "jetBrainsMono" }
// ]

The pipeline uses these specs to generate next/font/google imports in app/layout.tsx:

import { Inter, JetBrains_Mono } from 'next/font/google';
const interFont = Inter({ subsets: ["latin"], weight: ["400", "500", "700"], display: "swap" });
const jetBrainsMonoFont = JetBrains_Mono({ subsets: ["latin"], weight: ["400", "500", "600", "700", "800"], display: "swap" });

The next/font/google optimization path replaces @import url(...) Google Fonts calls in globals.css entirely. The original <link> tags from the Stitch HTML are not written to the output HTML — Next.js inlines the optimized font during build instead.

MCP Tool

Pipeline Internals

`parseStitchHtml`

Component extraction algorithm

Return type: `StitchParseResult`

`extractGoogleFonts`

Return type: `GoogleFontSpec[]`

Icon font handling

Example

Build docs developers (and LLMs) love

MCP Tool

Pipeline Internals

Documentation Index

​parseStitchHtml

​Component extraction algorithm

​Return type: StitchParseResult

​extractGoogleFonts

​Return type: GoogleFontSpec[]

​Icon font handling

​Example

Build docs developers (and LLMs) love

`parseStitchHtml`

Component extraction algorithm

Return type: `StitchParseResult`

`extractGoogleFonts`

Return type: `GoogleFontSpec[]`

Icon font handling

Example