aj-interactions — a registry of reusable web interactions

A small, shadcn-style copy-paste registry of polished UI interactions. Each item is a self-contained, prop-driven, themeable component with its own README — grab the folder, drop it in your project, and customize.

What's inside

| Item | What it is | | ------------------------------------------- | -------------------------------------------------------------- | | wallet-card | Tap-to-reveal wallet card that flips to show its details. | | fold-and-send | A letter that folds itself into a paper plane and flies off. |

Layout

registry.json                 # repo-level metadata only (name, homepage)
registry/
  <item>/
    meta.json                 # the contract: deps, files, props, cssVars, controls, source
    README.md                 # usage, props table, theme tokens
    <Component>.(jsx|tsx)      # the component
    <Component>.css           # styles (if not utility-class based)
    assets/                   # any imported svg the component needs
scripts/
  build-registry.mjs          # meta.json → shadcn-compatible public/r/*.json
public/r/                      # build output, served over HTTP (git-ignored)

The folders are the index: the CLI, the shadcn build, and the playground all discover items by scanning registry/*/meta.json, so adding an interaction needs no index edit. meta.json is the single source of truth; registry.json only holds repo-level metadata (name, homepage). README.md is the human doc.

How to reuse an item

With shadcn (recommended — no clone, no bespoke CLI)

Every item is published as a shadcn-compatible registry item, so you can add it with the tool you already use. Files (component, CSS, SVGs) land in your project and the terminal prints any extra setup:

npx shadcn@latest add https://registry.ajanwachuku.work/r/wallet-card.json

Swap wallet-card for any item name. The registry index (for discovery / a docs site) lives at https://registry.ajanwachuku.work/r/registry.json.

With the aj-interactions CLI

The aj-interactions CLI reads an item's meta.json, copies its files into your project, and prints what to install.

# once published to npm:
npx aj-interactions list                      # see what's available
npx aj-interactions add wallet-card

# or from a clone of this repo:
node cli/index.mjs add wallet-card --cwd /path/to/your/project

Files land in src/components/<name>/ by default (override with --dir=…); --force overwrites, --cwd=… targets another project. The command then tells you the exact npm i … and any theme tokens. Because each item's assets are self-contained (./assets/…), the copied folder works as-is.

By hand

1. Open the item folder (e.g. registry/wallet-card) and copy it into your project (keep the assets/ subfolder next to the component).
2. npm i the dependencies from its meta.json.
3. Import it and pass props / override CSS variables — see the item's README.

Conventions for every interaction (the mold)

Author each new interaction to this checklist so the whole registry stays consistent and reusable:

1. Content → props — no hardcoded copy or personal data; everything the user would change is a prop with a sensible default.
2. Look → CSS variables — expose the key colors/sizes as --tokens so the component restyles without edits. Pass className / style through to the root.
3. Respect prefers-reduced-motion — same result, no (or minimal) motion.
4. A README — props table, theme-token table, install, dependencies, a11y.
5. A meta.json — name, description, dependencies, files, props, cssVars, the controls block (drives the playground's sliders/inputs), and the source repo/branch it was authored in.
6. Asset gotchas — SVGs used as <img> must use literal fills (fill="white", not Figma's var(--fill-0, …)); inline any binary (png/jpg) as a base64 data URI (shadcn embeds file content as text, so it can't carry binaries).

Adding a new interaction

Dropping the folder is the whole flow — the folders are the index, so no file needs a manual entry:

1. Build & refactor it in its own repo to the checklist above (on a branch).
2. mkdir registry/<name> and copy in the component, README, assets.
3. Write registry/<name>/meta.json (include the controls block).
4. Commit + push. CI rebuilds public/r/*.json and redeploys the playground; the CLI and playground pick it up automatically. To update the npm CLI package, npm version patch && npm publish.

Preview locally first with npm run site:dev (playground) — the new item appears in the nav on its own.

Publishing

Two distribution channels, both derived from the same meta.json files.

shadcn registry (served over HTTP)

npm run build     # writes public/r/registry.json + public/r/<item>.json

.github/workflows/deploy-registry.yml runs this on every push to master and publishes public/ to GitHub Pages. Items are served at:

https://registry.ajanwachuku.work/r/<item>.json

The branded domain comes from static/CNAME (copied into public/ on each build). It's a registry subdomain CNAME'd to ajanwachuku.github.io — the ajanwachuku.github.io/interactions-registry/… URLs still work and 301-redirect here, so no links break. Pages source is Settings → Pages → Source: GitHub Actions.

npm (the CLI)

npm publish       # runs the build first via prepublishOnly

Publishes the aj-interactions CLI so anyone can npx aj-interactions add <item>.

License

MIT — take them, remix them, ship them.