Component Catalogue

LLM-first developer tool for generating Component Catalogues

View the Project on GitHub adieyal/component-catalogue

Creating Components

The fastest way to create a new component:

catalogue new <component-id> [options]

Options

Option Description
-t, --title <title> Human-readable title
-s, --status <status> stable, beta, or deprecated
-k, --kind <kind> standalone, subcomponent, or feature

Examples

# Basic component
catalogue new user-card

# With options
catalogue new data-table --title "Data Table" --status stable

# Subcomponent
catalogue new table-row --kind subcomponent

This creates:

registry/components/user-card/
├── component.json
├── docs.md
└── scenarios/
    └── default.json

src/components/
└── user-card.ts

Manual Creation

1. Create Component Directory

mkdir -p registry/components/my-button/scenarios

2. Create component.json

{
  "id": "my-button",
  "title": "My Button",
  "status": "stable",
  "kind": "standalone",
  "description": "A customizable button component",
  "tags": ["form", "action", "interactive"],
  "exports": {
    "customElement": "my-button"
  },
  "playground": {
    "primaryScenarioId": "my-button-default",
    "controls": {
      "variant": {
        "type": "select",
        "label": "Variant",
        "defaultValue": "primary",
        "options": ["primary", "secondary", "danger"]
      },
      "size": {
        "type": "select",
        "label": "Size",
        "options": ["small", "medium", "large"]
      },
      "disabled": {
        "type": "boolean",
        "label": "Disabled"
      }
    }
  }
}

3. Create Default Scenario

Create scenarios/default.json:

{
  "id": "my-button-default",
  "title": "Default",
  "description": "Default button state",
  "componentId": "my-button",
  "primary": true,
  "render": {
    "element": "my-button",
    "attrs": {
      "variant": "primary",
      "size": "medium"
    },
    "slots": {
      "default": "Click me"
    }
  }
}

4. Create Documentation (Optional)

Create docs.md:

# My Button

A customizable button component for user interactions.

## Usage

\`\`\`html
<my-button variant="primary">Click me</my-button>
\`\`\`

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| variant | string | primary | Visual style |
| size | string | medium | Button size |
| disabled | boolean | false | Disabled state |

5. Create Web Component

Create src/components/my-button.ts:

export class MyButton extends HTMLElement {
  static get observedAttributes() {
    return ['variant', 'size', 'disabled'];
  }

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  private render() {
    const variant = this.getAttribute('variant') || 'primary';
    const size = this.getAttribute('size') || 'medium';
    const disabled = this.hasAttribute('disabled');

    this.shadowRoot!.innerHTML = `
      <style>
        /* Your styles here */
      </style>
      <button class="${variant} ${size}" ${disabled ? 'disabled' : ''}>
        <slot></slot>
      </button>
    `;
  }
}

customElements.define('my-button', MyButton);

6. Export Component

Add to src/components/index.ts:

export * from './my-button.js';

7. Validate

catalogue validate

component.json Reference

Required Fields

Field Type Description
id string Unique kebab-case identifier
title string Human-readable name
status string stable, beta, or deprecated
kind string standalone, subcomponent, or feature
exports.customElement string Custom element tag name
playground.primaryScenarioId string Default scenario ID
playground.controls object Control definitions

Optional Fields

Field Type Description
description string Brief description
tags string[] Searchable tags
parentId string Parent component (for subcomponents)
subcomponents string[] List of subcomponent IDs
exports.package string npm package name
exports.entry string Entry point path

Next Steps