Externalize catalogue fundamental examples#377
Draft
IzumiSy wants to merge 3 commits into
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The catalogue's
fundamentalreferences had many inline TS/TSX snippets that were copied directly into the generated skill docs but were not type-checked anywhere. That made the examples easy to drift out of sync with the real AppShell API, and it also duplicated some information that the examples already showed themselves.This change moves the
fundamentalexamples into real source files undercatalogue/src/fundamental/examples/, updates the markdown to embed those files via<\!-- source: ... -->, and teaches the generator to resolve source markers forfundamentalreferences too. With that in place, the examples now participate incataloguetype-checking instead of living as unchecked markdown-only snippets.Design Decision
The smallest reliable approach was to keep markdown as the prose layer and make the examples the source of truth.
Instead of trying to type-check fenced markdown blocks directly, the change externalizes each TS/TSX example into a standalone file and re-embeds it during skill generation. That keeps the generated documentation readable while making the examples maintainable and verifiable. As part of that cleanup, the component reference prose drops redundant
**Import:**lines so the examples themselves remain the only import source of truth.Summary
fundamental/components.mdandfundamental/design-system.mdTS/TSX examples into typed source files<\!-- source: ... -->markers forfundamentaldocs during catalogue skill generation