lumo-mobile 0.0.1__tar.gz

lumo_mobile-0.0.1/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: lumo-mobile
+Version: 0.0.1
+Summary: Deterministic mobile UI/UX checks for Compose / SwiftUI / XML / UIKit — WCAG validator with OKLCH auto-correct, cross-platform parity diff, cognitive-science (Fitts / Hick / Gestalt) layout checks. Ships with an MCP server.
+Author: Viktor Savchik
+License: MIT
+Project-URL: Homepage, https://github.com/OneXeor/lumo
+Project-URL: Repository, https://github.com/OneXeor/lumo
+Project-URL: Issues, https://github.com/OneXeor/lumo/issues
+Keywords: mobile,design,ui,ux,wcag,accessibility,jetpack-compose,swiftui,uikit,android,ios,fitts,gestalt,design-system,cross-platform,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: mcp>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+
+# lumo-mobile
+
+Deterministic mobile UI/UX checks invoked by [Lumo](https://github.com/OneXeor/lumo) — a
+Claude Code skill / MCP server / CLI toolkit for designing polished mobile
+apps on Jetpack Compose, Android XML, SwiftUI, and UIKit.
+
+Install:
+
+```bash
+pipx install lumo-mobile
+```
+
+Three CLIs (plus one MCP server) ship:
+
+| Command | What it does |
+|---|---|
+| `lumo-wcag check --fg <hex> --bg <hex>` | WCAG AA / AAA contrast verdict using the W3C luminance formula. |
+| `lumo-wcag fix   --fg <hex> --bg <hex>` | OKLCH auto-correct that preserves hue and chroma while pushing the contrast above the threshold. |
+| `lumo-theory check --layout <path>` | Cognitive-science layout checks: Fitts (undersized targets, relative difficulty for primaries), Hick overload, Gestalt proximity, one-handed reachability. |
+| `lumo-parity diff --android <path> --ios <path> [--config <path>]` | Cross-platform diff between Android (dp) and iOS (pt) layouts, with optional design-system token validation. |
+| `lumo-mcp` | Model Context Protocol server (stdio) exposing all of the above to Claude Code, Cursor, Continue, Aider, Goose, Zed, Codex. |
+
+See the [main repo](https://github.com/OneXeor/lumo) for the full SKILL.md,
+examples, and rationale.
+
+## License
+
+MIT

lumo_mobile-0.0.1/README.md

@@ -0,0 +1,28 @@
+# lumo-mobile
+
+Deterministic mobile UI/UX checks invoked by [Lumo](https://github.com/OneXeor/lumo) — a
+Claude Code skill / MCP server / CLI toolkit for designing polished mobile
+apps on Jetpack Compose, Android XML, SwiftUI, and UIKit.
+
+Install:
+
+```bash
+pipx install lumo-mobile
+```
+
+Three CLIs (plus one MCP server) ship:
+
+| Command | What it does |
+|---|---|
+| `lumo-wcag check --fg <hex> --bg <hex>` | WCAG AA / AAA contrast verdict using the W3C luminance formula. |
+| `lumo-wcag fix   --fg <hex> --bg <hex>` | OKLCH auto-correct that preserves hue and chroma while pushing the contrast above the threshold. |
+| `lumo-theory check --layout <path>` | Cognitive-science layout checks: Fitts (undersized targets, relative difficulty for primaries), Hick overload, Gestalt proximity, one-handed reachability. |
+| `lumo-parity diff --android <path> --ios <path> [--config <path>]` | Cross-platform diff between Android (dp) and iOS (pt) layouts, with optional design-system token validation. |
+| `lumo-mcp` | Model Context Protocol server (stdio) exposing all of the above to Claude Code, Cursor, Continue, Aider, Goose, Zed, Codex. |
+
+See the [main repo](https://github.com/OneXeor/lumo) for the full SKILL.md,
+examples, and rationale.
+
+## License
+
+MIT

lumo_mobile-0.0.1/lumo/__init__.py

@@ -0,0 +1,3 @@
+"""Lumo — mobile design tools invoked by the Lumo Claude Code skill."""
+
+__version__ = "0.0.1"

lumo_mobile-0.0.1/lumo/mcp/__init__.py

@@ -0,0 +1,10 @@
+"""MCP server exposing Lumo tools to any MCP-compatible client.
+
+Public API:
+    server  — the FastMCP instance (importable for tests and custom mounts)
+    main()  — stdio entrypoint, registered as `lumo-mcp` console script
+"""
+
+from lumo.mcp.server import main, server
+
+__all__ = ["main", "server"]

lumo_mobile-0.0.1/lumo/mcp/server.py

@@ -0,0 +1,249 @@
+"""Lumo MCP server.
+
+Exposes the three Lumo tools (WCAG, theory, parity) over the Model Context
+Protocol so any MCP-compatible client (Claude Code, Cursor, Continue,
+Aider, Goose, Zed, etc.) can call them with structured arguments.
+
+This is a thin wrapper over the existing Python API — the heavy lifting
+stays in lumo.wcag, lumo.theory, lumo.parity. Adding MCP did not change a
+single line of those modules.
+
+Transport: stdio (the MCP standard for local servers).
+
+Run directly:
+    lumo-mcp
+
+Or for development:
+    python -m lumo.mcp.server
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from lumo.parity.core import DesignSystemConfig, diff
+from lumo.theory.core import Element, Layout, Screen, check_layout
+from lumo.wcag.core import auto_correct, check_pair
+
+server = FastMCP("lumo")
+
+
+# ============================================================================
+# Tool 1 — WCAG check
+# ============================================================================
+
+
+@server.tool()
+def lumo_wcag_check(
+    fg: str,
+    bg: str,
+    level: Literal["AA", "AAA"] = "AA",
+    size: Literal["normal", "large"] = "normal",
+) -> dict[str, Any]:
+    """Check whether a foreground/background color pair meets WCAG contrast.
+
+    Uses the W3C relative luminance formula. Returns the exact contrast ratio,
+    the required threshold for the given level + text size, and a pass / fail
+    verdict. This is deterministic math, not an LLM guess.
+
+    Args:
+        fg: Foreground hex (#RGB, #RRGGBB, #RGBA, or #RRGGBBAA — alpha ignored)
+        bg: Background hex (same formats)
+        level: "AA" (4.5:1 normal / 3:1 large) or "AAA" (7:1 / 4.5:1)
+        size: "normal" or "large" (large = ≥18pt or ≥14pt bold)
+
+    Returns:
+        Dict with fg, bg, ratio, level, size, required, passes.
+    """
+    result = check_pair(fg, bg, level, size)
+    return asdict(result)
+
+
+# ============================================================================
+# Tool 2 — WCAG auto-correct
+# ============================================================================
+
+
+@server.tool()
+def lumo_wcag_fix(
+    fg: str,
+    bg: str,
+    level: Literal["AA", "AAA"] = "AA",
+    size: Literal["normal", "large"] = "normal",
+    max_iterations: int = 60,
+) -> dict[str, Any]:
+    """Auto-correct a failing foreground color to meet WCAG, preserving hue and chroma.
+
+    Adjusts the foreground's L-channel in OKLCH (perceptually uniform color
+    space) until the pair passes. Brand identity stays intact because chroma
+    and hue are held fixed. Returns the corrected hex plus iteration count
+    and direction (darken_fg / lighten_fg / unchanged).
+
+    Args:
+        fg: Foreground hex to correct
+        bg: Background hex (untouched)
+        level: "AA" or "AAA"
+        size: "normal" or "large"
+        max_iterations: safety bound on the iterative search
+
+    Returns:
+        Dict with original CheckResult, corrected_fg, corrected_bg, corrected
+        CheckResult, iterations, and strategy.
+    """
+    result = auto_correct(fg, bg, level, size, max_iterations)
+    return {
+        "original": asdict(result.original),
+        "corrected_fg": result.corrected_fg,
+        "corrected_bg": result.corrected_bg,
+        "corrected": asdict(result.corrected),
+        "iterations": result.iterations,
+        "strategy": result.strategy,
+    }
+
+
+# ============================================================================
+# Tool 3 — theory_check
+# ============================================================================
+
+
+@server.tool()
+def lumo_theory_check(layout: dict[str, Any]) -> dict[str, Any]:
+    """Run cognitive-science layout checks (Fitts, Hick, Gestalt, reach).
+
+    Accepts a layout JSON (same schema as the lumo-theory CLI). Returns
+    findings with severity, recommendation, and the metric that produced
+    them. Each finding inherits a confidence label from the layout's
+    `source` field — `measured` / `code-estimated` / `description-estimated`
+    — so the consumer can weigh trust honestly.
+
+    Tool does NOT produce absolute Fitts MT or Hick RT in ms. Those depend
+    on device-specific constants with ±40% variance; we return relative
+    ratios and discrete flags instead.
+
+    Args:
+        layout: Layout JSON with keys `screen` ({width, height, unit}),
+                `source` (one of measured | code-estimated |
+                description-estimated), and `elements` (list of element
+                dicts with id, role, x, y, w, h, optional group + weight).
+
+    Returns:
+        Dict with `source`, `counts_by_severity`, and `findings` list.
+    """
+    screen = Screen(
+        width=float(layout["screen"]["width"]),
+        height=float(layout["screen"]["height"]),
+        unit=layout["screen"].get("unit", "dp"),
+    )
+    elements = tuple(
+        Element(
+            id=str(e["id"]),
+            role=e["role"],
+            x=float(e["x"]),
+            y=float(e["y"]),
+            w=float(e["w"]),
+            h=float(e["h"]),
+            group=e.get("group"),
+            weight=e.get("weight", "equal"),
+        )
+        for e in layout.get("elements", [])
+    )
+    parsed = Layout(screen=screen, elements=elements, source=layout.get("source", "description-estimated"))
+    report = check_layout(parsed)
+    return {
+        "source": report.source,
+        "counts_by_severity": report.counts_by_severity,
+        "findings": [asdict(f) for f in report.findings],
+    }
+
+
+# ============================================================================
+# Tool 4 — platform_parity
+# ============================================================================
+
+
+@server.tool()
+def lumo_parity_diff(
+    android: dict[str, Any],
+    ios: dict[str, Any],
+    config: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Diff an Android (dp) and iOS (pt) layout, optionally against a design system.
+
+    Compares the two layouts for component presence and sizing mismatches.
+    Whitelists known platform-specific defaults (Material 48dp vs Apple HIG
+    44pt touch target; Material bottom nav 80dp vs iOS Tab Bar 49pt) and
+    reports them as `info`, not as mismatches.
+
+    Reminder: dp and pt are both density-independent and equal in physical
+    size on screen. 16dp matches 16pt. The classic "iOS uses 3× because
+    Retina" misconception (writing 48pt on iOS for 16dp Android) is exactly
+    the bug this tool catches.
+
+    Args:
+        android: Android layout JSON (same schema as lumo_theory_check)
+        ios: iOS layout JSON
+        config: Optional design-system config with `spacing`, `sizing`,
+                `colors` token maps
+
+    Returns:
+        Dict with `confidence`, `android_source`, `ios_source`,
+        `counts_by_severity`, and `findings` list.
+    """
+
+    def _to_layout(data: dict[str, Any]) -> Layout:
+        screen = Screen(
+            width=float(data["screen"]["width"]),
+            height=float(data["screen"]["height"]),
+            unit=data["screen"].get("unit", "dp"),
+        )
+        elements = tuple(
+            Element(
+                id=str(e["id"]),
+                role=e["role"],
+                x=float(e["x"]),
+                y=float(e["y"]),
+                w=float(e["w"]),
+                h=float(e["h"]),
+                group=e.get("group"),
+                weight=e.get("weight", "equal"),
+            )
+            for e in data.get("elements", [])
+        )
+        return Layout(screen=screen, elements=elements, source=data.get("source", "description-estimated"))
+
+    android_layout = _to_layout(android)
+    ios_layout = _to_layout(ios)
+
+    ds_config = None
+    if config is not None:
+        ds_config = DesignSystemConfig(
+            spacing=config.get("spacing", {}),
+            sizing=config.get("sizing", {}),
+            colors=config.get("colors", {}),
+        )
+
+    report = diff(android_layout, ios_layout, ds_config)
+    return {
+        "confidence": report.confidence,
+        "android_source": report.android_source,
+        "ios_source": report.ios_source,
+        "counts_by_severity": report.counts_by_severity,
+        "findings": [asdict(f) for f in report.findings],
+    }
+
+
+# ============================================================================
+# Entrypoint
+# ============================================================================
+
+
+def main() -> None:
+    """Run the Lumo MCP server over stdio (the MCP standard for local tools)."""
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

lumo_mobile-0.0.1/lumo/parity/__init__.py

@@ -0,0 +1,31 @@
+"""Cross-platform parity diff for Android (Compose / XML) vs iOS (SwiftUI / UIKit).
+
+Public API:
+    diff(android, ios, config=None) -> ParityReport
+
+The diff compares two layout JSONs (same schema as theory_check) and, when
+provided, validates both against a shared design-system config.
+
+Honest design notes:
+    - dp and pt are both density-independent. A 16dp / 16pt comparison is
+      legitimate (NOT 16dp / 48pt — that's a known junior misconception).
+    - Some numeric discrepancies are *expected* per platform standards
+      (44pt touch target vs 48dp, 49pt Tab Bar vs 80dp bottom nav,
+      17pt iOS body text vs 16sp Material). These live in the whitelist
+      and are reported as `info`, not `mismatch`.
+    - Confidence propagates from the lower of the two input sources.
+"""
+
+from lumo.parity.core import (
+    DesignSystemConfig,
+    ParityFinding,
+    ParityReport,
+    diff,
+)
+
+__all__ = [
+    "DesignSystemConfig",
+    "ParityFinding",
+    "ParityReport",
+    "diff",
+]

lumo_mobile-0.0.1/lumo/parity/cli.py

@@ -0,0 +1,123 @@
+"""CLI for platform_parity.
+
+Usage:
+    lumo-parity diff --android <path|-> --ios <path|-> [--config <path>] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from lumo.parity.core import DesignSystemConfig, diff
+from lumo.theory.core import Element, Layout, Screen
+
+
+def _load_layout(source: str) -> Layout:
+    raw = sys.stdin.read() if source == "-" else Path(source).read_text(encoding="utf-8")
+    data: dict[str, Any] = json.loads(raw)
+    screen = Screen(
+        width=float(data["screen"]["width"]),
+        height=float(data["screen"]["height"]),
+        unit=data["screen"].get("unit", "dp"),
+    )
+    elements = tuple(
+        Element(
+            id=str(e["id"]),
+            role=e["role"],
+            x=float(e["x"]),
+            y=float(e["y"]),
+            w=float(e["w"]),
+            h=float(e["h"]),
+            group=e.get("group"),
+            weight=e.get("weight", "equal"),
+        )
+        for e in data.get("elements", [])
+    )
+    return Layout(screen=screen, elements=elements, source=data.get("source", "description-estimated"))
+
+
+def _load_config(path: str) -> DesignSystemConfig:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    return DesignSystemConfig(
+        spacing=data.get("spacing", {}),
+        sizing=data.get("sizing", {}),
+        colors=data.get("colors", {}),
+    )
+
+
+def _print_human(report: Any) -> None:
+    if not report.findings:
+        print("OK  Android and iOS layouts are in parity.")
+        print(f"    confidence: {report.confidence}")
+        print(f"    android: {report.android_source}, ios: {report.ios_source}")
+        return
+
+    counts = report.counts_by_severity
+    severity_summary = ", ".join(
+        f"{n} {sev}" for sev, n in sorted(counts.items(), key=lambda x: x[0])
+    )
+    print(f"FOUND  {len(report.findings)} parity findings ({severity_summary})")
+    print(f"       confidence: {report.confidence}")
+    print(f"       android: {report.android_source}, ios: {report.ios_source}\n")
+
+    for i, f in enumerate(report.findings, 1):
+        print(f"  {i}. [{f.severity.upper():8}] {f.check}")
+        if f.element_id:
+            print(f"     element: {f.element_id}")
+        if f.android_value is not None or f.ios_value is not None:
+            print(f"     android: {f.android_value}    ios: {f.ios_value}")
+        print(f"     {f.message}")
+        print(f"     → {f.recommendation}")
+        print()
+
+
+def _print_json(report: Any) -> None:
+    payload = {
+        "confidence": report.confidence,
+        "android_source": report.android_source,
+        "ios_source": report.ios_source,
+        "counts_by_severity": report.counts_by_severity,
+        "findings": [asdict(f) for f in report.findings],
+    }
+    print(json.dumps(payload, indent=2, default=str))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="lumo-parity",
+        description="Cross-platform parity diff: Android (dp) vs iOS (pt).",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("diff", help="Diff two layouts and (optionally) validate against a design system.")
+    d.add_argument("--android", required=True, help="Path to Android layout JSON, or '-' for stdin.")
+    d.add_argument("--ios", required=True, help="Path to iOS layout JSON, or '-' for stdin.")
+    d.add_argument("--config", default=None, help="Optional lumo.config.json with design tokens.")
+    d.add_argument("--json", action="store_true", help="Emit JSON.")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "diff":
+        if args.android == "-" and args.ios == "-":
+            print("error: cannot read both layouts from stdin", file=sys.stderr)
+            return 2
+        android = _load_layout(args.android)
+        ios = _load_layout(args.ios)
+        config = _load_config(args.config) if args.config else None
+        report = diff(android, ios, config)
+        if args.json:
+            _print_json(report)
+        else:
+            _print_human(report)
+        return 0 if not report.findings else 1
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())