CodeVetter · Repo Unpack · Data flow
nextlevelbuilder/ui-ux-pro-max-skill
Data flows one direction: canonical CSV/JSON datasets under src/ui-ux-pro-max/data/ are consumed in-process by the Python engine (csv.DictReader -> BM25 index -> projected row dicts -> formatted text/JSON), and physically mirrored by sync-assets.mjs into cli/assets/ and .claude/skills/. The CLI copies those bundled assets into the user's project at install time; at query time the skill instructs the agent to shell out to the installed scripts/search.py. Upstream catalog data (Google Fonts API, Phosphor npm packages, google/fonts repo metadata) enters only through the refresh-catalogs workflow as review-only candidates validated by refresh-*.py scripts.
- Input boundary is CSV_CONFIG/STACK_CONFIG: each domain maps to a file under DATA_DIR (Path(__file__).parent.parent / 'data') with declared search_cols and output_cols; rows are loaded via _load_csv_snapshot which re-stats the file before and after reading to reject mid-read mutations.
- Query pipeline: raw query -> _normalize (synonym table, e.g. 'e-commerce'->'ecommerce', 'colour'->'color') -> BM25.tokenize (punctuation strip, >=2 chars, stopword removal) -> optional _rewrite_query_for_domain routing rewrites -> BM25.score over joined search_cols.
- Calibrated abstention sits between scoring and output: _SEARCH_THRESHOLDS apply per-domain min_score/min_coverage (e.g. style 4.3, product 6.0, landing requires 0.5 token coverage), and _STACK_THRESHOLD requires min_score 3.6 + 1/3 coverage; abstained queries return empty results plus suggestions.
- Design-system generation is a fan-out/fan-in: search('product') -> category -> _apply_reasoning (ui-reasoning.csv row + decision rules) -> _multi_domain_search issues 5 searches with category/constraints/mood terms folded into the query -> _select_best_match resolves style_priority names through the style lookup before trusting BM25 order.
- Color-mode coherence is enforced in the transform layer: _resolve_color_mode (query markers or dark-primary style) -> _select_palette_for_mode -> _derive_dark_palette (WCAG luminance, contrast-checked ring) -> _filter_anti_patterns_for_mode strips 'avoid dark mode' advice once dark is chosen.
- Output boundary is stdout text formatted for agent consumption: format_output truncates cell values at 300 chars except UNTRUNCATED_COLS (code samples, checklists, CSS imports, GSAP snippets); --json emits the raw result dict including diagnostics when requested.
- Persistence writes only inside --output-dir (default cwd): safe_slug collapses project/page names to [a-z0-9_-] making traversal impossible, and _write_persisted_file publishes via temp-file + fsync + os.link/os.replace so a losing concurrent writer gets FileExistsError.
- Asset distribution flow: src/ui-ux-pro-max/{data,scripts,templates} -> syncDir() (delete target, rewrite LF-normalized) -> cli/assets/ and .claude/skills/ui-ux-pro-max/; install-time flow is ASSETS_DIR -> loadTemplate/renderSkillFile (placeholder substitution {{TITLE}}, {{SCRIPT_PATH}}, etc.) -> writeFile SKILL.md + cp data/ scripts/ -> copySubSkills.
- Platform-specific install paths are data-driven: templates/platforms/*.json declare folderStructure.root/skillPath/filename/dataPath and scriptPath; resolveInstallPaths derives skillDir, skillFilePath, dataDir, and skillsParentDir (e.g. copilot uses a separate dataPath under .github/).
- Catalog refresh flow is offline-review only: refresh-catalogs.yml fetches the Google Fonts Developer API (GOOGLE_FONTS_API_KEY, 25MB cap), sparse-clones google/fonts METADATA.pb files, and npm-installs pinned @phosphor-icons packages, then refresh-google-fonts.py/refresh-icon-catalog.py emit candidates+diffs uploaded as artifacts — nothing commits to main automatically.
- Provenance and freshness metadata travel with the data: data-provenance.json records per-entity verifiedAt/sla/confidence/source refs, catalog-summary.json pins sha256 snapshots + counts (88 styles, 1512 phosphor icons, 1271 stack guidelines), and .gitattributes forces LF on data files so hashes are platform-stable.
- The gallery reuses the canonical dataset through a symlink: page.tsx reads gallery/data/styles.csv -> src/ui-ux-pro-max/data/styles.csv at request/render time, then parseStylesCSV throws on any Status outside {active, supplemental, deprecated}.