@pithyjs/pidl-catalog

Machine-readable component contracts for PithyJS.

A PIDL spec is a JSON document declaring a component's props, types, defaults, slots, events and accessibility guarantees. The catalog is what lets tooling reason about a component without reading its source: the props panels, the AI content projector and the registry generator all read these same files.

Coverage is partial and growing — IconButton, Tooltip, Popover, NavLink and ErrorBoundary have no spec yet.

Beta. Published under the beta tag alongside the rest of the PithyJS packages. The spec shape is still moving; pin an exact version.

Install

npm install @pithyjs/pidl-catalog@beta

What is in it

Specs ship at dist/specs/, organised by atomic level (atoms/, layout/, organisms/, sections/). Enumerate them from ALL_PIDL_SPECS rather than relying on a count in prose — this file cannot recount itself when a spec lands.

A spec's top level looks like this:

{
  "kind": "component",
  "id": "ui.button",
  "name": "Button",
  "level": "atom",
  "domain": "actions",
  "description": "...",
  "props": { /* name -> type, default, constraints */ },
  "events": { /* ... */ },
  "slots": { /* ... */ }
}

Usage

import { ALL_PIDL_SPECS } from '@pithyjs/pidl-catalog';

Design-intelligence tables are separate entry points, so importing one does not pull the others:

import { COLOR_PSYCHOLOGY_GUIDANCE } from '@pithyjs/pidl-catalog/color-psychology';
import { MUTATION_VOCABULARY } from '@pithyjs/pidl-catalog/mutation-vocabulary';
import { DESIGN_INTELLIGENCE_RULES } from '@pithyjs/pidl-catalog/design-intelligence';

Available subpaths: design-intelligence, mutation-vocabulary, and the *-psychology tables for color, typography, spacing, radius, shadows, motion and borders.

Why it exists

A component library documented only in prose forces every tool that consumes it to guess — at which props exist, which values are legal, and which accessibility rules are non-negotiable. PIDL makes those machine-checkable, so "the model never writes CSS" can be enforced by the build rather than asked for in a prompt.

License

MIT