---
name: catalyst-component-catalog
description: >
  Consume `@aurora/components` using `*.stories.ts` files as the canonical source of truth for
  component APIs, variants, and composition patterns. Trigger: Whenever composing or generating ANY
  screen, page, form, or dashboard that uses anything from `@aurora/components/`; when picking
  between candidate components for the same requirement; when answering "how do I use X component?"
  — EVEN IF the user doesn't mention "stories", "catalog", or "component docs" explicitly. If the
  task consumes `@aurora/components`, this skill fires. For AUTHORING new stories (adding or
  updating a component's story in `@aurora/components/`), use `catalyst-component-story-composer`
  instead — this skill is read-only over the catalog.
license: MIT
metadata:
  author: aurora
  version: '2.1'
---

## When to Use

- Composing or generating a screen that consumes anything from `@aurora/components`
- Choosing between multiple `@aurora/components` that could satisfy the same user requirement
- Answering "how does component X work?" or "what props does X take?"
- Working in **Solution mode** (consuming the platform), not Framework mode

**Skip this skill** when adding or modifying a component in `@aurora/components/` — that is authoring, covered by `catalyst-component-story-composer`.

## Mandatory Discovery Protocol

BEFORE writing any code that consumes an `@aurora/components` component, follow this protocol:

1. **Glob for matching stories**
   `Glob frontend/src/@aurora/components/**/*.stories.ts` — returns the full catalog.
2. **Read the candidate story file(s)**
   `Read` the `*.stories.ts` sibling of the component you plan to use. Lift from it:
   - The `Meta.component` (canonical import)
   - The `args` / `argTypes` (prop names, types, defaults, descriptions)
   - Named `StoryObj` exports (representative variants — your composition should reuse these patterns, not invent new ones)
   - The `parameters.aurora` metadata, if declared (see next section)
3. **Consume, do NOT re-derive**
   Write the usage by lifting prop names, slot shapes, and composition patterns from the story. Do not re-read the component source to "verify" prop names — the story is canonical.

### Why `*.stories.ts` and not the component source?

Story files encode **intended usage**: representative variants, argTypes with descriptions, prose in `parameters.docs.description.story`. Component `.ts` files document only what is syntactically possible. A component may accept 20 inputs; the story tells you which 3 are actually meaningful at the call site.

## Two-Tier Component Selection (when multiple candidates fit)

When you need to pick between two or more `@aurora/components` candidates:

**Tier 1 — Read `parameters.aurora` metadata (preferred)**
Each story MAY declare:

```ts
parameters: {
  aurora: {
    category: 'data-table' | 'navigation' | 'form' | ...,
    when: 'one-sentence description of the primary use case',
    whenNot: 'one-sentence description of when a different component is the better choice, naming that alternative',
  },
},
```

When present, `when` and `whenNot` disambiguate candidates explicitly. Prefer this signal over inference — it is authored by the component owner.

**Tier 2 — Fall back to title / argTypes inference**
If `parameters.aurora` is absent on the candidate(s), infer from:

- `Meta.title` (e.g. `@aurora/components/data-table/table-search` hints at data-table scope)
- `argTypes` descriptions
- Story names (e.g. `FastDebounce`, `TranslatedPlaceholder`)

Flag to the user that metadata was missing — this indicates the catalog entry is incomplete. Tier-2 inference is explicitly degraded.

## Escalation: Undocumented Component

If you need to use an `@aurora/components` export but `Glob frontend/src/@aurora/components/**/*.stories.ts` returns no matching story:

1. **DO NOT** infer usage from the component source and ship code silently.
2. **FLAG THE GAP** to the user: name the component and state that its story is missing.
3. **DELEGATE the authoring**: hand off to `catalyst-component-story-composer` (or propose it to the user) BEFORE consuming the component. That skill owns the authoring convention and Generator Mode procedure.

This rule exists because silently inferred usage is the primary source of drift between generated modules and the `@aurora/` platform layer.

## Related Skills

- **`catalyst-component-story-composer`** — sibling skill for **authoring** stories when a component has no documentation or needs an update. Fires in Framework mode; this one fires in Solution mode.
- `layout-design-system` — spacing/density rules that apply when composing the screens that consume these components.
- `transloco-i18n` — for stories that demonstrate translated content.
- `catalyst-data-table-management` — specific patterns for the `data-table` family; this skill handles the broader catalog discovery loop.
