Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BaselAshraf81/holystitch/llms.txt

Use this file to discover all available pages before exploring further.

​
The contribution philosophy

HolyStitch is a compiler, not a prompt. The HTML-to-JSX transformation in packages/mcp-server/src/pipeline/compiler.ts is deterministic: given the same Stitch HTML input, it always produces the same JSX output. That means the most valuable contribution is a failing test case — a snippet of Stitch HTML that the compiler converts incorrectly, paired with what the correct output should look like. A good test case is a precise, reproducible bug report. It tells you exactly where the regex or attribute-transform logic breaks down, and it gives anyone fixing the bug an instant pass/fail verification.
You do not need to fix the bug yourself to contribute. Opening an issue with a clear input/output pair is genuinely useful.

​
How the compiler works

The compiler (compiler.ts) is a two-phase pipeline:
  1. Pre-processing — pattern-specific transforms that cannot be done safely with a single regex pass (Material Icons text stripping, curly brace escaping in <pre> blocks).
  2. Tag and attribute rewriting — a regex pass over the HTML that rewrites every opening tag: attribute renames, style string conversion, void-element self-closing, and event-handler camelCasing.
After both phases, if the result has more than one root element, it is wrapped in a React fragment (<>…</>). Because the compiler is regex-based, it can go wrong in a few predictable ways:
  • A regex doesn’t match an unexpected variant of valid HTML (e.g. attributes with single-quoted values, attributes with no value at all)
  • An attribute rename is missing from ATTR_MAP or EVENT_MAP
  • A CSS value contains a construct the style-parser hasn’t seen before (nested calc(), custom property fallbacks, font-variation-settings)
  • The Material Icons regex doesn’t match a new icon class variant Stitch emits

​
Patterns the compiler handles

Understanding what the compiler already covers helps you identify what might be missing.

​
Attribute renames

Standard HTML attributes are renamed to their JSX equivalents. The full mapping is in ATTR_MAP in compiler.ts. 
<label for="email" class="form-label" tabindex="0">Email</label>

​
Inline style conversion

CSS style strings are converted to JSX style objects. Hyphenated property names are camelCased. Complex values like url(), calc(), and var() are preserved as strings. 
<div style="background-image: url('/hero.png'); font-size: 16px; color: red;">
If a CSS value contains a semicolon inside a url() or calc(), the style parser uses paren-depth tracking to split declarations correctly. If you find a style value that splits at the wrong place, that is a bug worth reporting.

​
Material Symbols / Icons text stripping

Stitch emits the icon name as both a data-icon attribute and as text content. The Material Symbols font renders the glyph via CSS class — if the text content is left in place, the icon name appears as visible text. The compiler strips it. 
<span class="material-symbols-outlined" data-icon="check_circle">check_circle</span>
The data-icon attribute is dropped entirely (it is a Stitch artifact with no use in React).

​
data-alt → alt promotion

Stitch uses data-alt on <img> elements instead of the standard alt attribute. The compiler promotes data-alt to a real alt prop and removes the data-alt. If both alt and data-alt are present, data-alt wins (it is the more descriptive value Stitch provides). 
<img src="/hero.png" alt="short" data-alt="Hero image showing the product dashboard" />

​
<pre><code> curly brace escaping

Stitch code examples contain raw { and } characters. JSX treats bare curly braces as expression delimiters, which causes a parse error. The compiler replaces them with HTML entities inside every <pre> block. 
<pre><code>const x = { key: "value" };</code></pre>

​
Fragment wrapping for multiple root elements

JSX requires a single root element. If the compiled output has more than one root, the compiler wraps the entire output in a fragment. 
<header>Nav</header>
<main>Content</main>
<footer>Footer</footer>

​
What a good test case looks like

A good test case has three parts:
  1. The Stitch HTML snippet — the smallest fragment that reproduces the problem. Trim it down to the relevant element if possible.
  2. The wrong JSX — what the compiler currently outputs.
  3. The expected JSX — what it should output.
Input HTML:
  <span class="material-icons">settings</span>

Current output (wrong):
  <span className="material-icons">settings</span>

Expected output:
  <span className="material-icons"></span>
The more minimal the snippet, the easier it is to locate the exact regex or branch that needs updating.

​
Opening a bug report

1

Reproduce the problem

Build the project locally (npm install && npm run build) and run a conversion that triggers the bad output. Copy the relevant fragment from the stitch-source/ directory that HolyStitch writes alongside every conversion.
2

Trim the snippet

Reduce the HTML to the smallest fragment that still shows the wrong output. A 3-line snippet is easier to act on than a 300-line screen.
3

Open an issue

Go to github.com/BaselAshraf81/holystitch/issues and open a new issue. Include:
  • The HTML input
  • The current (wrong) JSX output
  • The expected JSX output
  • The Stitch screen or component name if relevant
No template is required — a clear input/output pair is enough.

​
Opening a pull request

1

Clone and install

git clone https://github.com/BaselAshraf81/holystitch
cd holystitch
npm install
2

Locate the relevant code

Almost all HTML-to-JSX logic lives in two files:
  • packages/mcp-server/src/pipeline/compiler.ts — attribute transforms, style parsing, pre-processing
  • packages/mcp-server/src/pipeline/parser.ts — Stitch HTML parsing, component extraction, Tailwind config extraction
Start with compiler.ts for attribute or style issues. Start with parser.ts for component-boundary or structure issues.
3

Make your fix

Edit the relevant file. For a new attribute rename, add an entry to ATTR_MAP. For a new Material Icons class variant, extend the regex in preProcessHTML. For a style-parsing issue, update splitCssDeclarations or styleStringToObject.
4

Verify the build passes

npm run build
npm run lint
Both commands must exit cleanly before submitting.
5

Submit the PR

Push your branch and open a pull request. In the description, include the same input/output pair from the bug report so the reviewer can verify the fix without running a full conversion.
There is no automated test suite at this time. Verification is manual: build the project, point your MCP host at the local dist/index.js, run a conversion, and confirm the output is correct. See Local development for setup instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us