@adieyal/catalogue-cli 0.1.0

package/skills/document-component.md

@@ -0,0 +1,83 @@
+# Document Component
+
+Generate or improve documentation for a component by analyzing its source code.
+
+## Arguments
+
+- `$ARGUMENTS` - Component ID (e.g., `button`)
+
+## Instructions
+
+1. Parse component ID from `$ARGUMENTS`. If empty, list components in `registry/components/` and ask user to choose.
+
+2. Read the component source file at `src/components/<id>.ts` (or `.js`).
+
+3. Analyze the source code to extract:
+   - `static observedAttributes` → Properties
+   - Getter/setter pairs → Properties with types
+   - `<slot>` elements → Available slots
+   - `this.dispatchEvent()` calls → Events
+   - Any JSDoc comments
+
+4. Read existing docs at `registry/components/<id>/docs.md`.
+
+5. Read `registry/components/<id>/component.json` for title and description.
+
+6. Generate improved documentation:
+
+```markdown
+# <Component Title>
+
+<description from component.json>
+
+## Usage
+
+\`\`\`html
+<<component-id> [key-attributes]>
+  [typical slot content]
+</<component-id>>
+\`\`\`
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| <attr> | <type> | <default> | <description> |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| <name> | <description> |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| <name> | <type> | <description> |
+
+## Examples
+
+### <Example Name>
+
+\`\`\`html
+<example code>
+\`\`\`
+
+## Accessibility
+
+<accessibility notes based on component type>
+
+## See Also
+
+- [Related Component](./related.md)
+```
+
+7. Show the user the generated docs and ask if they want to:
+   - Replace existing docs entirely
+   - Merge with existing docs
+   - Just see the output without saving
+
+8. If saving, write to `registry/components/<id>/docs.md`.
+
+9. Suggest creating scenarios for any documented states/variants not yet covered.

package/skills/migrate-library.md

@@ -0,0 +1,193 @@
+# Migrate Existing Component Library
+
+Guide migration of an existing component library to use the catalogue.
+
+## Arguments
+
+- `$ARGUMENTS` - Optional: path to components directory (e.g., `src/components`)
+
+## Instructions
+
+Follow this phased approach. Do NOT try to "port everything" at once.
+
+### Phase 1: Assess the Library
+
+1. If `$ARGUMENTS` provided, scan that directory. Otherwise, look for common patterns:
+   - `src/components/`
+   - `lib/components/`
+   - `packages/*/src/`
+
+2. List all components found (custom elements, web components, or framework components).
+
+3. Check how components are currently registered:
+   - Side-effect registration on import?
+   - Manual `customElements.define()` calls?
+   - Framework-specific registration?
+
+4. Check for existing:
+   - Design tokens (CSS variables, JSON tokens, SCSS)
+   - Theme support (light/dark)
+   - Documentation (README, Storybook, etc.)
+   - Demo pages
+
+5. Report findings to user before proceeding.
+
+### Phase 2: Create Registration Entrypoint
+
+Create `src/register-all.ts` (or similar) that imports all components:
+
+```typescript
+// Auto-generated component registration
+import './components/button/button';
+import './components/card/card';
+// ... etc
+```
+
+If components are already side-effect registered:
+```typescript
+export * from './components/button';
+export * from './components/card';
+```
+
+Update `catalogue.config.ts` to point to this entrypoint.
+
+### Phase 3: Generate Seed Registry
+
+For EACH component, create minimal registry files:
+
+1. `registry/components/<id>/component.json`:
+```json
+{
+  "id": "<kebab-case-id>",
+  "title": "<Title Case>",
+  "status": "beta",
+  "kind": "standalone",
+  "description": "<from existing docs or infer from code>",
+  "tags": [],
+  "playground": {
+    "primaryScenarioId": "<id>-default"
+  }
+}
+```
+
+2. `registry/components/<id>/scenarios/default.json`:
+```json
+{
+  "id": "<id>-default",
+  "componentId": "<id>",
+  "title": "Default",
+  "description": "Primary appearance",
+  "render": {
+    "element": "<element-tag-name>",
+    "slots": {
+      "default": "Content"
+    }
+  }
+}
+```
+
+3. `registry/components/<id>/docs.md`:
+```markdown
+# <Title>
+
+<existing description or TODO>
+
+## Usage
+
+\`\`\`html
+<<element-tag>></<element-tag>>
+\`\`\`
+```
+
+### Phase 4: Wire Up Design Tokens
+
+Ask user about their token setup:
+- CSS variables in a .css file?
+- JSON/YAML tokens compiled to CSS?
+- SCSS variables?
+- Multiple themes (light/dark)?
+
+Update `catalogue.config.ts`:
+
+```typescript
+export default {
+  // ...existing config
+  themes: {
+    default: 'light',
+    available: ['light', 'dark'],
+    tokenCss: {
+      light: './src/tokens/tokens-light.css',
+      dark: './src/tokens/tokens-dark.css',
+    }
+  }
+}
+```
+
+Ensure the catalogue shell loads tokens at the root level so components inherit CSS variables.
+
+### Phase 5: Add Critical Variants
+
+For each component, add 2-5 scenarios max covering:
+- Default/primary state
+- Disabled/loading (if applicable)
+- Dense case (long labels, overflow)
+- Responsive stress (narrow container)
+- Dark mode variant
+
+Do NOT create scenarios for every prop combination.
+
+### Phase 6: Establish Hierarchy
+
+Review components and set appropriate `kind`:
+- `standalone` - User-facing, top-level components
+- `subcomponent` - Internal pieces (add `parentId`)
+- `feature` - Complex composites (or use Examples instead)
+
+### Phase 7: Validate and Test
+
+Run:
+```bash
+npx catalogue validate
+npx catalogue dev
+```
+
+Verify:
+- All components render in harness
+- Tokens apply correctly
+- No console errors
+
+### Migration Tips
+
+**Components requiring app context (stores/router/i18n):**
+- Create wrapper scenarios that provide context
+- Keep wrappers shared and few
+
+**Components that fetch data:**
+- Add prop to accept data directly
+- Or create "static mode" scenarios
+- Scenarios must NOT make network calls
+
+**CSS/theme dependencies:**
+- Load same global CSS the app uses
+- Otherwise screenshots won't match reality
+
+**Container queries vs media queries:**
+- Recommend container queries for component internals
+- The catalogue resizer tests container width, not viewport
+- Set `container-type: inline-size` on preview frame
+
+### What "Done" Looks Like
+
+- [ ] Every component has a primary scenario
+- [ ] Key components have 3-5 variants
+- [ ] Playground works for top 20% of components
+- [ ] CI catches visual regressions
+- [ ] Old demo pages can be deleted
+
+### Report to User
+
+After migration, summarize:
+- Components migrated: X
+- Scenarios created: Y
+- Components needing manual attention (complex setup, network deps, etc.)
+- Suggested next steps

package/skills/new-component.md

@@ -0,0 +1,98 @@
+# Create New Component
+
+Create a new component entry in the catalogue registry.
+
+## Arguments
+
+- `$ARGUMENTS` - Component ID (kebab-case, e.g., `user-avatar`)
+
+## Instructions
+
+1. Parse the component ID from `$ARGUMENTS`. If empty, ask the user for a component ID (must be kebab-case).
+
+2. Derive the component title by converting kebab-case to Title Case (e.g., `user-avatar` → `User Avatar`).
+
+3. Ask the user:
+   - What is the component's purpose/description?
+   - What status? (stable, beta, deprecated) - default: beta
+   - What kind? (standalone, subcomponent, feature) - default: standalone
+   - What tags apply? (e.g., form, layout, navigation, feedback)
+
+4. Create the directory structure:
+   - `registry/components/<id>/`
+   - `registry/components/<id>/scenarios/`
+
+5. Create `registry/components/<id>/component.json`:
+
+```json
+{
+  "id": "<component-id>",
+  "title": "<Component Title>",
+  "status": "<status>",
+  "kind": "<kind>",
+  "description": "<description>",
+  "tags": [<tags>],
+  "playground": {
+    "primaryScenarioId": "<component-id>-default"
+  }
+}
+```
+
+6. Create `registry/components/<id>/docs.md`:
+
+```markdown
+# <Component Title>
+
+<description>
+
+## Usage
+
+\`\`\`html
+<<component-id>></<component-id>>
+\`\`\`
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| default | Main content |
+```
+
+7. Create `registry/components/<id>/scenarios/default.json`:
+
+```json
+{
+  "id": "<component-id>-default",
+  "componentId": "<component-id>",
+  "title": "Default",
+  "description": "Default appearance",
+  "render": {
+    "element": "<component-id>",
+    "slots": {
+      "default": "Content"
+    }
+  }
+}
+```
+
+8. Create `src/components/<id>.ts` with a Web Component class:
+   - Class name: PascalCase version of the ID (e.g., `user-avatar` → `UserAvatar`)
+   - Use Shadow DOM with `mode: 'open'`
+   - Include basic styles and a slot
+
+9. Update `src/components/index.ts` to add:
+```typescript
+export * from './<component-id>.js';
+```
+
+10. Run `npx catalogue validate` to verify.
+
+11. Tell the user what was created and suggest:
+    - Adding properties to the component
+    - Creating more scenarios
+    - Updating the docs

package/skills/new-scenario.md

@@ -0,0 +1,56 @@
+# Create New Scenario
+
+Add a new scenario to an existing component.
+
+## Arguments
+
+- `$ARGUMENTS` - Format: `<component-id> <scenario-name>` (e.g., `button disabled`)
+
+## Instructions
+
+1. Parse arguments from `$ARGUMENTS`:
+   - First word: component ID
+   - Remaining words: scenario name
+   - If missing, ask the user for component ID and scenario name
+
+2. Verify the component exists at `registry/components/<component-id>/component.json`. If not, list available components and ask user to choose.
+
+3. Generate scenario ID: `<component-id>-<scenario-name-kebab>` (e.g., `button-disabled`)
+
+4. Ask the user:
+   - Brief description of this scenario
+   - What attributes/properties should be set?
+   - What slot content should be shown?
+   - Any custom viewport size? (optional)
+   - Any custom background color? (optional)
+
+5. Create `registry/components/<component-id>/scenarios/<scenario-name-kebab>.json`:
+
+```json
+{
+  "id": "<scenario-id>",
+  "componentId": "<component-id>",
+  "title": "<Scenario Title>",
+  "description": "<description>",
+  "render": {
+    "element": "<component-id>",
+    "attributes": {
+      // based on user input
+    },
+    "slots": {
+      "default": "<slot content>"
+    }
+  }
+}
+```
+
+Include optional fields only if provided:
+- `"viewport": { "width": <w>, "height": <h> }`
+- `"background": "<color>"`
+
+6. Run `npx catalogue validate` to verify.
+
+7. Tell the user:
+   - Scenario created at `registry/components/<id>/scenarios/<name>.json`
+   - View it at `http://localhost:5173/#/harness/<scenario-id>`
+   - Suggest running `npm run catalogue` to see it

package/skills/setup-tokens.md

@@ -0,0 +1,148 @@
+# Setup Design Tokens
+
+Configure design tokens for the catalogue so components render with correct styling.
+
+## Arguments
+
+- `$ARGUMENTS` - Optional: path to tokens file (e.g., `src/tokens/tokens.css`)
+
+## Instructions
+
+### Step 1: Identify Token Source
+
+If `$ARGUMENTS` provided, use that path. Otherwise, search for:
+- `**/tokens.css`, `**/tokens*.css`
+- `**/variables.css`, `**/vars.css`
+- `**/theme.css`, `**/themes/*.css`
+- `**/design-tokens.json`, `**/tokens.json`
+
+Ask user to confirm or provide the correct path.
+
+### Step 2: Determine Token Format
+
+Identify the format:
+- **CSS Variables**: `:root { --color-primary: #3b82f6; }`
+- **JSON Tokens**: `{ "color": { "primary": { "value": "#3b82f6" } } }`
+- **SCSS Variables**: `$color-primary: #3b82f6;`
+
+For JSON/SCSS, ask if there's a build step that compiles to CSS.
+
+### Step 3: Identify Themes
+
+Check for multiple theme files or theme selectors:
+- Separate files: `tokens-light.css`, `tokens-dark.css`
+- Selectors: `[data-theme="dark"]`, `.dark-theme`, `:root.dark`
+- Media query: `@media (prefers-color-scheme: dark)`
+
+List discovered themes to user.
+
+### Step 4: Update Configuration
+
+Update `catalogue.config.ts` with token configuration:
+
+**Single theme (light only):**
+```typescript
+export default {
+  // ...
+  themes: {
+    tokenCss: './src/tokens/tokens.css',
+  }
+}
+```
+
+**Multiple themes:**
+```typescript
+export default {
+  // ...
+  themes: {
+    default: 'light',
+    available: ['light', 'dark'],
+    tokenCss: {
+      light: './src/tokens/tokens-light.css',
+      dark: './src/tokens/tokens-dark.css',
+    }
+  }
+}
+```
+
+**Multiple token sets (brands/projects):**
+```typescript
+export default {
+  // ...
+  themes: {
+    tokenSets: {
+      brandA: { light: './tokens/brand-a-light.css', dark: './tokens/brand-a-dark.css' },
+      brandB: { light: './tokens/brand-b-light.css', dark: './tokens/brand-b-dark.css' },
+    },
+    defaultTokenSet: 'brandA',
+    defaultTheme: 'light',
+  }
+}
+```
+
+### Step 5: Scope Decision
+
+Ask user which model to use:
+
+**Model A - Global tokens (recommended for most):**
+- Tokens apply to entire document
+- Catalogue chrome and components share variables
+- Simplest setup
+
+**Model B - Scoped tokens:**
+- Tokens apply only inside preview frame
+- Prevents token names from affecting catalogue UI
+- Better if tokens use generic names (`--text`, `--bg`)
+
+For Model B, ensure preview frame has isolation:
+```css
+.preview-frame {
+  container-type: inline-size;
+  /* tokens scoped here */
+}
+```
+
+### Step 6: Container Query Setup
+
+Since the catalogue resizes the preview container (not viewport), recommend:
+
+```css
+.preview-frame {
+  container-type: inline-size;
+}
+```
+
+Tell user: "Components should use `@container` queries for internal responsiveness, not `@media` queries. Media queries test viewport; container queries test the actual embedding context."
+
+Suggest semantic container breakpoints:
+```css
+/* Document these in your design system */
+/* --cq-sm: 420px */
+/* --cq-md: 640px */
+/* --cq-lg: 960px */
+```
+
+### Step 7: Verify Setup
+
+1. Run `npx catalogue dev`
+2. Check that components render with correct colors, typography, spacing
+3. Toggle themes (if multiple) and verify switching works
+4. Resize preview frame and verify container queries respond
+
+### Step 8: Document Tokens (Optional)
+
+If user wants a tokens documentation page, suggest:
+- Generate from source (don't hand-maintain)
+- Show color palette swatches
+- Typography scale examples
+- Spacing scale visualization
+- Semantic token reference
+
+### Report to User
+
+Summarize:
+- Token files configured: X
+- Themes available: [light, dark, ...]
+- Token sets (if multiple): [brandA, brandB, ...]
+- Container query setup: enabled/disabled
+- Any warnings or manual steps needed