Subcomponent

Move one member of a component family into its own sibling doc without duplicating it in the parent.

Choose a separate doc

Start with a component family doc. Move one public member into a sibling doc when it has its own source and enough behavior, props, or usage guidance to maintain separately. The parent still lists the member, but only by name.

  • Keep a small member inline when its whole contract stays clear in the family doc.
  • Use a sibling doc when the member needs focused search results, examples, usage guidance, or independent maintenance.
  • Give each member one documentation owner. Do not keep a full parent entry and a sibling doc for the same name.

Reference it from the parent

components/AcmeDialog.doc.mjs
javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeDialog',
  displayName: 'Acme Dialog',
  usage: {description: 'Presents a focused task above the current page.'},
  components: [
    {
      name: 'AcmeDialog',
      displayName: 'Acme Dialog',
      description: 'Owns the modal surface and open state.',
      props: [],
    },
    {name: 'AcmeDialogHeader'},
  ],
};

The name-only entry keeps AcmeDialogHeader in the family. Its description and props come only from the sibling file.

Write the subcomponent doc

components/AcmeDialogHeader.doc.mjs
javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeDialogHeader',
  displayName: 'Acme Dialog Header',
  subComponentOf: 'AcmeDialog',
  description: 'Labels an Acme Dialog and holds its close action.',
  props: [
    {
      name: 'title',
      type: 'string',
      description: 'The dialog title.',
      required: true,
    },
  ],
};
FieldTypeRequiredDescription
subComponentOfstringnoSubComponentDoc variant (required there): the parent component's name (e.g. 'Chat'). Marks this file as a sub-component doc that inherits family fields (group, category, keywords, theming, playground) from the parent.
descriptionstringnoSubComponentDoc variant (required there): one-sentence description of the sub-component's role within the parent composition. Single/Multi docs have no top-level description; they derive their summary from usage.
propsComponentPropDoc[]noSingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.

From ComponentDoc: astryx docs authoring component-doc

  • subComponentOf must exactly match the parent doc's name.
  • description explains this member's role in the family. usage is optional; add it when the member needs guidance beyond that sentence.
  • The child inherits family fields such as group, category, keywords, theming, and playground unless it overrides them.