Single component

integration add component creates the normal doc for one public component. Keep the generated identity and import, then replace its sample text and props with the component's real public contract.

javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeCarousel',
  displayName: 'Acme Carousel',
  import: '@acme/astryx-widgets/components/AcmeCarousel',
  usage: {
    description:
      'Cycles through slides one at a time. Use it for a small set of related cards.',
  },
  props: [
    {
      name: 'slides',
      type: 'ReactNode[]',
      description: 'The slides to show, in order.',
      required: true,
    },
  ],
};

• Keep props on the top-level doc. Private implementation helpers do not need entries.
• Keep the doc beside the source and change both in the same pull request.
• If the module later exposes several related public exports, adapt this doc with astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family.

ComponentDoc: The doc-type for a component directory's {Name}.doc.mjs. A discriminated union of SingleComponentDoc (props on the doc), MultiComponentDoc (a components array), and SubComponentDoc (a subComponentOf pointer). All three share the ComponentBaseDoc fields below; the variant is chosen by which of props / components / subComponentOf you set. Read it with astryx docs authoring component-doc.

Write usage.description so a person or agent can decide whether this is the right component without opening its source. Say what it does, when to use it, and the most important boundary with a nearby alternative.

javascript
usage: {
  description:
    'Cycles through slides one at a time. Use it for a small set of related cards. Use a static list when every item should stay visible.',
  bestPractices: [
    {guidance: true, description: 'Keep the slide order stable while someone interacts with the carousel.'},
    {guidance: false, description: 'Hide information that must remain visible for comparison.'},
  ],
},

Copy the public prop names and types from the source. Explain the behavior a caller controls, not only the TypeScript type.

javascript
props: [
  {
    name: 'slides',
    type: 'ReactNode[]',
    description: 'The slides to show, in order.',
    required: true,
  },
  {
    name: 'interval',
    type: 'number',
    description: 'Milliseconds between automatic slide changes.',
    default: '5000',
  },
],

• Set required: true only when every caller must pass the prop.
• Write default exactly as the value should appear in documentation.
• Skip styling escape hatches such as xstyle, className, and style.

Add short examples for important usage that the prop table does not make obvious. Each example should teach one complete pattern and use only public imports.

javascript
examples: [
  {
    label: 'Automatic rotation',
    code: '<AcmeCarousel slides={slides} interval={5000} />',
  },
],

Read the component after every source or doc change. Confirm that its purpose, import, props, defaults, and examples match the source, then verify the packed package.

bash
npx astryx component AcmeCarousel
npx astryx integration verify