{"id":33314513,"url":"https://github.com/kosaki08/uimatch","last_synced_at":"2025-11-19T12:03:14.105Z","repository":{"id":324823603,"uuid":"1083440240","full_name":"kosaki08/uimatch","owner":"kosaki08","description":"Compare Figma designs with your implemented UI. Playwright-based visual regression \u0026 design QA tool.","archived":false,"fork":false,"pushed_at":"2025-11-18T03:56:48.000Z","size":1629,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-18T04:24:57.591Z","etag":null,"topics":["cli","design-qa","figma","playwright","typescript","visual-regression","visual-testing"],"latest_commit_sha":null,"homepage":"https://kosaki08.github.io/uimatch/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kosaki08.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-26T02:41:45.000Z","updated_at":"2025-11-18T03:56:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kosaki08/uimatch","commit_stats":null,"previous_names":["kosaki08/uimatch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kosaki08/uimatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosaki08%2Fuimatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosaki08%2Fuimatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosaki08%2Fuimatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosaki08%2Fuimatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kosaki08","download_url":"https://codeload.github.com/kosaki08/uimatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosaki08%2Fuimatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285240542,"owners_count":27137943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","design-qa","figma","playwright","typescript","visual-regression","visual-testing"],"created_at":"2025-11-19T12:01:16.881Z","updated_at":"2025-11-19T12:03:14.089Z","avatar_url":"https://github.com/kosaki08.png","language":"TypeScript","readme":"# uiMatch\n\n[![CI](https://github.com/kosaki08/uimatch/actions/workflows/ci.yml/badge.svg)](https://github.com/kosaki08/uimatch/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/kosaki08/uimatch/branch/main/graph/badge.svg)](https://codecov.io/gh/kosaki08/uimatch)\n\n\u003e ⚠️ **Status: Experimental / 0.x**\n\u003e This project is in early development. APIs may change without notice and are not production-ready.\n\u003e Feedback and contributions are welcome!\n\nDesign-to-implementation comparison tool that evaluates how closely an implemented UI matches a Figma design with pixel-level precision, color accuracy (ΔE2000), and automated quality scoring.\n\n---\n\n## Documentation\n\n**📖 [Full Documentation](https://kosaki08.github.io/uimatch/)**\n\n- [Getting Started](https://kosaki08.github.io/uimatch/docs/getting-started) - Installation and quickstart\n- [CLI Reference](https://kosaki08.github.io/uimatch/docs/cli-reference) - Complete command options\n- [Concepts](https://kosaki08.github.io/uimatch/docs/concepts) - Anchors, quality gates, content basis\n- [CI Integration](https://kosaki08.github.io/uimatch/docs/ci-integration) - GitHub Actions and CI setup\n- [Local Testing](https://kosaki08.github.io/uimatch/docs/local-testing) - Pack/link workflows for contributors\n- [Troubleshooting](https://kosaki08.github.io/uimatch/docs/troubleshooting) - Common issues and solutions\n- [Plugins](https://kosaki08.github.io/uimatch/docs/plugins) - Plugin development guide\n- [Experimental Features](https://kosaki08.github.io/uimatch/docs/experimental) - MCP and AI integration\n- [API Reference](https://kosaki08.github.io/uimatch/docs/api) - TypeScript API documentation\n\n---\n\n## Quick Start\n\n### Installation\n\n**Global install (for CLI usage):**\n\n```bash\nnpm install -g @uimatch/cli playwright\nnpx playwright install chromium\nexport FIGMA_ACCESS_TOKEN=\"figd_...\"\n```\n\n**Project install (for development/CI):**\n\n```bash\nnpm install -D @uimatch/cli playwright\nnpx playwright install chromium\n```\n\n### First Comparison\n\n**Note:** The examples below assume `@uimatch/cli` is already installed (globally or as a dev dependency).\n\n```bash\nnpx uimatch compare \\\n  figma=\u003cfileKey\u003e:\u003cnodeId\u003e \\\n  story=http://localhost:6006/?path=/story/button \\\n  selector=\"#root button\"\n```\n\n**Try without installing:**\n\nIf you want to run a quick test without installation:\n\n```bash\nnpx -p @uimatch/cli uimatch compare \\\n  figma=\u003cfileKey\u003e:\u003cnodeId\u003e \\\n  story=http://localhost:6006/?path=/story/button \\\n  selector=\"#root button\"\n```\n\n### Save Artifacts\n\n```bash\nnpx uimatch compare \\\n  figma=\u003cfileKey\u003e:\u003cnodeId\u003e \\\n  story=http://localhost:6006/?path=/story/button \\\n  selector=\"#root button\" \\\n  outDir=./uimatch-reports\n```\n\n**👉 See [Getting Started](https://kosaki08.github.io/uimatch/docs/getting-started) for detailed setup**\n\n---\n\n## Features\n\n- **Pixel-perfect comparison** - Visual diff with content-aware pixelmatch\n- **Color accuracy** - Perceptual color difference with ΔE2000\n- **Design Fidelity Score** - Automated 0-100 quality scoring (DFS)\n- **Figma integration** - Direct API access, MCP server support, or bypass mode\n- **Quality gates** - Configurable pass/fail thresholds with profiles\n- **Stable selectors** - AST-based anchors plugin for refactor-resistant targeting\n- **CI-ready** - GitHub Actions integration with caching and artifacts\n\n---\n\n## Common Usage Patterns\n\n### Component vs Component (Strict)\n\n```bash\nnpx uimatch compare \\\n  figma=... story=... selector=... \\\n  size=strict profile=component/strict\n```\n\n### Page vs Component (Padded)\n\n```bash\nnpx uimatch compare \\\n  figma=... story=... selector=... \\\n  size=pad contentBasis=intersection\n```\n\n**👉 See [CLI Reference](https://kosaki08.github.io/uimatch/docs/cli-reference) for selector anchors, suite mode, and all options**\n\n---\n\n## CI Integration\n\nMinimal GitHub Actions example:\n\n```yaml\nname: uiMatch QA\non: [pull_request]\n\njobs:\n  compare:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '22'\n\n      - name: Install\n        run: |\n          npm install -g @uimatch/cli playwright\n          npx playwright install --with-deps chromium\n\n      - name: Compare\n        env:\n          FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_TOKEN }}\n        run: |\n          npx uimatch compare \\\n            figma=${{ secrets.FIGMA_FILE }}:${{ secrets.FIGMA_NODE }} \\\n            story=https://storybook.com/?path=/story/button \\\n            selector=\"#root button\" \\\n            outDir=uimatch-reports \\\n            profile=component/strict\n\n      - name: Upload artifacts\n        if: always()\n        uses: actions/upload-artifact@v4\n        with:\n          name: uimatch-reports\n          path: uimatch-reports/\n```\n\n**👉 See [CI Integration Guide](https://kosaki08.github.io/uimatch/docs/ci-integration) for caching, bypass mode, suite configurations, and complete setup**\n\n---\n\n## Quality Gate Profiles\n\nBuilt-in profiles for different use cases:\n\n- `component/strict` - Pixel-perfect for design systems\n- `component/dev` - Development tolerance\n- `page-vs-component` - Loose layout comparison\n\n```bash\nnpx uimatch compare \\\n  figma=... story=... selector=... \\\n  profile=component/strict\n```\n\n**👉 See [CI Integration Guide](https://kosaki08.github.io/uimatch/docs/ci-integration#quality-gate-enforcement) for detailed thresholds and parameters**\n\n---\n\n## Architecture Overview\n\nAt a high level:\n\n- Fetch frame PNG from Figma (API / MCP / bypass)\n- Capture implementation screenshot via Playwright\n- Compare pixels + styles in `@uimatch/core`\n- Apply quality gates and compute DFS (0–100)\n- Report pass/fail and diff artifacts (for CI)\n\n**👉 See [Concepts - Architecture](https://kosaki08.github.io/uimatch/docs/concepts#architecture-overview) for detailed diagrams and component explanation**\n\n---\n\n## Development\n\n### Prerequisites\n\n- Node.js 20.19+ / 22.12+\n- pnpm 9.15.4+\n- Bun 1.x (test runner)\n\n### Setup\n\n```bash\npnpm install\npnpm build\npnpm test\n```\n\n### Verification\n\n```bash\n# Smoke test (no Figma/Storybook required)\npnpm build\nnode packages/uimatch-cli/dist/cli/index.js compare \\\n  figma=bypass:test \\\n  story=\"data:text/html,\u003cdiv style='width:10px;height:10px;background:red'\u003e\u003c/div\u003e\" \\\n  selector=\"div\" dpr=1 size=pad\n```\n\n**👉 See [Local Testing Guide](https://kosaki08.github.io/uimatch/docs/local-testing) for pack/link workflows**\n\n---\n\n## Troubleshooting\n\nRun diagnostics:\n\n```bash\nnpx uimatch doctor\n```\n\n**Common issues:**\n\n| Issue               | Solution                               |\n| ------------------- | -------------------------------------- |\n| Browser not found   | `npx playwright install chromium`      |\n| Figma token missing | `export FIGMA_ACCESS_TOKEN=\"figd_...\"` |\n| Want to see browser | `export UIMATCH_HEADLESS=false`        |\n\n**👉 See [Troubleshooting Guide](https://kosaki08.github.io/uimatch/docs/troubleshooting) for complete solutions**\n\n---\n\n## Packages\n\n**Public (npm):**\n\n- `@uimatch/cli` - CLI tool\n- `@uimatch/selector-anchors` - AST-based selector plugin\n- `@uimatch/selector-spi` - Plugin interface types\n- `@uimatch/shared-logging` - Logging utilities\n\n**Internal:**\n\n- `@uimatch/core` - Comparison engine\n- `@uimatch/scoring` - DFS calculator\n\n---\n\n## Project Structure\n\n```\nui-match/\n├── packages/\n│   ├── uimatch-cli/              # CLI entry point\n│   ├── uimatch-core/             # Comparison engine\n│   ├── uimatch-scoring/          # DFS calculation\n│   ├── uimatch-selector-spi/     # Plugin interface\n│   ├── uimatch-selector-anchors/ # AST plugin\n│   └── shared-logging/           # Logging utils\n└── docs/                         # Documentation site\n```\n\n---\n\n## Experiments / Skills\n\nThese markdown-based skills support AI-assisted workflows (Claude Code) and provide task-focused guides and references.\n\n- Visual Compare: `experiments/skills/uimatch-compare/SKILL.md`\n- Suite (Batch): `experiments/skills/uimatch-suite/SKILL.md`\n- Text Diff: `experiments/skills/uimatch-text-diff/SKILL.md`\n\nShared references:\n\n- `experiments/skills/_shared/uimatch-advanced-settings.md`\n- `experiments/skills/_shared/uimatch-common-env.md`\n\n👉 Important: export `FIGMA_ACCESS_TOKEN` in your shell (the CLI does not read `.env` automatically).\n👉 Prefer `FILE_KEY:NODE_ID` for Figma references; if you pass a full Figma URL, always quote it in the shell.\n\n---\n\n## Contributing\n\nContributions welcome! See [Local Testing](https://kosaki08.github.io/uimatch/docs/local-testing) for development workflows.\n\n---\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkosaki08%2Fuimatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkosaki08%2Fuimatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkosaki08%2Fuimatch/lists"}