In a component library's documentation, why generate property tables from the source and render live examples instead of writing them by hand?
answer
- precise parts drift first
- read from the shipped source
- descriptions live in doc comments
- a broken example fails the build
- the what, not the when
basics
~20 sHand-copied property tables and pasted snippets go wrong the moment a property changes. Generated tables read names, types and defaults from the component's source, and examples the docs build renders turn API drift into a build failure.
solid answer
~50 sThe most drift-prone parts of a component page are the precise ones: the **property table** and the **code examples**. A **generated property table** is produced by the docs build from the component's source — names, types, defaults, whether each is required, and the **doc comment** beside each property — so it cannot disagree with the code the docs were built from. A **live example** is compiled and rendered by the docs build against the current component, so a renamed property breaks the build instead of leaving a snippet that silently lies, and a visual change shows up automatically. Generation guarantees accuracy, not quality: a blank doc comment produces a blank cell, so descriptions must be written in the source and reviewed with the property. And people still write the when and why — usage guidance, reasons, accessibility intent.
go deeper
Recall that generated tables come from the component's source and that live examples are rendered by the docs build, so neither can quietly describe an old API.
Explain what generation guarantees and what it does not — accuracy of names, types and defaults, but not description quality — and why descriptions belong in doc comments.
Show how you would make missing descriptions and broken examples fail review or the build, and choose realistic examples that expose real content edge cases.
Balance generated reference against authored guidance across web and native platforms, and decide what the docs own versus what the component workshop owns.
## Hand-maintained reference drifts first In a **component library** — the coded half of a design system, consumed by many product teams — the most drift-prone parts of any component page are the precise ones: the **property table** (every configurable input with its type, default and whether it is required) and the **code examples**. When they are copied by hand from the source, every rename, changed default or removed variant makes them wrong the moment the change merges, and nothing tells anyone. Prose guidance ages slowly; reference tables age with every release. ## Generated property tables A **generated property table** is produced by the docs build from the component's own source: names, types, defaults, required-ness and the **doc comments** written beside each property. Because it is read from the code the docs were built from, it cannot disagree with that code. - **What it guarantees**: the table matches the shipped surface — no missing property, no stale default, no removed variant still listed. - **What it does not guarantee**: good descriptions. The generator copies whatever comment is there; a blank comment produces a blank cell. - **Where descriptions belong**: in the source, beside each property, so writing one is part of adding the property and is reviewed with it. Patching descriptions into the generated page by hand recreates the drift the generator removed. - **Deprecation markers**: a property marked deprecated in the source can show as deprecated in the table automatically. ## Live rendered examples A **live example** is one whose code the docs build actually compiles and renders using the current version of the component, instead of a screenshot or a snippet pasted into the page. | After… | Screenshot or pasted snippet | Live rendered example | |---|---|---| | A property rename | Silently shows the old API | Fails the docs build | | A visual change | Shows the old look | Shows the new look | | Adding theme or density modes | One captured state | Can render each mode | | A reader copies the code | May no longer work | Known to work at that version | The first row matters most: **drift becomes a build error** instead of a reader's discovery. This holds only for examples the build really executes; a code block that is merely displayed as text is still a pasted snippet. ## Choosing examples that teach On a music-streaming app's design system, examples for the **track row** and the **album tile** earn their place when they show what real content does to the component: 1. A two-word track title and one long enough to wrap or truncate. 2. An album with no cover art, and a podcast episode three hours long. 3. Loading, empty and error states, not only the happy default. 4. One decision per example, so each one answers a single question. ## Checks worth adding to the docs build Once reference and examples come from the source, the docs build can act as a drift detector: - **Fail** when an example no longer compiles or renders against the current component. - **Warn** when a public property has no doc comment, so blank cells are caught in review rather than by readers. - **Flag** examples that still use a property marked deprecated, so the docs do not teach what the system is retiring. - **Check links** between pages, which break quietly whenever a page is renamed or removed. Each check is cheap, runs on every change and moves one kind of staleness from the reader's desk to the author's. ## What stays hand-written Generation covers the **what**. People still write the **when and why**: usage guidance, do / don't pairs with reasons, accessibility intent and content guidance. A page that is nothing but generated tables is accurate and unhelpful; a page that is nothing but prose is helpful until the first release after it was written. ## Across platforms Native mobile component libraries have their own sources, and the same approach applies: generate each platform's reference from that platform's source, and keep property names aligned across platforms where the concepts match, so shared guidance can refer to one name. Interactive playgrounds that let a reader adjust every property live belong to the component workshop, a separate tool from these reference pages; the docs page's job is an accurate, versioned reference with curated examples.
- The generated table shows blank descriptions for most properties; what is the right fix?Write the descriptions in the doc comments in the component source, where the generator reads them, and make a missing description a review comment or a build warning for new properties. Adding descriptions by hand on the docs page, or abandoning generation, would bring back the drift the generator exists to remove.
- Why is a docs build that renders every example slower to maintain, and why is that acceptable?Every breaking change to a component now also breaks its examples, so the author must update them before merging. That cost is the point: it is paid once, by the person who made the change and understands it, instead of by every reader who copies a broken snippet later.
A generated property table is like a station departure board fed by the signalling system instead of chalked up by hand: it cannot show a cancelled train as on time. But it still cannot tell you which train you should take — that is the usage guidance.
saying these in an interview costs you the question
- Generated property tables make hand-written usage guidance unnecessary.
- A screenshot of a component is as good as a rendered example.
- Blank descriptions are fine because property names explain themselves.
- A snippet pasted into the docs once stays valid across releases.
- Hand-editing a generated table is a safe way to fix its descriptions.