Skip to content

Externalize catalogue fundamental examples#377

Draft
IzumiSy wants to merge 3 commits into
mainfrom
chore/catalogue-fundamental-examples
Draft

Externalize catalogue fundamental examples#377
IzumiSy wants to merge 3 commits into
mainfrom
chore/catalogue-fundamental-examples

Conversation

@IzumiSy

@IzumiSy IzumiSy commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

Motivation

The catalogue's fundamental references 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 fundamental examples into real source files under catalogue/src/fundamental/examples/, updates the markdown to embed those files via <\!-- source: ... -->, and teaches the generator to resolve source markers for fundamental references too. With that in place, the examples now participate in catalogue type-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

  • externalize fundamental/components.md and fundamental/design-system.md TS/TSX examples into typed source files
  • resolve <\!-- source: ... --> markers for fundamental docs during catalogue skill generation
  • trim redundant component reference prose and update a few stale examples to match the current AppShell API

@IzumiSy IzumiSy requested a review from a team as a code owner July 9, 2026 07:53
@IzumiSy IzumiSy marked this pull request as draft July 9, 2026 07:54
Base automatically changed from fix/catalogue-skill-drift to main July 10, 2026 01:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant