{"id":51230462,"url":"https://github.com/suraj787/motif","last_synced_at":"2026-06-28T16:00:26.527Z","repository":{"id":367733530,"uuid":"1282096264","full_name":"Suraj787/motif","owner":"Suraj787","description":"Open-source interaction-design intelligence for AI coding agents - securely discover, select, adapt and validate UI motion, effects and interaction patterns.","archived":false,"fork":false,"pushed_at":"2026-06-27T10:55:55.000Z","size":500,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T12:09:36.010Z","etag":null,"topics":["accessibility","agent-skills","application-security","claude-code","frontend","interaction-design","motion-design","open-source","react","svelte","ui-animation","vue","web-performance"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Suraj787.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":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":"2026-06-27T10:13:24.000Z","updated_at":"2026-06-27T10:55:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Suraj787/motif","commit_stats":null,"previous_names":["suraj787/open-interaction-intelligence"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Suraj787/motif","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suraj787%2Fmotif","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suraj787%2Fmotif/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suraj787%2Fmotif/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suraj787%2Fmotif/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Suraj787","download_url":"https://codeload.github.com/Suraj787/motif/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suraj787%2Fmotif/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34894560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"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":["accessibility","agent-skills","application-security","claude-code","frontend","interaction-design","motion-design","open-source","react","svelte","ui-animation","vue","web-performance"],"created_at":"2026-06-28T16:00:18.063Z","updated_at":"2026-06-28T16:00:26.514Z","avatar_url":"https://github.com/Suraj787.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Motif\n\n**Design judgment, interface engineering, assurance, and governance for AI coding agents.**\n\nAI coding agents already know how to generate interface code. They do not reliably know\nwhat should be built, why a design choice belongs, whether a pattern fits the user and\nworkflow, whether the output is generic, whether it is accessible, whether it is fast on\nreal devices, whether third-party code is safe and legally reusable, whether it fits the\nexisting design language, or whether the codebase stays coherent after many changes.\nMotif is the intelligence and governance layer that answers those\nquestions.\n\n[![CI](https://github.com/Suraj787/motif/actions/workflows/ci.yml/badge.svg)](https://github.com/Suraj787/motif/actions)\n\u0026nbsp;Licence: MIT. Status: v3.0.0 \"Evidence-Grounded Interface Engineering\" (interaction core shipped as v1.0.0; intelligence platform as v2.0.0)\n\n\u003e Defining principle: first determine what the user needs to understand, feel, decide, or\n\u003e accomplish, then choose the least complex interface and interaction that achieves it.\n\u003e Visual novelty never outranks usability, accessibility, security, performance, or\n\u003e maintainability.\n\n## Honesty first\n\nThis README distinguishes what is **implemented**, **experimental**, and **planned**. See\nthe full [capability matrix](docs/capability-matrix.md). Nothing marked planned is claimed\nto work. Anything you can run is covered by `make check`.\n\n## The six engines\n\n```\nProduct intent\n\u003e Product Intelligence      (context manifest: facts vs inference vs assumption)\n\u003e Design Intelligence       (styles, colour, typography, layout, ux-principles, industry packs)\n\u003e Interaction Intelligence  (patterns before effects, motion + density grammars, state completeness)\n\u003e Implementation            (framework detection, controlled install, rollback, provenance)\n\u003e Assurance                 (security static scans, evidence model; runtime checks planned)\n\u003e Governance and Learning   (design genome, interaction graph, originality, decisions, debt, drift)\n```\n\nThe Interaction Intelligence Engine and Secure Component Supply Chain are the validated\n**Motif** interaction foundation (originally the v1.0 core) (90 web-verified sources, 64\ncomponents, 30 effects, 28 patterns, 14 recipes, 5 scanners, controlled installer). Vue and\nFrappe-Vue are first-class.\n\n## What you can run today (implemented)\n\n```bash\nii inspect                              # detect the target project's framework + conventions\nii model-product                        # scaffold a Product Context Manifest\nii context validate                     # validate manifests (uncertainty stays explicit)\nii genome validate|explain|diff \u003cname\u003e  # Product Design Genome\nii graph validate|query \u003cname\u003e          # Interaction Specification Graph (surfaces real gaps)\nii originality audit \u003cpath\u003e [--product-form ...]   # aesthetic-convergence risk over real source\nii states matrix|validate|inspect       # State Completeness Engine\nii motion validate ; ii density validate\nii debt calculate \u003cpath\u003e                # explainable Interface Debt Score\nii decision create|list                 # design decision ledger\nii source scan \u003cpath\u003e                   # 5 security scanners (foundation)\nii component plan-install \u003cid\u003e --target \u003cdir\u003e   # controlled install plan\nii search \"\u003cquery\u003e\" ; ii rank \u003cpattern\u003e # registry search + transparent ranking\nii validate ; ii doctor                 # validate all engine data; health check\nmake check                              # full local gate (mirrors CI)\n```\n\n`motif` is the primary command; `ii` and `oii` are aliases. All three expose the full platform.\n\n### Motif Live (v3, runtime and governance)\n\n```bash\nmotif init                        # first run: inspect, create .motif/, first audit\nmotif improve --target ./app --goal \"Make project risk easier to scan\"\nmotif findings audit|list         # unified findings with evidence + lifecycle\nmotif policy init|check           # policy as code (blocking thresholds)\nmotif memory add --type rejected-approach --content \"...\"   # auditable project memory\nmotif atlas build                 # static public catalogue from the registry\nmotif system extract              # extract the project's design system\nmotif guard branch --base main    # Guardian: scan a diff against policy\nmotif mcp serve                   # MCP server (read tools + guarded writes)\nmotif studio                      # local read-only Studio viewer\nmotif bench --target ./app        # InterfaceBench automated measures\n```\n\nThe browser-runtime surfaces (Visual Twin rendering, Playwright assurance, live preview,\nsemantic visual diff, interactive apply) are marked experimental and never fake output.\nSee the [capability matrix](docs/capability-matrix.md) and\n[v3 architecture](docs/architecture/motif-v3-live-architecture.md).\n\n### Evidence-grounded runtime (v3.0.0)\n\n```bash\nmotif evidence query --product-form dashboard --purpose monitor --ability colour-vision-deficiency --risk financial:3\nmotif evidence evaluate --product-form dashboard --workflow daily-operation \u003cpath\u003e   # applicable claims + findings -\u003e evidence-backed enforcement\nmotif evidence explain claim-status-colour-001     # source, tier, limitations, validation\nmotif evidence check-myth \"three click rule\"\nmotif repair golden --target evals/fixtures/sample-vue-app --route /projects   # detect -\u003e evidence -\u003e worktree fix -\u003e verify -\u003e exact rollback -\u003e report\nmotif doctor --browser                              # browser runtime status (optional motif[browser] extra)\n```\n\nA version-controlled UX Evidence Graph (110 Tier 1-3 claims with sources, limitations, and\nvalidation) grounds the audit-and-repair decisions. Browser capture/validation is an\noptional extra and reports `not-executed` without a runtime, never faked.\n\nAn applicable claim is not a finding. `motif evidence query` returns applicable claims and\nthe normative requirements to evaluate (status `needs_evaluation`), never evidence-free\nblocking. `motif evidence evaluate` correlates detector findings to claims and produces\nevidence-backed enforcement: a claim blocks only when it is an applicable normative,\nmachine-detectable claim with a correlated finding at sufficient confidence and no unresolved\ncontradiction; non-machine claims route to human review and never auto-block.\n\nEvidence matching uses wildcard semantics: an empty applicability dimension applies to all\nvalues, existing values refine ranking, and only dimensions a claim lists in `restrict` are\nhard filters, so universal claims survive rich contexts. `motif evidence query\n--explain-matching` shows why each claim matched or was excluded. The originality detector\nreports **aesthetic-convergence risk** (generic-pattern concentration with contextual\noriginality signals); it accounts for design-system provenance and product context, requires\na combination of cliche signals for a high band, and does not determine whether a UI was made\nby AI.\n\n## Quick start (no pip)\n\nThe core is dependency-free, so setup is one command. Requirements: Python 3.11+ and `git`.\n\n```bash\ngit clone https://github.com/Suraj787/motif.git motif \u0026\u0026 cd motif\nmake install        # or: bash install.sh\n```\n\n`make install` wires three things (each optional, reversible with `make uninstall`):\n\n1. a `motif` (and `ii`/`oii`) command on your PATH, so you can audit any project from any\n   terminal, with no pip and no build;\n2. a Claude Code skill at `~/.claude/skills/motif`, so you can type `/motif` in Claude Code;\n3. the read-only Motif MCP server registered with Claude Code, so `motif.*` evidence and audit\n   tools are available in any session.\n\nThen:\n\n```bash\nmotif doctor\nmotif evidence query --product-form dashboard --ability colour-vision-deficiency\nmotif evidence evaluate --product-form dashboard --workflow daily-operation ./your-app\n```\n\nPrefer a packaged install instead? `python -m pip install -e .` also gives the `ii`, `oii`,\nand `motif` entry points. Or run in place with no setup at all: `python -m ii doctor`.\n\nThe root [`SKILL.md`](SKILL.md) is the orchestrator (an 18-step workflow with hard rules);\nspecialist skills live in [`skills/`](skills/).\n\n## Repository map\n\n| Area | What's there |\n|------|--------------|\n| `SKILL.md`, `skills/`, `agents/` | Orchestrator, 11 specialist skills, 15 reviewer agents |\n| `product-intelligence/` | Product Context Manifest + sub-models |\n| `design-intelligence/` | Styles, colour, typography, layout, ux-principles, 10 industry packs |\n| `interaction-intelligence/` | Motion + density grammars, state requirements, anti-patterns |\n| `governance/` | Design genome, interaction graph, decision ledger, debt, drift |\n| `registry/`, `scanners/`, `security/`, `connectors/`, `ingestion/` | Secure supply chain (foundation) |\n| `adapters/`, `implementations/`, `compiler/` | Framework adaptation and the controlled installer |\n| `assurance/` | Assurance evidence model (static scans implemented; runtime planned) |\n| `specifications/` | Interface Specification Language (schema + examples) |\n| `interfacebench/` | Production-survival benchmark (15 capabilities, 10-round scenario) |\n| `ii/`, `motif/` | The platform CLI module (`ii`) and the Motif foundation engine |\n| `schemas/` | 25 strict JSON Schemas every record must satisfy |\n| `evals/`, `tests/` | Adversarial judgement + security evaluations; test suite |\n| `docs/` | Research, competitive analysis, architecture, capability matrix, ADRs |\n\n## What v2.0.0 contains\n\n- All six engines have functioning, schema-validated foundations.\n- Design intelligence: 12 styles, 12 layouts, 15 executable UX principles, colour and\n  typography systems, 10 deep industry packs (workflow and risk, not themes).\n- Governance: 2 design genomes, a 31-node / 40-edge interaction graph with six deliberately\n  seeded gaps that the queries surface, a decision ledger, and an explainable debt analyzer.\n- Honesty discipline: the Product Context Manifest separates verified facts from inference\n  and assumptions; recommendations carry confidence levels; performance is never reported as\n  measured without measurement.\n- `make check`: foundation self-check (75) plus the `ii` self-check (20), engine-data and\n  graph validation, and a secret scan.\n\nPlanned next (v0.3.0): live `ii compile plan/apply`, workflow simulation (Playwright),\nvisual-regression assurance, drift trend tracking, external provider imports, and the\nautomated InterfaceBench runner. See the [capability matrix](docs/capability-matrix.md) and\n[`docs/product/roadmap.md`](docs/product/roadmap.md).\n\n## Honest limitations\n\n- Live network connectors are declarative; ingestion is offline and proven on fixtures.\n- Accessibility and performance assurance are static estimates plus state completeness, not\n  runtime measurement.\n- The design-intelligence and governance catalogues are representative, not exhaustive.\n- Third-party code can never be guaranteed completely safe; automated accessibility checks\n  are incomplete; AI-generated contributions require human review.\n\n## Licence\n\nOriginal code is [MIT](LICENSE). Third-party sources keep their own licences and\nobligations; public source metadata does not imply redistribution rights. See\n[`LICENSE_POLICY.md`](LICENSE_POLICY.md) and [`THIRD_PARTY_SOURCES.md`](THIRD_PARTY_SOURCES.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuraj787%2Fmotif","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuraj787%2Fmotif","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuraj787%2Fmotif/lists"}