How I force Copilot to write deterministic React UI (using a custom Markdown Skill)

[MegaByteMark]

Select Topic Area

General

Copilot Feature Area

Copilot Agent Mode

Body

Hi,

I've been heavily using Copilot's Agent mode to scaffold frontend code, particularly React which I'm relatively new to. It’s amazing, but I found that writing natural language prompts for complex UI layouts ("make a login page with a card in the middle and a dark button") was too flaky. Sometimes it hallucinates, totally misses constraints, or generates spaghetti CSS that doesn't match the theme I'm trying to implement.

I wanted a way to give Copilot strict "wireframes" it could actually understand. Figma is too token-heavy, paired with the fact LLM's don't have eyeballs so its doing its best guess of pixel math to work out how things should be arranged, and trying to explain intricate layout in English is equally cumbersome.
So I built an open-source intermediate representation which I've called the Markdown-UI DSL.

I packaged it as a Copilot Custom Skill that you can just drop into .github/skills/markdown-ui-agent/SKILL.md.

Once installed, you can write dumb-simple .ui.md files like this:

---
framework: Next.js + TailwindCSS + Shadcn UI
theme: ./design-system.md
component: src/components/LoginForm.tsx
---

||| COLUMN |||
::: CARD :::
# Welcome Back
[ text: Email Address ]
[ text: Password ]
[ Login ](#login)
--- END ---
--- END ---

Why this works so well with Copilot Agent Mode:

• Deterministic Parsing: Because the syntax is incredibly rigid (||| COLUMN |||, [ ] Checkbox, |[ Tabs ]|), Copilot maps it perfectly.
• Design Isolation: You point the top YAML frontmatter at a single design-system.md file (where you list your Tailwind standards), and Copilot applies that theme globally to every .ui.md file you feed it.
• Two-Way Code Sync: This is my favourite part—if you update the wireframe spec in the .ui.md, the Copilot skill instructs it to automatically hunt down the frontend component mapped in the frontmatter (src/components/LoginForm.tsx) and update the React code to match your spec changes.
  If you are trying to implement true "Spec-Driven Development" (SDD) using Copilot agents, you might find this really useful.

I wrote up a quick 2-minute installation guide in the repo here: https://github.com/MegaByteMark/markdown-ui-dsl

Would love to know how you guys handle UI design prompting with Copilot and if you find this DSL useful!

[RDEsley]

Hey @MegaByteMark, this is a really clever approach and the timing is great because I've been wrestling with the exact same problem.

The flakiness you're describing with natural language UI prompts is real. I've noticed that the more specific the layout constraint (things like "card centered, checkbox left-aligned, link right-aligned on the same row"), the worse natural language gets, because the model is inferring spatial relationships from text rather than parsing a structure.

Your DSL sidesteps that entirely by making layout syntactically unambiguous. The ||| COLUMN ||| / === ROW === nesting is especially smart, it maps almost 1:1 to Flexbox/Grid mental models, so there's no translation loss.

A few questions / thoughts:
On the two-way sync, does the skill handle partial diffs gracefully? E.g. if I only change one input field in the .ui.md, does Copilot know to surgically update just that component, or does it tend to regenerate the whole file? That's where I'd expect the most drift.

On the design-system.md file, are you storing raw Tailwind class mappings in there (e.g. primary-button: bg-blue-600 rounded-xl font-bold), or is it more semantic/token-based? Curious how opinionated the schema is.

On alternatives considered, did you look at anything like Storybook's CSF format or a JSON schema approach before landing on Markdown? Just curious why Markdown won out (my guess: it's the most token-efficient + human-readable combo).

Going to try dropping this into a project this weekend. The repo structure looks clean. Nice work making it installable as a single skill file drop-in, that's the right distribution model for this kind of thing.

[MegaByteMark]

Hi @RDEsley, thanks for the great feedback! I'm glad to hear I wasn't the only one hitting this exact issue with prompt flakiness in layouts.

To answer your questions:

> On the two-way sync, does the skill handle partial diffs gracefully?
Because the DSL acts as an instruction set (a Skill) for your AI agent, the "gracefulness" of the diff actually relies on your Agent Host (Copilot, Cursor, Cline, etc.). Fortunately, most modern IDE agents use intelligent streaming diffs or targeted string-replacement tools. So when you change one input in the .ui.md file, the agent uses the component: YAML frontmatter to locate the code, reads its current state, and surgically replaces just that specific JSX/HTML block without regenerating the entire file. In my tests, It handles it incredibly seamlessly.

> On the design-system.md file, are you storing raw Tailwind class mappings in there?
For the current examples, yes! The examples are strongly focused on React + Tailwind to provide a quick starting point. However, the DSL itself is completely unopinionated. For example, if you wanted to build a design-system.md to target a Flutter project, you would just alter the natural language instructions in that file to describe how you want the Dart components to be themed and structured (no tailwind 😂).

> On alternatives considered, did you look at anything like Storybook's CSF format or a JSON schema approach?
Yes, I heavily considered those, but ultimately landed on Markdown for three main reasons:

1. Extensibility: Markdown lacks a strict schema, meaning it is much easier to extend the DSL syntax without facing compatibility constraints or parser breaking-changes. Revisions can just be expressed as additional natural language rules in the skill rather than mapping out new rigid JSON properties.
2. Re-use of existing elements: Markdown already natively handles structural text beautifully (Headings, tables, lists, bold/italics). The skill inherently understands these default elements, meaning there's no requirement to invent new syntax for basic text formatting.
3. Natural Language Directives: AI agents can ingest natural language wrapped inside the markdown that falls outside of the visual syntax. For example, if you want to align a user avatar in a header, you don't need to bloat the DSL syntax. You just use a standard markdown blockquote > to pass a hint to the LLM:

   > align items to the right space-between
   [ IMG: User Avatar (rounded) ]

This fluidity is much harder to achieve with rigid JSON/CSF schemas, which expect key-value pairs for everything.

FYI - I've pushed an update to the skill this morning to specifically add support for the Natural Language Directives and some additional common UI components e.g. Headers, Footers etc. Please make sure you grab the latest copy of the skill for your project.

Thanks again for checking it out, let me know how it goes dropping it into your project this weekend!

[RDEsley]

Thanks for the thorough follow-up @MegaByteMark, the answers actually resolved a concern I hadn't fully articulated yet.

The point about diff gracefulnessrelying on the agent host is something I hadn't thought through properly. It makes sense that the DSL just needs to be a stable reference point, and the host handles the surgical replacement. That reframes how I was thinking about it, the skill is the spec, not the patch mechanism.

The Natural Language Directives via blockquotes is a genuinely elegant escape hatch. The fact that you're not trying to encode every possible layout constraint into the DSL syntax, but instead letting the LLM fill in the gaps with a hint, is the right call. Rigid schemas always end up fighting you the moment you hit an edge case.

Grabbed the latest skill update, I'll drop it into a small project this weekend and report back. One thing I'm curious to stress-test: nested layouts with conditional rendering (e.g. a tab group where each tab has a different column structure). I'll see how the DSL handles that and let you know.

Nice work on the update, looking forward to putting it through its paces! 🚀

[MegaByteMark]

Hi @RDEsley,

Just an FYI: based on some of the discussions here, I've pushed a major update to the markdown-ui-agent.md skill to make it even more robust!

Here are the key improvements:

Bulletproof Two-Way Binding: I updated the skill to explicitly teach the LLM how to handle the different sync directions (Wireframe -> Code and Code -> Wireframe). It now includes specific instructions on how to handle "drift" scenarios (e.g., when a human-in-the-loop updates the code manually and the LLM needs to resolve the conflict with the wireframe).

True Framework Agnosticism: I removed implicit "web biases" (like references to HTML/CSS) from the core skill instructions so agents don't get confused when working in mobile or desktop environments.

New Design System Examples: To prove the cross-platform nature of the DSL, I've split out the design-systems/ directory. We now have tailored examples showing how to map the exact same .ui.md spec to React + Tailwind, Flutter + Material, and Blazor + Bootstrap.

Natural Language Directives: Officially documented support for inline > blockquotes to pass contextual layout hints to the agent without breaking the strict syntax.

Let me know if you run into any parsing quirks with these updates while you're dropping it into your project this weekend. Very excited to see how it handles your workflows!

[Nyrok]

This nails the core problem: natural language is ambiguous, and LLMs amplify that ambiguity. Your DSL works because it gives the model typed, scoped structure instead of a blob of English to interpret. The ||| COLUMN ||| / === ROW === syntax is smart precisely because it maps 1:1 to layout primitives.

I ran into the same insight from the prompt side. Not UI wireframes, but general prompts. Role instructions, constraints, output format, examples... when they're all mixed in one text block, the model guesses which part matters most. Structure fixes that.

I've been building flompt around this idea. It decomposes prompts into 12 typed semantic blocks (role, constraints, output format, chain of thought, etc.) on a visual canvas, then compiles them to Claude-optimized XML. Same principle as your DSL: give the model unambiguous boundaries between different types of instructions.

Curious if you've thought about extending the Markdown-UI approach beyond layout. Things like accessibility constraints or interaction states could be their own typed blocks in the spec.

[MegaByteMark]

Hi @Nyrok,

Thanks for the great feedback!

I completely agree with your philosophy—providing unambiguous boundaries is exactly what turns unpredictable LLM output into predictable, deterministic pipelines.

I checked out flompt and it looks extremely powerful as a visual tool for tuning prompts into that optimised XML structure. For power users orchestrating complex chains, it looks incredible to be honest.
My only feedback is that the canvas approach with 12 semantic blocks might have a steep learning curve for someone unfamiliar with how prompt responses flow, but it solves the structural problem perfectly.

As for extending the Markdown-UI approach beyond layout to things like accessibility or interaction states: I've actually thought about this, but chose to intentionally keep them separated out of the DSL.

My philosophy here is essentially Separation of Concerns for Agent Skills:

1. The UI DSL is strictly the structural scaffolding—acting like basic, primitive building blocks ("put this here, wrap that in a column"). It needs to remain readable enough for a non-technical PM or designer to write without getting bogged down in state management.
2. Other app-specific concerns should be abstracted into their own domain-specific skills or global instructions.

For example, instead of bloating the .ui.md file with screen-reader constraints, the LLM should just have a separate accessibility-standards.md skill that instructs it: "Whenever you are translating a UI component, always implement proper ARIA roles and screen-reader compatibility."

By keeping the layout DSL isolated, we allow the agent to combine it with other technical skills (accessibility, interactivity, theme systems) under the hood without making the wireframe itself too complex to read.

I had this exact problem yesterday when doing some further testing. I wanted my user avatar to be right-aligned, but the DSL didn't have a rigid syntax to specify this. Instead of building new syntax tokens, I chose to extend the skill to allow the agent to receive inline structural hints as standard markdown blockquotes, e.g.:

> align the next element to the right of the header
[ IMG: User Avatar ]

Love where your head is at with Flompt though—we are definitely tackling two sides of the same coin!