UI-Genius

A UI skill for really pretty, on-brand websites. UI-Genius teaches the mblode UI skills (ui-design, ui-animation, ui-audit) your company brand system, so generated UI comes out on-brand instead of generic.

It is currently loaded with the Click Frenzy brand v3 (single-led Pink #FB1671 on White + Black chrome, Inter type, badge-triad semantics, blode-icons), reverse-engineered from the client's Figma explorations.

Install (team, one line)

npx -y @amtec-advisory/ui-genius@latest

Run that once (needs Node.js). It installs the skill into ~/.claude/skills/ui-genius and keeps itself up to date at the start of every Claude session: no git, no npm login, no auth. Then use /ui-genius, or just ask Claude to build something on-brand. Full options and contributor installs are under Install details.

Team usage in target repos

The intended user experience is plain English in Claude Code, not memorising package commands. After UI-Genius is installed once on a teammate's machine, they can open Claude in any target repo and ask:

Make this page on-brand with UI-Genius.

or:

Audit this repo against the Click Frenzy brand and fix the safe issues.

Claude should then run the UI-Genius helper itself. The helper is idempotent: it wires the repo only when needed, adds the global @amtec-advisory/ui-genius/tokens.css import, adds target-repo agent instructions, adds package scripts, and installs a daily GitHub Actions brand audit workflow. The user does not need to know where CSS imports live or which command performs the audit.

For maintainers or agents doing explicit setup, the same flow is available as:

npx -y @amtec-advisory/ui-genius@latest "make this repo on-brand"

Safe migrations are deliberately reviewable. Claude can run a dry-run audit first, explain the proposed replacements in plain English, then apply exact, low-risk replacements only when asked.

Figma (design-side source of truth): the v3 brand system lives inside the client's Click Frenzy file on the ----- BRAND SYSTEM v3 pages: 5 variable collections (109 variables), 14 text styles, 4 effect styles, and Badge / Chip / Button / Section Header / Deal Card / Product Card / Offer Card / Voucher Card components, all variable-bound. v3 was extracted ONCE from the "Explorations V2" page (2026-06-12); designers edit the library, and token changes sync back into brand/tokens.json on library publish. The brand font is Inter (native in Figma; Glide retired in v3). Build ledger: /tmp/dsb-state-cf-v3-001.json. The old mirror file (ASS3ASyzDqDu8R1uhgblX7) is obsolete.

Token sync pipeline (Figma to code)

Designers edit the Figma library; code follows. The chain:

1. Dump: scripts/figma-dump-variables.js runs in Figma (via the MCP use_figma tool) and exports every variable collection + effect style to brand/figma-variables.json.
2. Transform: node scripts/figma-sync.mjs regenerates the Figma-owned sections of brand/tokens.json (colour ramps, badge triads, semantics, alpha, gradients, space, radius, borders, shadows) and rebuilds brand/tokens.css via scripts/build-tokens-css.mjs. Code-owned sections (type, motion, icons, voice rules) are never touched. Validation gates (required tokens, badge triads, WCAG contrast, writing rules) block a broken Figma state from shipping.
3. Ship: pushing to main auto-publishes @amtec-advisory/ui-genius to npm (publish.yml); consumers import @amtec-advisory/ui-genius/tokens.css.

To sync right now: run /figma-sync in Claude Code in this repo. One command does dump, transform, validation, diff summary, commit, and push.

CI (figma-sync.yml): every push verifies dump/tokens.json/tokens.css agree (no hand edits to generated files). A repository_dispatch of type figma-library-publish, an hourly cron, or a manual dispatch runs the regenerate job, which pulls the CURRENT token state from Figma without Enterprise: scripts/figma-rest-pull.mjs reads the Sync Board page (node 375:2, one node per variable with the variable bound to a REST-resolvable property: fills for colours, widths for numbers, applied styles for shadows) through the plain file REST API.

The same regenerate job performs the Tier-2 drift sweep. Token-value changes still ship automatically; rule or card-structure divergence is written to drift-report.json and maintained as one idempotent figma-drift issue. Structural card drift now proposes the matching spec/example update inside that same regenerate job via anthropics/claude-code-action@v1. The proposal step is guarded by open figma-drift/ PR branches so the hourly cron cannot open duplicate PRs. .github/workflows/figma-structure-propose.yml remains as a manual workflow-dispatch fallback for rerunning proposal from an existing drift issue.

Manual-review alerts are optional. Set the repo secret FIGMA_DRIFT_NOTIFY_WEBHOOK to a Make, Zapier, Twilio, or internal webhook URL, and figma-sync.yml will POST a JSON alert when a figma-drift issue is created or materially updated. That webhook can send email, WhatsApp, SMS, or any other team notification. The hourly cron does not spam unchanged issues.

Webhook: api/figma-webhook.js is deployed at https://cf-figma-sync.vercel.app/api/figma-webhook (Vercel project cf-figma-sync). It verifies the shared passcode and relays Figma LIBRARY_PUBLISH / FILE_VERSION_UPDATE events as the GitHub dispatch. Register it with scripts/register-figma-webhook.mjs (needs FIGMA_TOKEN with webhooks scope; passcode in the local .env.figma-sync, gitignored).

Current live status: the Figma token secret, npm token, Anthropic key, webhook, and hourly cron are configured. The remaining product integration is to wire the Click Frenzy website to import @amtec-advisory/ui-genius/tokens.css. /figma-sync in Claude Code is still available as the manual trigger for the same loop.

Install details

UI-Genius is a Claude Code skill bundle: SKILL.md lives at the repo root and the brand/, references/, components/, and assets/ folders are the resources it loads. The npm command at the top is the recommended path for teammates (auto-updating, no auth). The git installs below are for contributors who work on the skill itself.

Publishing is automatic: the Publish to npm GitHub Action (.github/workflows/publish.yml) ships a new version on every push to main. It needs one repo secret, NPM_TOKEN (an npm token with publish rights to the @amtec-advisory scope).

Personal install (available in all your projects):

# Claude Code auto-discovers skills under ~/.claude/skills/<name>/
git clone https://github.com/Amtec-Advisory/UI-Genius.git ~/.claude/skills/ui-genius

Team install (commit it into a shared project so it travels with the repo):

cd <your-project>
git submodule add https://github.com/Amtec-Advisory/UI-Genius.git .claude/skills/ui-genius
git add .claude && git commit -m "Add UI-Genius brand skill"

Via the skills CLI (same result as the clone, nicer ergonomics):

npx skills add Amtec-Advisory/UI-Genius -g -y

Notes:

• The repo is private under the Amtec-Advisory org. Whichever path you use, the installer needs GitHub access to that org or the clone will fail on auth.
• To update later: git pull in the skill dir, git submodule update --remote for the submodule, or re-run the skills add command.
• UI-Genius is a thin orchestrator. The self-contained brand system (tokens, guidelines, logo, font, icon references) works on its own, but the full design loop also calls the ui-design, ui-animation, and ui-audit skills. Install those too for the complete flow.

Once installed, type /ui-genius or just ask Claude to build something on-brand.

Layout

SKILL.md                  UI-Genius orchestrator: load brand → design → build → animate → audit
brand/
  tokens.json             canonical brand values (source of truth)
  tokens.css              drop-in CSS variables, derived from tokens.json
  guidelines.md           voice, color, type, motion, logo: the "why" and the rules
  brand-grill.md          the grill-me interview that (re)builds the brand
  brand-sheet.html        one-page visual cheat-sheet of the whole system
  assets/                 logo variants (pink recolor) + source
components/                the component library (see "Component library" below)
  index.md                generated registry: every component, one row each
  _baseline.md            rules every interactive component inherits
  _template.md            authoring template for a new component
  product-card.md         a component file: card-specific rules + link to a working example
references/
  inter-font.md           Inter font setup (Next.js + Tailwind)
  icons.md                blode-icons (mandatory icon library)
scripts/
  build-component-index.mjs   regenerates components/index.md from frontmatter
gallery.html              click-through preview of every built artifact (the regression harness)
product-card*.html        canonical component examples (the copy-source for components/)

Use it

1. Open brand/brand-sheet.html to see the system.
2. When building UI, load brand/tokens.json + brand/guidelines.md, drop in brand/tokens.css, and reference the tokens, never hard-code off-brand values.
3. To define/evolve the brand, run the interview in brand/brand-grill.md.

Component library

UI-Genius scales by capturing each UI component once, as a working example plus a thin rules file, so generated UI reuses battle-tested patterns instead of regenerating (and re-breaking) them. It is designed to hold many components without bloating what loads per task.

How it loads (progressive disclosure). SKILL.md stays a small, always-on index. It points at components/index.md (a generated registry, read when any component is needed), which points at one components/<name>.md file (read on demand). Building a card pulls in the brand files plus the index plus product-card.md plus its example, never the other components. Per-task cost stays flat as the library grows.

No duplicated rules. Brand-wide law lives in brand/guidelines.md. Rules shared by every interactive component (focus, selection-vs-action colour, radio-group semantics, disabled states, tap targets, motion) live in components/_baseline.md. A component file holds only its own delta, so a shared rule has exactly one home and nothing drifts.

Examples are the copy-source. Each component file points example at a real, audited HTML file (product-card.md → product-card-multi.html). Agents copy from it rather than synthesising from scratch. Keep examples rendering in gallery.html so breakage stays visible.

Add a component:

1. cp components/_template.md components/<kebab-name>.md

2. Fill the frontmatter (component, status, description, example) and the delta rules. Point example at a working file and add that file to gallery.html.

3. Regenerate the registry:

   node scripts/build-component-index.mjs

index.md is generated from frontmatter, so it never drifts from the files, and the generator flags any component whose example is missing.

Brand checks

The brand hard rules (no em-dashes, no emoji) are enforced mechanically, not by eye:

• Linter: node scripts/check-brand-rules.mjs scans every tracked text file and prints file:line:col for any violation. En-dashes in numeric ranges (like 400-900) and arrows are allowed. Pass file paths as arguments to scan a subset.

• Pre-commit hook: .githooks/pre-commit runs the linter on staged files and blocks the commit on any violation. Enable it once per clone:

  git config core.hooksPath .githooks

Re-brand for another company

Re-run brand/brand-grill.md and overwrite tokens.json / guidelines.md / assets/. The skill structure stays; only the brand contents change.