Explain when and how a component should be used
A component needs more than a name. Its specification explains its purpose, when it fits, the inputs it accepts and how its registered implementations relate to that contract.
Wildo makes this guidance available to development tools and language generation. Application authors can understand a component’s intended use before composing or extending it.
Example — Choose a card for the right reason
A summary card’s specification describes its header, content and action regions, and suggests where that grouping helps. A builder can choose it for a customer snapshot rather than guessing from its export name.
For engineers
The framework’s card specification uses frontendComponentSpecification and names the same LOW_LEVEL_CARD reference used by the runtime. This selected source captures its authoring guidance:
componentId: 'framework.low-level.card',
purpose:
'Group related content with header, title, description, actions, and body regions in a surfaced container.',
uiRole:
'Compound card shell: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`.',
useWhen:
'Use for summaries, entity snapshots, dashboard tiles, and form sections that need a clear boundary.',
avoidWhen:
'Avoid nesting many interactive cards inside tiny lists without spacing; consider table rows instead.',
compositionNotes: [
'Sub-components are separate exports that share the same registry preset.',
],
The same specification records CardProps, its preset vocabulary, a compound-card usage example and the implementation/registration symbols. Those connections matter: guidance for an old prop or nonexistent preset would mislead the next author even if the prose sounded useful.
Publish the specification to its consumers
An application-owned specification belongs in its specifications package and must be included in the frontendComponentSpecifications companion export. Wonder Todos already publishes the framework’s specification map there. The companion’s component-specification context factory and labelling context loader read that map to provide component meaning and prop information.
| Record | Responsibility |
|---|---|
| Runtime registration | Makes a component implementation available to its callers |
| Component specification | Explains that contract and the intended use of its presets |
| Label declaration and generated bundle | Defines the wording keys and supplies their values |
Writing a specification does not register the React implementation. Keep those separate connections aligned when adding a custom slot or preset. Include a useful composition example and explain constraints that a caller must respect; changing only the visual recipe generally belongs in the theme configuration rather than a new component specification.