@create-ui/cli 0.5.4 → 0.5.6

package/dist/skills/createui/contributing.md

@@ -1,213 +0,0 @@
-# Contributing to the Create UI Monorepo
-
-This guide is for contributors working **inside** the Create UI monorepo — adding or editing
-registry components, the CLI, or the documentation site. If you only want to consume Create UI in
-your own app, see [`cli.md`](./cli.md) instead.
-
-## Contents
-
-- [Monorepo layout](#monorepo-layout)
-- [Dev, build & quality commands](#dev-build--quality-commands)
-- [Tests](#tests)
-- [The registry](#the-registry)
-- [Authoring a component](#authoring-a-component)
-- [Scaffolding & validation](#scaffolding--validation)
-- [Testing the CLI locally](#testing-the-cli-locally)
-- [Website: three-layer architecture](#website-three-layer-architecture)
-- [Component rules recap](#component-rules-recap)
-- [Commit convention](#commit-convention)
-
-## Monorepo layout
-
-Create UI is a **pnpm 9.0.6 + Turbo** monorepo with two workspaces:
-
-| Workspace | What it is | Stack |
-|---|---|---|
-| `apps/v4` | Documentation site & component showcase | Next.js 16 (App Router), React 19, Tailwind CSS v4 |
-| `packages/createui` | The `createui` CLI published to npm | Commander.js, tsup (ESM-only) |
-
-The site is also where the **registry** lives (`apps/v4/registry/`). The CLI reads that registry —
-in the monorepo it points at the local dev server (`http://localhost:4000/r`).
-
-## Dev, build & quality commands
-
-Run all commands from the repo root. Package manager is **pnpm** — do not use npm or yarn.
-
-```bash
-# Develop
-pnpm dev            # everything, in parallel via Turbo
-pnpm v4:dev         # docs/showcase site only (port 4000)
-pnpm createui:dev   # CLI only, in watch mode
-
-# Build
-pnpm build          # all workspaces
-pnpm v4:build       # site only
-pnpm createui:build # CLI only
-
-# Quality
-pnpm check          # lint + typecheck + format:check (run this before opening a PR)
-pnpm lint           # ESLint
-pnpm lint:fix       # ESLint with --fix
-pnpm typecheck      # TypeScript
-pnpm format:write   # Prettier write
-pnpm format:check   # Prettier check
-```
-
-## Tests
-
-The test suite needs the v4 dev server running; `pnpm test` handles that for you.
-
-```bash
-pnpm test       # starts the v4 dev server, then runs Vitest
-pnpm test:dev   # runs Vitest against an already-running server (no startup)
-```
-
-## The registry
-
-Every UI component is defined under `apps/v4/registry/` and served to users through the CLI.
-
-```
-apps/v4/registry/
-  ui/         core UI components (button, select, dialog, …)
-  examples/   demos shown in the docs
-  blocks/     larger composed blocks
-  hooks/      custom React hooks
-  lib/        utilities (e.g. cn())
-  internal/   internal-only components (not exposed to users)
-  components/  shared registry components
-```
-
-Each subdirectory has a `_registry.ts` that exports a metadata array, and every array is aggregated
-in `apps/v4/registry/registry.ts`.
-
-In-repo registry entries **omit `content`** — `pnpm registry:build` injects each file's source when
-it generates `apps/v4/public/r/<name>.json`. Real entry shapes:
-
-```ts
-// apps/v4/registry/ui/_registry.ts
-{
-  name: "button",
-  type: "registry:ui",
-  dependencies: ["class-variance-authority", "radix-ui"],
-  files: [{ path: "ui/button.tsx", type: "registry:ui" }],
-}
-
-{
-  name: "select",
-  type: "registry:ui",
-  registryDependencies: ["field", "dropdown-menu"],
-  files: [{ path: "ui/select.tsx", type: "registry:ui" }],
-}
-```
-
-The `type` values, file objects (`{ path, type, content?, target? }`), and item fields are defined by
-the registry-item schema (`$schema: https://createui.co/schema/registry-item.json`). Use
-`dependencies` for npm packages and `registryDependencies` for other registry items the component
-needs.
-
-## Authoring a component
-
-1. Create `apps/v4/registry/ui/<name>.tsx`:
-   - use **`cva`** for variants and **`cn()`** (from `@/registry/lib/utils`) to merge classes
-   - put `data-slot="<name>"` on the root element
-   - support polymorphism with **`asChild`** via the Radix `Slot`
-   - type props as `React.ComponentProps<"el"> & VariantProps<typeof variants> & { … }`
-   - use a **named export** (`export { Name }`)
-2. Add an entry to `apps/v4/registry/ui/_registry.ts` (shape above).
-3. Add a demo under `apps/v4/registry/examples/<name>-demo.tsx` and register it in
-   `apps/v4/registry/examples/_registry.ts`.
-4. Run **`pnpm registry:build`** to rebuild the registry (it also runs `lint:fix` + format and
-   regenerates the `public/r/*.json` files).
-
-> Filenames are **kebab-case**; exports are PascalCase named exports. There is **no** `pnpm tokens:build` —
-> tokens live in `apps/v4/styles/globals.css` and are edited directly.
-
-## Scaffolding & validation
-
-```bash
-pnpm scaffold <name>              # create a component + example + registry entry
-pnpm scaffold <name> --existing   # generate an example from an existing component (parses CVA)
-pnpm scaffold <name> --dry-run    # preview output without writing files
-pnpm scaffold <name> --force      # overwrite existing files
-
-pnpm validate:registries          # validate every _registry.ts against the schema
-```
-
-## Testing the CLI locally
-
-The root `pnpm createui` script runs the **local CLI build** against `http://localhost:4000/r`, so
-start the site first:
-
-```bash
-pnpm v4:dev                          # serves the local registry at http://localhost:4000/r
-pnpm createui add -c ~/path/to/app   # run the local CLI against a target app
-```
-
-`-c` (`--cwd`) points at the project you want to add components to.
-
-## Website: three-layer architecture
-
-Site work follows a strict three-layer model:
-
-```
-registry/ui/            primitives — SACROSANCT, never edited by site work
-  ↓ composed by
-components/site/         shared composites (reused across ≥2 route groups)
-  ↓ composed by
-app/(group)/_components/ route-local composites (used by one route group)
-```
-
-A new composite belongs in `components/site/` only if it is reused across **two or more** route
-groups; otherwise it lives in the route group's `_components/`. If a primitive is missing, **ask
-first** — never edit `registry/ui/` to make a page work.
-
-The authoritative website guides live in **`mds/website/`** — start at
-[`mds/website/BRIEF.md`](../../mds/website/BRIEF.md) (it is written in Turkish). Consult those guides
-for any website task; do not duplicate them here.
-
-## Component rules recap
-
-These conventions keep every component consistent (see [`rules/styling.md`](./rules/styling.md),
-[`rules/composition.md`](./rules/composition.md), and [`rules/icons.md`](./rules/icons.md) for the
-full rules):
-
-- **`data-slot`** on the root element (and on meaningful sub-parts) for semantic styling hooks.
-- **`cn()`** for all class merging — never string-concatenate classes.
-- **`cva`** for variant-based styling; hoist the variants object out of the component.
-- **Semantic tokens** for color: `bg-primary-base`, `text-error-base`, `bg-weak`, `text-body` —
-  never `bg-background` / `text-foreground`-style names.
-- **Radix UI** primitives for accessibility; polymorphism via **`asChild`** + Radix `Slot` only.
-- **Focus is `outline-*`**, never `ring-*` (e.g. `focus-visible:outline-primary-700`).
-- Intersection prop types: `React.ComponentProps<"button"> & VariantProps<…> & { … }`.
-- **kebab-case** filenames, **named** exports.
-
-A correct root element looks like:
-
-```tsx
-// Incorrect — ring focus, non-semantic token, anonymous default export
-<button className={`${base} focus-visible:ring-2 bg-primary`}>{children}</button>
-
-// Correct — data-slot, cn(), outline focus, semantic token
-<Comp
-  data-slot="button"
-  className={cn(buttonVariants({ variant, appearance, size, className }))}
-  {...props}
-/>
-```
-
-When you reference a component in an example, **read its source** at
-`apps/v4/registry/ui/<name>.tsx` first — never guess props. For instance, `Button` takes
-`variant` (`primary` | `neutral-solid` | `neutral-light` | `danger` | `success` | `inverse-solid` |
-`inverse-light`), `appearance` (`solid` | `outline` | `ghost` | `soft`), `size`, `shape`, `loading`,
-`iconOnly`, `leadingIcon`, `trailingIcon`, and `asChild` — there is no `variant="outline"` or
-`variant="destructive"`.
-
-## Commit convention
-
-Conventional commits: `category(scope): message`.
-
-Categories: `feat`, `fix`, `refactor`, `docs`, `build`, `test`, `ci`, `chore`.
-
-```
-feat(components): add loading prop to the button component
-```