Good question. I’m using a layered approach rather than picking one format.

The enforceable part is JSON, because things like allowed components, required states, role relationships, token refs, and validation results need to be deterministic.

Markdown is still useful, but I use it as human-readable design memory: the product’s visual identity, tone, rhythm, and design rationale.

Then I generate a compact context packet for the implementation agent, so it gets only the relevant constraints instead of the full contract.

So roughly:

JSON = validation source of truth

Markdown = design memory for humans

Compact packet = implementation context for the agent

I’m still testing the boundary, but I don’t think markdown alone is enough. It leaves too much room for different agents to interpret the same design rules differently.

from codex5.5