submit

Submit your DESIGN.md to the public catalog via PR.

Synopsis

design-md submit <file> [--dry-run]

What it does

submit takes your local DESIGN.md file and opens a pull request against the public catalog repo at github.com/WebDesignHot/design-md. Here’s the flow:

Validates the file by checking required frontmatter fields (name, spec, source_url, color roles)
Resolves the slug from frontmatter or derives it from your filename (e.g., my-brand.md → slug my-brand)
Checks for GitHub CLI (gh command). If missing, prints manual submission instructions instead
Forks the catalog repo to your GitHub account (idempotent — no-op if already forked)
Clones your fork to a temporary directory and syncs it with the upstream main branch
Copies your file to the catalog’s design-md/<slug>.md location
Commits and pushes to a timestamped feature branch on your fork
Opens a PR against WebDesignHot/design-md:main with a templated body that includes categories, tags, and your source URL
Prints the PR URL so you can track it

If the slug already exists in the catalog, you’ll be prompted to confirm whether you want to update it.

Options

Flag	Description
`--dry-run`	Validate the file and print what would be submitted without forking, cloning, or opening a PR. Useful for checking your entry is ready before committing to the submission flow.

Prerequisites

Your DESIGN.md must pass lint — required fields, 15 sections, all color roles present
The slug you’re submitting must not duplicate an existing catalog entry (unless you’re updating it intentionally)
GitHub CLI (gh) is installed and authenticated. Without it, the command will print manual fork + PR instructions

Install gh if needed:

macOS: brew install gh
Windows: winget install GitHub.cli
Other: https://cli.github.com

Examples

Dry-run first

Always validate before submitting:

npx @webdesignhot/design-md submit ./DESIGN.md --dry-run

Output:

→ Submitting Acme Corp as slug "acme-corp"
✓ Dry-run passed. Would submit Acme Corp as acme-corp.
  File: /Users/you/projects/acme/DESIGN.md
  Target: WebDesignHot/design-md/design-md/acme-corp.md

Submit for real

Once dry-run succeeds, drop the flag:

npx @webdesignhot/design-md submit ./DESIGN.md

The command will:

Fork the repo to your account (or re-use existing fork)
Clone it locally
Add your file
Commit and push
Open a PR

Output:

→ Submitting Acme Corp as slug "acme-corp"
→ Forking WebDesignHot/design-md to you/design-md (no-op if already forked)
→ Cloning fork to /var/folders/…/design-md-submit-acme-corp-1716907843420
→ Branch: submit/acme-corp-a1b2
→ Pushing to you/design-md:submit/acme-corp-a1b2
→ Opening PR

✓ Submitted.
  https://github.com/WebDesignHot/design-md/pull/42

Your design will appear on webdesignhot.com once we review and merge.

Update an existing entry

If the slug already exists in the catalog, you’ll be prompted:

design-md/<slug>.md already exists in the catalog. Open a PR to update it?
❯ (y/n)

Answer y to open a PR that replaces the existing entry, or n to abort.

What happens after submit

PR opens on the public catalog with your file, categories, tags, and source URL in the body
The team reviews for completeness — lint pass, all 15 sections present, tokens match production, lineage references are real
Once merged, your brand appears on webdesignhot.com/design.md/ and becomes available to all users via design-md add <slug>
CLI users see it immediately — the catalog is fetched fresh on each command

The whole process typically takes 1–3 business days.

Failure modes

gh is not installed

The command exits gracefully and prints manual instructions:

⚠ The GitHub CLI (`gh`) is not installed.

This command auto-forks + opens a PR for you. Install with:
  brew install gh              # macOS
  winget install GitHub.cli    # Windows
  https://cli.github.com       # other platforms

Or submit manually:
  1. Fork https://github.com/WebDesignHot/design-md
  2. Add your file at design-md/<slug>.md
  3. Open a PR against `main`.

gh is installed but not authenticated

⚠ `gh` is installed but not authenticated.
  Run: gh auth login

Lint fails

✗ File has issues that must be fixed before submitting:
  · frontmatter.name is required
  · frontmatter.colors must include bg, text, and brand
  Run `design-md lint <file>` for full diagnostics.

lint — validate a DESIGN.md before submission
init — scaffold a new DESIGN.md for your brand
Adding a brand — step-by-step guide for catalog contributions (coming soon)