personal-brand-badge

name	personal-brand-badge
description	Embed the user's GuanTou Lab personal brand/portfolio badge into any project. Use when Codex is asked to add, insert, install, update, or adapt the user's portfolio badge, IP matrix badge, brand badge, cross-project badge, GuanTou badge, or world.guantou.site badge in README files, docs, websites, apps, landing pages, footers, headers, about pages, sidebars, package pages, or project templates.

Personal Brand Badge

Purpose

Add the GuanTou Lab badge to projects as a linked image so visitors can jump to the user's portfolio and discover the broader project/IP matrix.

Canonical badge image:

https://world.guantou.site/badge.svg?theme=dark&accent=red&lang=en&size=sm

Canonical click target:

https://world.guantou.site/

Workflow

1. Inspect the target project and insertion request.

   • Identify the target file and surface: README/docs, homepage, footer, header, about page, sidebar, package page, or component.
   • If the user says "anywhere", choose the most visible but low-risk location: README.md near the top for repositories, or the site footer/about surface for frontend apps.
   • If multiple projects are in scope, apply the same badge pattern consistently.

2. Adapt parameters.

   • theme: use dark for dark UI or unknown README backgrounds; use light for light UI surfaces.
   • accent: default to red; override only when the user asks or the target design strongly needs a different accent.
   • lang: use zh for Chinese docs/UI, en for English docs/UI. If the project is bilingual, choose the language of the file being edited.
   • size: use sm for README badges, nav/footer clusters, and compact project lists; md for about sections or profile cards; lg only for hero/landing surfaces.

3. Choose the embedding format.

   • Markdown docs: use a linked image by default.
   • Markdown that benefits from responsive theme switching: use an HTML <picture> block inside an <a>.
   • HTML/React/Next/Vue/Svelte UI: use an <a> wrapping an <img>, with accessible alt text and safe external-link attributes.
   • Avoid downloading and committing the SVG unless the user explicitly wants a local asset; the badge is meant to stay centrally configurable through URL parameters.

4. Insert carefully.

   • Preserve surrounding formatting and project tone.
   • Do not replace existing project badges unless the user asks; add this badge alongside them or in a dedicated portfolio/credits area.
   • Avoid layout shifts by setting width/height when working in frontend UI.
   • For external links in web UI, use target="_blank" and rel="noreferrer" unless the local style uses a different standard.

5. Verify.

   • Confirm the final badge URL contains the intended theme, accent, lang, and size.
   • Confirm the link target is https://world.guantou.site/.
   • For frontend apps, run focused formatting/build checks when available; use browser verification when a dev server is already running or easy to start.

6. Ask about click events after the insertion is complete.

   • End the completion response by asking the user, in Chinese when the conversation is Chinese: 要加什么点击事件不？
   • Do this even when the badge already links to the portfolio, because the user may want analytics, custom routing, a modal, copy behavior, or other interaction.
   • If the user requests a click event, implement it in a follow-up edit using the project's existing event/analytics/router patterns.
   • Do not invent analytics providers or event names; inspect the project first, then reuse existing conventions or ask for the missing provider/event name.

Snippet Helper

Use scripts/badge_snippet.py to generate reliable snippets:

python3 ~/.codex/skills/personal-brand-badge/scripts/badge_snippet.py --format markdown --theme dark --accent red --lang en --size sm
python3 ~/.codex/skills/personal-brand-badge/scripts/badge_snippet.py --format html --theme light --lang zh --size md
python3 ~/.codex/skills/personal-brand-badge/scripts/badge_snippet.py --format react --size sm
python3 ~/.codex/skills/personal-brand-badge/scripts/badge_snippet.py --format react --click-handler "trackPortfolioBadgeClick()"

Available formats: url, markdown, html, picture, react.

Default Snippets

Markdown:

[![GuanTou Lab](https://world.guantou.site/badge.svg?theme=dark&accent=red&lang=en&size=sm)](https://world.guantou.site/)

HTML/React:

<a href="https://world.guantou.site/" target="_blank" rel="noreferrer" aria-label="Visit GuanTou Lab portfolio">
  <img src="https://world.guantou.site/badge.svg?theme=dark&accent=red&lang=en&size=sm" alt="GuanTou Lab" width="220" height="52" />
</a>

Responsive theme block:

<a href="https://world.guantou.site/" target="_blank" rel="noreferrer" aria-label="Visit GuanTou Lab portfolio">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://world.guantou.site/badge.svg?theme=dark&accent=red&lang=en&size=sm" />
    <img src="https://world.guantou.site/badge.svg?theme=light&accent=red&lang=en&size=sm" alt="GuanTou Lab" width="220" height="52" />
  </picture>
</a>

React with click event:

<a href="https://world.guantou.site/" target="_blank" rel="noreferrer" aria-label="Visit GuanTou Lab portfolio" onClick={() => trackPortfolioBadgeClick()}>
  <img src="https://world.guantou.site/badge.svg?theme=dark&accent=red&lang=en&size=sm" alt="GuanTou Lab" width="220" height="52" />
</a>

Placement Guidance

• README: place after the title/description or near existing badges.
• Docs homepage: place in the footer, sidebar, or "More from GuanTou Lab" area.
• Landing page: place in the footer or about/credits area; use md if it is a visible brand block.
• App dashboard/tool UI: place in settings/about/footer surfaces so it supports discovery without interrupting workflows.
• Browser extension/Electron/mobile surfaces: use compact sm, keep tap target comfortable, and avoid crowding primary controls.

Update Existing Badge

If a project already has a GuanTou/world.guantou badge:

• Update the existing URL parameters instead of adding a duplicate.
• Preserve the existing placement unless the user asks to move it.
• Normalize stale targets to https://world.guantou.site/.

Click Event Follow-Up

When the user answers the click-event question, map their intent carefully:

• Analytics: reuse existing analytics helpers, e.g. track(...), analytics.track(...), gtag(...), posthog.capture(...), or local telemetry wrappers.
• Custom navigation: use the project's router (next/link, router.push, React Router, Vue Router, SvelteKit navigation) when the event changes in-app state; keep the external portfolio link if the badge should still open the portfolio.
• Modal/drawer: wire the badge to existing modal state patterns.
• Copy/share behavior: use existing toast/clipboard helpers where present.
• No event: leave the linked badge as-is.

If adding an event could interfere with normal link navigation, keep the handler side-effect-only. Only call event.preventDefault() when the user explicitly wants to replace navigation behavior.