Sharpen Why section with research-backed positioning#193
Conversation
Addresses HN feedback about too much friction — adds a visual "show then ask" demo at the top of the README. The animated SVG shows the core workflow: write markdown with frontmatter, run tinkerdown serve, get a live interactive app with data persistence. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
Gives readers the motivation and value prop before jumping into install instructions — addresses the core problem, what makes Tinkerdown different, and who it's for. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
Reworked from docs/archive research: adds progressive complexity tiers, git-native/self-hosted angle, LLM determinism advantage over React, throwaway tools use case, and "build a UI for your scripts" pitch. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
Reframes the section around the core value prop: Tinkerdown is a markdown format designed for LLMs to generate working UIs on the fly. Leads with the AI angle, follows with single-file simplicity and progressive power. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
Addresses key HN thread points: runtime vs MDX (compile-time), freezeable/reusable views, Kubernetes dashboard use case, and sharpens the on-the-fly UI pitch. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
Rewrites all bullet points to avoid borrowed phrasing. Tightens the language and uses more concrete, specific examples throughout. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
The previous intro described the workflow but didn't explain why markdown over React. Now directly addresses the maintenance and dependency burden that LLM-generated React still carries. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
Rewritten based on web research into vibe coding pain points, AI app builder failures, and the disposable software trend. Leads with the concrete problems of AI-generated React (context drift, dependency hell, debugging someone else's code), then positions Tinkerdown's declarative format as the fix: constrained enough for reliable AI generation, small enough for humans to fully understand. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
There was a problem hiding this comment.
Pull request overview
This PR updates the project’s top-level documentation to better communicate Tinkerdown’s positioning (“Why Tinkerdown?”) and adds an animated demo asset to visually explain the markdown-to-app workflow.
Changes:
- Add a new animated SVG demo asset under
docs/assets/. - Embed the demo image near the top of the README.
- Introduce a new “Why Tinkerdown?” section with expanded product positioning in the README.
Reviewed changes
Copilot reviewed 1 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
docs/assets/demo.svg |
Adds an animated demo SVG illustrating authoring markdown and seeing a live app UI. |
README.md |
Embeds the demo SVG and adds a new “Why Tinkerdown?” positioning section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
PR ReviewThis is a clean documentation PR. The "Why Tinkerdown?" copy is sharp and well-targeted. A few things to note: Bug: Invalid SVG attribute on circle elementIn The current code is:
Minor: SMIL
|
- Remove invalid `y` attribute from circle element (only cx/cy/r valid) - Match clip path rx="10" to window frame border radius - Add timing comment to SMIL animation for maintainability - Improve alt text with descriptive content for accessibility https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
No description provided.