{"id":49987543,"url":"https://github.com/onexeor-dev/lumo","last_synced_at":"2026-05-23T05:01:46.087Z","repository":{"id":358349723,"uuid":"1240576512","full_name":"OneXeor-Dev/lumo","owner":"OneXeor-Dev","description":"Mobile UI/UX design intelligence for AI coding assistants — WCAG validator with OKLCH auto-correct, cross-platform parity diff for Compose vs SwiftUI, and theory-of-design (Fitts / Hick / Gestalt) layout checks.","archived":false,"fork":false,"pushed_at":"2026-05-22T09:26:44.000Z","size":2225,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T11:31:14.285Z","etag":null,"topics":["accessibility","ai","android","claude","claude-code","cross-platform","cursor","design-system","fitts-law","gestalt","ios","jetpack-compose","mcp","mobile","model-context-protocol","oklch","swiftui","ui-ux","uikit","wcag"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@onexeor/lumo","language":"Python","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/OneXeor-Dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T09:55:36.000Z","updated_at":"2026-05-22T09:25:25.000Z","dependencies_parsed_at":"2026-05-21T03:00:52.471Z","dependency_job_id":null,"html_url":"https://github.com/OneXeor-Dev/lumo","commit_stats":null,"previous_names":["onexeor-dev/lumo"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/OneXeor-Dev/lumo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneXeor-Dev%2Flumo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneXeor-Dev%2Flumo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneXeor-Dev%2Flumo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneXeor-Dev%2Flumo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneXeor-Dev","download_url":"https://codeload.github.com/OneXeor-Dev/lumo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneXeor-Dev%2Flumo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33383233,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["accessibility","ai","android","claude","claude-code","cross-platform","cursor","design-system","fitts-law","gestalt","ios","jetpack-compose","mcp","mobile","model-context-protocol","oklch","swiftui","ui-ux","uikit","wcag"],"created_at":"2026-05-19T01:00:27.139Z","updated_at":"2026-05-23T05:01:46.033Z","avatar_url":"https://github.com/OneXeor-Dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lumo\n\n\u003e Mobile UI/UX design intelligence for AI coding assistants, grounded in\n\u003e cognitive science — not just style guides.\n\n**Status:** v0.2.0 published (alpha — PyPI and npm versions stay in lock-\nstep). Eight tools work (`lumo-wcag`, `lumo-theory`, `lumo-parity`,\n`lumo-source`, `lumo-audit`, `lumo-figma`, `lumo-render`, plus the\n`lumo-mcp` server), five install paths are live (`npx @onexeor/lumo init`\n· `npx skills add` · Claude plugin marketplace · `pipx install lumo-mobile`\n· git clone), and the MCP server exposes all eleven functions\n(`lumo_wcag_check` / `_fix`, `lumo_theory_check`, `lumo_parity_diff`,\n`lumo_source_check_compose` / `_swiftui`, `lumo_audit_scan`,\n`lumo_figma_diff`, `lumo_figma_render`, `lumo_render_compose` /\n`_swiftui`) to every major AI client.\n\nLumo helps mobile developers build polished, accessible UI by applying\n**Fitts**, **Hick**, **Gestalt**, and **Nielsen** alongside Apple HIG and\nMaterial Design. The hard checks (WCAG luminance, OKLCH correction,\ncross-platform diff) run as **deterministic Python tools**, not LLM\nguesses.\n\n## What works today\n\n| Tool | What it does |\n|---|---|\n| `lumo-wcag` | WCAG AA / AAA contrast checker + OKLCH auto-correct that preserves chroma and hue. Catches the contrast pairs Claude misjudges by eye. |\n| `lumo-theory` | Cognitive-science layout checks: undersized tap targets, relative Fitts difficulty for primary actions, Hick overload in equal-weight choice groups, Gestalt proximity violations, one-handed reachability. |\n| `lumo-parity` | Cross-platform diff between Android (Compose / XML, in dp) and iOS (SwiftUI / UIKit, in pt). Flags size and component mismatches. Whitelists known platform divergences (Material 48 dp vs Apple HIG 44 pt, etc.) so the noise stays out. Optional `lumo.config.json` validates both platforms against shared design tokens. |\n| `lumo-source` | AST-based design-system drift checks for Jetpack Compose `.kt` and SwiftUI `.swift` files. Flags hardcoded colours, off-scale paddings / radii, and undersized tap targets (Material 48dp on Compose, Apple HIG 44pt on SwiftUI) — but never trips on theme tokens (`MaterialTheme.*`, `LocalDimensions.*`, `Color(\"brand…\")`, asset-catalog lookups) since those are exactly what Lumo wants to encourage. |\n| `lumo-audit` | Whole-repository scan. Walks every `.kt` / `.swift` file, aggregates `lumo-source` findings, and surfaces the *measured* spacing / radius scale — the actual frequency of every hardcoded literal in the codebase. Lets you compare what your design system claims against what the code actually does. |\n| `lumo-figma diff` | Diff Figma design tokens (COLOR + FLOAT variables) against the audited code. Matches by value, not name. Three buckets: matched, unused-in-code (candidates for review), and missing-from-Figma (heavy code values waiting to be promoted to the design system). |\n| `lumo-figma render` | Render a Figma frame to a Lumo layout JSON with `source: \"measured\"` — Figma's `absoluteBoundingBox` is the rendered coordinate after Auto-Layout resolves. Lets `lumo-theory` / `lumo-parity` run on the design itself BEFORE any code ships. No more hand-built layout JSON for design audits. |\n| `lumo-render` | AST layout evaluator for Compose `.kt` and SwiftUI `.swift`. Produces measured-like `(x, y, w, h)` coordinates from source with no build, no app run, no snapshot test. Output feeds `lumo-theory` and `lumo-parity` directly. Honest about what it can't derive: token references and unknown composables come back as `ast-unresolved` with a reason, never invented numbers. New honesty label slot: `measured \u003e ast-resolved \u003e code-estimated \u003e description-estimated`. |\n| `lumo-mcp` | Model Context Protocol server. Exposes all of the above to Claude Code, Cursor, Continue, Aider, Goose, Zed, OpenAI Codex CLI, and any other MCP-aware client. |\n\nEach tool returns structured findings (severity, recommendation, metric)\nand propagates an honest confidence label — `measured`, `code-estimated`,\nor `description-estimated` — so the consumer can weigh the result.\n\n## Demo\n\n![Lumo demo: wcag fix, parity diff, theory check](./assets/demo.gif)\n\nReal output from the Lumo CLIs, no screenshots or hand edits. Rebuild\nlocally with `bash assets/record-demo.sh` after a `pip install -e \".[dev]\"`\nin `tools/` and `brew install asciinema agg`. (The GIF currently shows\n`lumo-wcag`, `lumo-parity`, and `lumo-theory` — `lumo-source` is captured\nin the worked examples below the install section instead.)\n\n### WCAG auto-correct in OKLCH (preserves brand chroma and hue)\n\n```\n$ lumo-wcag fix --fg '#7DD3FC' --bg '#FFFFFF'\nFIXED  #7DD3FC → #1B7BA1  on #FFFFFF\n       ratio 1.667:1 → 4.779:1  (required 4.5:1)\n       strategy=darken_fg  iterations=14\n```\n\n### Cross-platform parity diff (catches the 16dp / 48pt junior bug)\n\n```\n$ lumo-parity diff \\\n    --android examples/parity_android.json \\\n    --ios     examples/parity_ios.json \\\n    --config  examples/lumo.config.json\n\nFOUND  6 parity findings (1 high, 2 info, 3 medium)\n\n  1. [HIGH    ] component_missing_on_ios\n     element: fab_add\n     android: present    ios: missing\n\n  2. [MEDIUM  ] height_mismatch\n     element: card_offer\n     android: 16.0    ios: 48.0\n     'card_offer' height differs: Android 16.0dp vs iOS 48.0pt.\n     dp and pt are both density-independent and should match.\n\n  5. [INFO    ] platform_specific_default\n     element: nav_back\n     android: 48.0    ios: 44.0\n     'nav_back' differs by design: Material 48dp vs Apple HIG 44pt.\n```\n\nThe full real output is captured in [examples/](./examples/) and rendered\nby the actual binaries — no screenshots, no hand-edited results.\n\n## Install\n\nPick the path that fits your workflow:\n\n### 1. One-command installer (`@onexeor/lumo`)\n\n```bash\nnpx @onexeor/lumo init                    # interactive — picks your AI client\nnpx @onexeor/lumo init --ai claude        # explicit target\nnpx @onexeor/lumo init --all              # install everywhere supported\n\n# After install the binary is just `lumo`:\nlumo doctor\nlumo uninstall --ai claude\n```\n\nInstalls Python tools into `~/.lumo/venv`, copies the skill bundle into\nyour chosen AI client, and registers the MCP server in that client's\nconfig. See [installer/README.md](./installer/README.md) for the full\nflag list. Also ships `lumo doctor` and `lumo uninstall`.\n\n### 2. `npx skills add` (vercel-labs/skills)\n\n```bash\nnpx skills add OneXeor-Dev/lumo\n```\n\nThe `skills.json` manifest at the repo root makes Lumo a first-class\ncitizen of the `npx skills` ecosystem. Works for any client supported\nby the `skills` CLI.\n\n### 3. Claude Code plugin marketplace\n\n```bash\nclaude plugin marketplace add OneXeor-Dev/lumo\nclaude plugin install lumo@lumo\n```\n\nUses the `.claude-plugin/marketplace.json` manifest — same pattern as\n`apple-skills` and other native Claude Code plugins.\n\n### 4. Direct Python install (no AI client)\n\n```bash\npipx install lumo-mobile          # global CLI install\n# or\npip install lumo-mobile           # any existing venv\n```\n\nGives you the seven CLIs (`lumo-wcag`, `lumo-theory`, `lumo-parity`,\n`lumo-source`, `lumo-audit`, `lumo-figma`, `lumo-mcp`) without touching\nany AI client config. Use this if you want to wire Lumo into CI, scripts,\nor a custom workflow.\n\n### 5. Git clone + manual\n\n```bash\ngit clone https://github.com/OneXeor-Dev/lumo.git\ncp -r lumo/skill ~/.claude/skills/lumo\ncd lumo/tools \u0026\u0026 pip install -e .\n```\n\nZero-installer fallback for users who prefer to see every file move\nthemselves (the [`material-3-skill`](https://github.com/hamen/material-3-skill)\nmodel).\n\n## Wiring the MCP server into your AI client manually\n\nIf you'd rather not run `npx @onexeor/lumo init` and you already have\n`lumo-mobile` installed (via `pipx install lumo-mobile` or any other\nPython install), point your AI client at the `lumo-mcp` binary directly.\nThe installer does this for you; this section is the manual fallback.\n\nFirst, find the absolute path of `lumo-mcp`:\n\n```bash\nwhich lumo-mcp\n# typically: /Users/\u003cyou\u003e/.local/bin/lumo-mcp     (pipx)\n#       or: /Users/\u003cyou\u003e/.lumo/venv/bin/lumo-mcp  (npx installer)\n```\n\nThen add Lumo to your client's MCP config. The shape is the same\neverywhere — only the file path differs:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"lumo\": {\n      \"command\": \"/absolute/path/to/lumo-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nPer-client paths:\n\n| Client | Config file |\n|---|---|\n| Claude Desktop / Claude Code (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop / Claude Code (Linux / Windows fallback) | `~/.claude/claude_desktop_config.json` |\n| Cursor | `~/.cursor/mcp.json` |\n| OpenAI Codex CLI | `~/.codex/mcp.json` |\n| Continue, Aider, Goose, Zed | each client's own MCP config — same `mcpServers` shape |\n\nRestart the client after editing the config. Verify with\n`lumo doctor` (if you installed via `npx @onexeor/lumo init`) — it will\nmark MCP as registered for each client whose config now contains the\n`lumo` server.\n\n## Why Lumo\n\nMost AI design skills regurgitate platform style guides. Lumo is different\nin three ways:\n\n1. **Cognitive science first.** Numeric thresholds derived from Fitts /\n   Hick / Gestalt research, applied as concrete checks. Where the\n   underlying constants are device-dependent and shaky (absolute Fitts\n   movement time in ms), Lumo reports relative comparisons instead of\n   inventing numbers.\n2. **Cross-platform parity.** Catches the classic junior bug — writing\n   `padding(16.dp)` on Android and `.padding(48)` on SwiftUI under the\n   \"iOS uses 3× because Retina\" misconception — and any other size or\n   presence drift between the two platforms.\n3. **Deterministic tools, not just prompts.** Real W3C luminance math,\n   real OKLCH conversion, real geometric checks, real `tree-sitter` AST\n   walking. None of the shipped tools depends on an LLM at runtime.\n\n## Target platforms (v1)\n\n- **Android:** Jetpack Compose + XML layouts\n- **iOS:** SwiftUI + UIKit\n\nFlutter and React Native are on the v2 roadmap.\n\n## Running locally for development\n\n```bash\ngit clone git@github.com:OneXeor-Dev/lumo.git\ncd lumo/tools\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\n\n# Smoke\nlumo-wcag check --fg \"#3B82F6\" --bg \"#FFFFFF\"\nlumo-theory check --layout ../examples/theory_bad_layout.json\nlumo-parity diff \\\n  --android ../examples/parity_android.json \\\n  --ios     ../examples/parity_ios.json \\\n  --config  ../examples/lumo.config.json\n\n# Tests\npytest        # 67 passing\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonexeor-dev%2Flumo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonexeor-dev%2Flumo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonexeor-dev%2Flumo/lists"}