CodeVetter · Repo Unpack · System map
nextlevelbuilder/ui-ux-pro-max-skill
The repo is a content product, not a running service: the runtime is a stdlib-only Python 3 CLI (search.py over core.py/design_system.py) reading canonical CSVs under src/ui-ux-pro-max/data/. The TypeScript CLI under cli/ is purely an installer that renders platform templates and copies bundled assets; it never executes the Python. Distribution happens through three mirrored copies of the same data (src/ -> cli/assets/ -> .claude/skills/ui-ux-pro-max/) kept in sync by cli/scripts/sync-assets.mjs and enforced by CI. Supporting surfaces: a Next.js 14 style gallery, a stack/ sub-project that wraps the skill with Playwright/MCP tooling, and six GitHub Actions workflows covering tests, asset sync, catalog refresh, release, and version bumping.
- The runtime entrypoint is src/ui-ux-pro-max/scripts/search.py, an argparse CLI exposing --domain (12 keys of CSV_CONFIG), --stack (22 stacks), --design-system, --json, --persist/--page/--output-dir/--force, and three 1-10 dials --variance/--motion/--density.
- core.py implements a hand-rolled BM25 class (k1=1.5, b=0.75) with in-process caches _csv_cache and _bm25_cache keyed by file signature (st_mtime_ns, st_size), plus synonym normalization, per-domain score floors, and deterministic domain tie-breaking.
- design_system.py contains DesignSystemGenerator plus three output formatters (format_ascii_box, format_markdown, format_master_md) and the Master+Overrides persistence layer (persist_design_system, format_page_override_md).
- reasoning_contract.py is a closed, non-executable DSL: ui-reasoning.csv Decision_Rules cells are JSON objects whose conditions must come from ALLOWED_CONDITIONS (must_have + 38 if_* signals) and actions must carry a constraint:/style:/pattern:/mode: prefix.
- The npm CLI (cli/package.json name ui-ux-pro-max-cli v2.5.0, bin uipro -> dist/index.js) registers exactly four commander subcommands: init, versions, update, uninstall; it is ESM ('type': 'module') built by bun build with a tsc fallback in scripts/build.mjs.
- src/ui-ux-pro-max/ is the single source of truth; cli/scripts/sync-assets.mjs mirrors data/, scripts/, templates/ into cli/assets/, mirrors data/ and scripts/ into .claude/skills/ui-ux-pro-max/, and copies 6 sub-skills (banner-design, brand, design, design-system, slides, ui-styling) into cli/assets/skills/, normalizing CRLF->LF before hashing.
- The Claude plugin surface is .claude-plugin/plugin.json + marketplace.json (version 2.13.0) pointing 'skills' at ./.claude/skills/, where SKILL.md is hand-authored (not template-generated) while its data/ and scripts/ are mirrors of src/.
- The gallery is a Next.js 14 + Tailwind app (gallery/package.json name style-gallery) whose server component reads gallery/data/styles.csv — a symlink into ../../src/ui-ux-pro-max/data/styles.csv — and parses it with a hand-written CSV parser.
- stack/ is a separate private package (claude-website-design-stack) that wraps the skill with a design loop (plan -> commit aesthetic -> build -> Playwright visual check -> design-review subagent) installed by scripts/setup.sh via npx ui-ux-pro-max-cli init --ai claude.
- CI is six workflows: tests.yml (verify:data + pytest over .claude/skills + Playwright e2e + gallery build), check-asset-sync.yml (drift + skill-path contract greps), smoke-stacks.yml, refresh-catalogs.yml (weekly cron), release.yml (semantic-release to npm/GitHub), bump-versions.yml (post-release JSON version sync PR).
- Version numbers intentionally diverge: the skill/plugin manifests are at 2.13.0 while cli/package.json is 2.5.0; bump-versions.yml opens a PR to re-sync skill.json, marketplace.json, and plugin.json after each GitHub release.
- Python scripts are strictly stdlib-only (csv, json, re, difflib, math, pathlib) — no requirements.txt or pyproject exists; tests run under unittest/pytest with zero third-party runtime deps, matching the documented 'no external dependencies' prerequisite.