Get started

Contributing a component

The same recipe whether it's you, me, or an agent in another repo. A single component touches three places — source code, doc spec, and the registry index — and it lights up automatically in the gallery + the install endpoint.

Step 1Add the component to the design package

Drop the file under packages/design/src/primitives (or patterns, layouts, brand). Re-export it from packages/design/src/index.ts so consumer apps can import it directly.

// packages/design/src/primitives/badge-pulse.tsx
export function BadgePulse({ children }: { children: React.ReactNode }) {
  return <span className="…">{children}</span>;
}

Step 2Write a doc spec

Create apps/docs/src/content/components/<slug>.tsx exporting a ComponentDoc. The four required sections are short, variants (if any), doDont, and at least one example with both `code` and `render`.

// apps/docs/src/content/components/badge-pulse.tsx
import { BadgePulse } from "@8maverik8/design";
import type { ComponentDoc } from "@/lib/registry";

export const badgePulseDoc: ComponentDoc = {
  slug: "badge-pulse",
  name: "BadgePulse",
  category: "primitives",
  short: "Pulsing dot for live/online indicators.",
  imports: [{ from: "@8maverik8/design", symbols: ["BadgePulse"] }],
  doDont: [
    { do: "Use to signal a live, real-time stream — telemetry, presence." },
    { dont: "Use as a generic notification bullet — that's <Badge>." },
  ],
  examples: [
    {
      title: "Default",
      code: '<BadgePulse>Live</BadgePulse>',
      render: () => <BadgePulse>Live</BadgePulse>,
    },
  ],
  registry: {
    type: "registry:ui",
    files: [
      { path: "primitives/badge-pulse.tsx", pkg: "design", type: "registry:ui" },
    ],
  },
};

Step 3Register it

Import the doc in apps/docs/src/lib/registry.ts and push it into componentDocs. The sidebar, /components index, dynamic page and /r/<slug>.json endpoint all pick it up automatically.

// apps/docs/src/lib/registry.ts
import { badgePulseDoc } from "@/content/components/badge-pulse";

export const componentDocs: ComponentDoc[] = [
  buttonDoc,
  badgePulseDoc, // ← add here
];

Step 4Verify locally

Run pnpm --filter docs dev and visit http://localhost:3030/components/<slug>. Check the live preview, copy the install command, and try `npx shadcn add http://localhost:3030/r/<slug>.json` in a throwaway directory.

pnpm --filter docs dev
# → http://localhost:3030/components/badge-pulse

Step 5Publish

Run pnpm changeset, describe the new export, push to main. The release workflow bumps @8maverik8/design and publishes to GitHub Packages. The docs site redeploys on the same push.

pnpm changeset
# pick @8maverik8/design → minor → "Add BadgePulse"
git add . && git commit -m "feat(design): BadgePulse"
git push

For agents working in another repo

If you're inside Archi / Cip / a new project and you need a component that's already documented here — install it instead of inventing one. The shadcn CLI drops the source files into your repo and you can edit freely from there.

npx shadcn@latest add https://design.oapps.io/r/<slug>.json

If the component you need is missing, add it to packages/design first (so all apps can use it), then come back and write the doc spec.