Authoring Reference

The astryx.integration.* manifest that sits beside an integration package's package.json. It can preserve a stable provider identity across a package rename, and points the CLI at the package's components, templates, codemods, doc topics, source themes, managed agent guidance, and issue tracker. Every field is optional.

Applies to: astryx.integration.{ts,mjs,js}

js
export default {
  components: './src/components',
  templates: './src/templates',
  codemods: './codemods',
  docs: './docs',
  themes: './themes',
  agentDocs: {
    append: ['Run acme verify before finishing.'],
  },
  issuesUrl: 'https://github.com/acme/widgets/issues',
};

Provider identity defaults to package.json#name. During an explicit package rename, set providerId to the prior canonical package name so existing artifact IDs remain stable. Package version always comes from package.json.

agentDocs.append may contain at most eight lines. Each line is a trimmed, non-blank string of at most 240 Unicode code points with no line separators, control characters, NUL, or Astryx/XDS managed-marker text. The configured project may contain at most 32 integration lines total.

A themes root is forward-compatible but version-gated: a CLI released before this field ignores it with a warning and continues loading every contribution kind it understands. That older CLI cannot list or add the contributed themes.

Validate the manifest with astryx doctor integration validate. At the load boundary, a known field of the wrong type is an error, issuesUrl must be a valid URL, and unknown fields become warnings so an older CLI can still load the fields it understands. Before publishing, also run templates, components, and docs under the same doctor integration group. Those leaves compare authored identities with Core and explain whether an overlap is intentional or needs a rename.

The optional astryx.config.* file at your project root. Declares which integrations to load, where to route issue links, post-codemod hooks, local debug-log and gap-report handlers, and experimental layout components. All optional; {} is valid.

Applies to: astryx.config.{ts,mjs,js}

js
export default {
  integrations: ['@acme/astryx-widgets'],
};

js
export default {
  debug: event => appendFileSync("runs.ndjson", JSON.stringify(event) + "\n"),
};

The config is validated at load with a strict schema: unknown keys are errors, so a typo fails fast rather than being silently ignored.

A codemod module the CLI runs during astryx upgrade. Default-export a plain object with a type discriminant: 'code' rewrites source files, 'config' rewrites the astryx.config.* file. There is no factory to call.

Applies to: the codemods/ dir of an integration

js
export default {
  type: 'code',
  title: 'Rename Button prop kind to variant',
  fileExtensions: ['.tsx', '.ts'],
  transform(file, api) {
    const j = api.jscodeshift;
    const root = j(file.source);
    // ...rewrite the AST...
    return root.toSource();
  },
};

js
export default {
  type: 'config',
  title: 'Move issuesUrl into astryx.config',
  transform(file, api) {
    // Rewrite the astryx.config.* source; return null to skip.
    return null;
  },
};

The config-codemod variant (type: 'config') carries the same fields as a code codemod except fileExtensions: it always targets the astryx.config.* file rather than a set of source files.

Authors write a plain object and default-export it with the type discriminant; there is no factory. The CLI validates it at the load boundary via parseCodemod with a strict schema, and isOptional defaults to false.

Separates stable provider/artifact identity from package instances and runtime lifecycle state.

Applies to: Compiler inputs, manifests, search, Build, and Doctor

Provider package renames require an explicit mapping: a ProviderInstance may retain its stable providerId while packageName changes. Silent identity changes are not inferred.

Optional placement, compatibility aliases, and audience fields shared by every authored documentation kind.

Applies to: Every supported .doc.mjs object

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.

Applies to: {Name}.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
  name: 'Switch',
  displayName: 'Switch',
  category: 'Form Controls',
  keywords: ['toggle', 'switch', 'on off'],
  usage: {
    description:
      'A Switch toggles a single setting on or off. Use it for instant, binary preferences that apply immediately without a submit step.',
    bestPractices: [
      {guidance: true, description: 'Apply the change immediately when toggled.'},
      {guidance: false, description: 'Use a Switch for actions that need confirmation; prefer a Checkbox in a form.'},
    ],
  },
  props: [
    {name: 'isSelected', type: 'boolean', description: 'Whether the switch is on.', required: true},
    {name: 'onChange', type: '(isSelected: boolean) => void', description: 'Called when the user toggles the switch.'},
    {name: 'isDisabled', type: 'boolean', description: 'Prevents interaction and dims the control.', default: 'false'},
  ],
};

js
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
  name: 'Table',
  displayName: 'Table',
  category: 'Table & List',
  usage: {description: 'Displays rows and columns of data. Compose the sub-components to build headers, rows, and cells.'},
  components: [
    {name: 'Table', displayName: 'Table', description: 'The table container.', props: []},
    {name: 'TableRow', displayName: 'Table Row', description: 'A row within the table body.', props: [
      {name: 'isSelected', type: 'boolean', description: 'Highlights the row as selected.'},
    ]},
    {name: 'useTableSelection', displayName: 'useTableSelection', description: 'Manages row selection state.',
      params: [{name: 'rows', type: 'T[]', description: 'The rows to track.', required: true}],
      returns: [{name: 'selectedIds', type: 'Set<string>', description: 'Currently selected row ids.'}]},
  ],
};

ComponentDoc is a discriminated union of three shapes that all extend ComponentBaseDoc. Pick the variant by which key you set: props (single), components (multi), or subComponentOf (sub).

• SingleComponentDoc: one primary component; put props directly on the doc via props. Use for Switch, Badge, Spinner, TextInput.
• MultiComponentDoc: a directory exporting several components/hooks; list them in components (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.
• SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set subComponentOf to the parent name. It inherits family fields and may omit usage.

js
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
  name: 'ChatComposer',
  displayName: 'Chat Composer',
  subComponentOf: 'Chat',
  description: 'The message input row within a Chat, with an editor and send affordance.',
  props: [
    {name: 'onSend', type: '(text: string) => void', description: 'Called when the user submits a message.', required: true},
  ],
};

The stamped format is export default { type: 'component', ... }; legacy docs use export const docs = {...} and omit type (the parser shape-sniffs). A hook that is part of a component API is documented as a ComponentEntry in a MultiComponentDoc components array (with params/returns), not as a standalone HookDoc.

The doc-type for a standalone React hook (e.g. useMediaQuery, useFocusTrap, useOverflow) that gets its own .doc.mjs. Hooks that are part of a component API (e.g. useImperativeDialog) belong in that component's MultiComponentDoc components array instead. HookDoc is the hook-flavored view of the shared type: 'function' kind.

Applies to: {useX}.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
export const docs = {
  type: 'function',
  name: 'useMediaQuery',
  displayName: 'useMediaQuery',
  importPath: '@astryxdesign/core/hooks',
  params: [
    {name: 'query', type: 'string', description: 'A CSS media query, e.g. "(min-width: 768px)".', required: true},
  ],
  returns: [
    {name: 'matches', type: 'boolean', description: 'Whether the query currently matches.'},
  ],
  usage: {
    description:
      'Subscribes to a CSS media query and re-renders when it changes. Use for responsive behavior that CSS alone cannot express, such as swapping components by breakpoint.',
  },
  relatedHooks: ['useIsMobile'],
};

A hook's discriminant is type: 'function': HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named returns fields and a required usage block.

Only standalone hooks get their own file. A hook that is part of a component API is documented as an entry in that component's MultiComponentDoc components array (with params/returns), so it renders under the component.

The generalized type: 'function' doc-type covering both React hooks and CLI/API functions. A hook (HookDoc) is the hook-flavored view of this same kind; FunctionDoc adds the fields an API function needs (a {type, data} return envelope, thrown error codes, the wrapping CLI command). The CLI binding itself lives in a separate CommandDoc.

Applies to: api/<name>/<name>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
export const doc = {
  type: 'function',
  kind: 'api',
  name: 'search',
  displayName: 'search()',
  namespace: 'cli/api',
  importPath: '@astryxdesign/cli/api',
  summary: 'Find components, hooks, docs, and templates by term.',
  signature: 'search(query, options?): Promise<SearchResponse>',
  params: [
    {name: 'query', type: 'string', description: 'The search term.', required: true},
    {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template'", description: 'Restrict results to one domain.'},
  ],
  returns: [
    {type: 'search', description: 'Envelope with the query and ranked results[].'},
  ],
  throws: [
    {code: 'ERR_INVALID_ARGUMENT', when: 'query is empty.'},
  ],
  examples: [
    {label: 'Basic', code: "await search('button')", result: "{ type: 'search', data: { results: [...] } }"},
  ],
  command: 'search',
};

The type discriminant is 'function' for both flavors. Set kind: 'hook' or kind: 'api' to drive docsite sectioning; it is inferred from importPath when omitted.

The two flavors differ in returns: a hook lists named fields (name set), while an API function lists {type, data} envelope entries whose type is the response discriminant and whose name is omitted. throws (keyed to ERROR_CODES) applies to API functions.

The function does not know it has a CLI. The terminal binding (args, flags, exit codes) lives in a separate CommandDoc that references this function via fn; here you only note the wrapping command name via command.

The doc-type for a CLI command: the terminal binding of an operation. A command is not its own behavior; it is a FunctionDoc exposed on the CLI, referenced via fn, carrying only CLI-surface facts (args, flags, subcommands, examples, exit codes). A defineCommand converter turns it into Commander config + --help.

Applies to: clients/cli/commands/<name>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
export const doc = {
  type: 'command',
  name: 'search',
  displayName: 'astryx search',
  summary: 'Find components, hooks, docs, and templates.',
  namespace: 'cli',
  fn: 'search',
  args: [{name: 'query', param: 'query', required: true}],
  options: [
    {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook', 'doc', 'template']},
    {flag: '--json', cliOnly: true, description: 'Emit the typed JSON envelope.'},
  ],
  examples: [{label: 'Terminal', cli: 'astryx search button --json'}],
  exitCodes: [{code: 1, when: 'The --type value is not a known domain.'}],
  related: ['discover'],
};

A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via fn; the function does not know it has a CLI.

Bind an arg/option to a function param via param so it inherits that param's description. Use cliOnly: true for flags with no function param (e.g. --json); those must supply their own description.

The doc-type for a closed vocabulary: a fixed set of literal values such as error codes or response-type discriminants. Colocated as a .doc.mjs next to the source of truth it documents.

Applies to: <enum>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').EnumDoc} */
export const doc = {
  type: 'enum',
  name: 'error-codes',
  displayName: 'Error Codes',
  namespace: 'cli',
  description: 'Stable error codes thrown by the CLI/API and surfaced in the JSON envelope.',
  members: [
    {value: 'ERR_UNKNOWN_TOPIC', description: 'The requested docs topic does not exist.'},
    {value: 'ERR_INVALID_ARGUMENT', description: 'A required argument was missing or malformed.'},
    {value: 'ERR_LEGACY', description: 'Old alias.', deprecated: 'Use ERR_INVALID_ARGUMENT.'},
  ],
};

An enum doc is the human-readable mirror of a closed vocabulary defined elsewhere in source (e.g. an ERROR_CODES map or a response-type union). Keep the members in sync with that source of truth.

Mark a value with deprecated (a migration hint) rather than deleting it, so old codes stay documented while readers are pointed at the replacement.

Declares named navigation slots and renderer-neutral layout blocks for already-discovered docs. It never scans folders or copies child documents.

Applies to: <namespace>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
  type: 'namespace',
  name: 'cli',
  title: 'Astryx CLI',
  summary: 'Commands, APIs, and integration authoring.',
  slots: {
    guides: {title: 'Guides', accepts: {kinds: ['namespace', 'generic']}},
    reference: {
      title: 'Reference',
      accepts: {kinds: ['namespace', 'command']},
    },
  },
  adopts: [{
    source: {group: 'cli-commands', kinds: ['command']},
    into: 'reference',
  }],
  blocks: [
    {type: 'collection', source: {slot: 'guides'}, presentation: 'cards'},
    {type: 'collection', source: {slot: 'reference'}, presentation: 'compact'},
  ],
};

Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.

The doc-type for a reference/topic doc: tokens, principles, theming, patterns, accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: drop a .doc.mjs in the docs directory and it shows up in astryx docs. Content is built from ordered sections of mixed content blocks.

Applies to: assets/docs/<topic>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export const docs = {
  type: 'generic',
  name: 'spacing',
  title: 'Spacing',
  description: 'Spacing tokens for gap, margin, and padding.',
  category: 'foundations',
  tokenCategory: 'spacing',
  sections: [
    {
      title: 'Spacing Tokens',
      content: [
        {type: 'prose', text: 'Use spacing tokens instead of raw pixel values so layouts stay on the 4px grid.'},
        {type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']]},
      ],
      previewType: 'spacing-bar',
    },
  ],
};

Each sections[].content is an ordered array of ReferenceContentBlock, a discriminated union. V1 adds only workflow, collection, and reference; choice, callout, and checklist remain invalid. The same union is reused by the notes field on SchemaDoc and CommandDoc.

ts
type ReferenceContentBlock =
  | { type: 'prose'; text: string }
  | { type: 'heading'; level: 3 | 4 | 5 | 6; text: string }
  | { type: 'code'; lang: string; code: string; label?: string }
  | { type: 'table'; headers: string[]; rows: string[][] }
  | { type: 'list'; style: 'ordered' | 'unordered' | 'do' | 'dont'; items: string[] }
  | { type: 'token-ref'; topic: string; section: string }
  | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
  | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
  | { type: 'reference'; target: string; projection?: {fields?: string[]; sections?: string[]} };

A token-ref block (e.g. {type: 'token-ref', topic: 'tokens', section: 'Color Tokens'}) references a token table in another topic; the CLI resolves and inlines it at read time so the docsite can render live theme values.

A section may set previewType to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.

The doc-type for documenting an authored/received OBJECT shape (astryx.config, a codemod payload, the doc-types themselves). Colocated as a .doc.mjs next to the schema it describes. Fields nest recursively, so a whole shape is one tree.

Applies to: <schema>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
export const doc = {
  type: 'schema',
  name: 'integration',
  displayName: 'Astryx Integration',
  namespace: 'cli',
  description: 'The astryx.integration.* manifest that registers the components a package provides.',
  appliesTo: 'astryx.integration.{ts,mjs,js}',
  fields: [
    {name: 'name', type: 'string', description: 'Package name.', required: true},
    {
      name: 'components',
      type: '{ dir: string }',
      description: 'Where component sources live.',
      fields: [
        {name: 'components.dir', type: 'string', description: 'Glob root for XDS*.tsx files.', required: true},
      ],
    },
  ],
};

SchemaFieldDoc is recursive: an object-typed field lists its members in its own fields, so an entire nested shape (including paths like hooks.postCodemod or experimental.xle.components) is documented as one tree.

Name nested fields with a dotted path from the root (e.g. hooks.postCodemod) so readers can see where each field sits in the shape.

The doc-type for template metadata. A discriminated union of PageTemplateDoc (type: 'page') for full page templates and BlockTemplateDoc (type: 'block') for editable compositions. A block can stand alone or use exampleFor to attach to one component; isShowcase requires that component ownership.

Applies to: <Name>.template.mjs

js
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export const doc = {
  type: 'page',
  name: 'Dashboard',
  displayName: 'Dashboard',
  description: 'An analytics dashboard with KPI cards and charts.',
  category: 'Dashboard - Analytics',
  isReady: true,
};

js
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export const doc = {
  type: 'block',
  name: 'ButtonGroupExample',
  displayName: 'Button Group Example',
  description: 'A row of related buttons showing primary and secondary actions.',
  exampleFor: 'Button',
  aspectRatio: 16 / 9,
  componentsUsed: ['Button', 'HStack'],
  isShowcase: true,
};

TemplateDoc is a discriminated union keyed by type. Set type: 'page' for a full page template. Set type: 'block' for an editable composition; add exampleFor only when one component owns the example.

• PageTemplateDoc (type: 'page'): a full page template; name doubles as its display value.
• BlockTemplateDoc (type: 'block'): an editable composition. exampleFor is optional component ownership; omit it for a standalone block. isShowcase requires exampleFor.

category uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template; unused values are reserved so authors get autocomplete for the full taxonomy.