https://github.com/suraj787/motif
Open-source interaction-design intelligence for AI coding agents - securely discover, select, adapt and validate UI motion, effects and interaction patterns.
https://github.com/suraj787/motif
accessibility agent-skills application-security claude-code frontend interaction-design motion-design open-source react svelte ui-animation vue web-performance
Last synced: 1 day ago
JSON representation
Open-source interaction-design intelligence for AI coding agents - securely discover, select, adapt and validate UI motion, effects and interaction patterns.
- Host: GitHub
- URL: https://github.com/suraj787/motif
- Owner: Suraj787
- License: other
- Created: 2026-06-27T10:13:24.000Z (3 days ago)
- Default Branch: main
- Last Pushed: 2026-06-27T10:55:55.000Z (2 days ago)
- Last Synced: 2026-06-27T12:09:36.010Z (2 days ago)
- Topics: accessibility, agent-skills, application-security, claude-code, frontend, interaction-design, motion-design, open-source, react, svelte, ui-animation, vue, web-performance
- Language: Python
- Size: 488 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Motif
**Design judgment, interface engineering, assurance, and governance for AI coding agents.**
AI coding agents already know how to generate interface code. They do not reliably know
what should be built, why a design choice belongs, whether a pattern fits the user and
workflow, whether the output is generic, whether it is accessible, whether it is fast on
real devices, whether third-party code is safe and legally reusable, whether it fits the
existing design language, or whether the codebase stays coherent after many changes.
Motif is the intelligence and governance layer that answers those
questions.
[](https://github.com/Suraj787/motif/actions)
Licence: MIT. Status: v3.0.0 "Evidence-Grounded Interface Engineering" (interaction core shipped as v1.0.0; intelligence platform as v2.0.0)
> Defining principle: first determine what the user needs to understand, feel, decide, or
> accomplish, then choose the least complex interface and interaction that achieves it.
> Visual novelty never outranks usability, accessibility, security, performance, or
> maintainability.
## Honesty first
This README distinguishes what is **implemented**, **experimental**, and **planned**. See
the full [capability matrix](docs/capability-matrix.md). Nothing marked planned is claimed
to work. Anything you can run is covered by `make check`.
## The six engines
```
Product intent
> Product Intelligence (context manifest: facts vs inference vs assumption)
> Design Intelligence (styles, colour, typography, layout, ux-principles, industry packs)
> Interaction Intelligence (patterns before effects, motion + density grammars, state completeness)
> Implementation (framework detection, controlled install, rollback, provenance)
> Assurance (security static scans, evidence model; runtime checks planned)
> Governance and Learning (design genome, interaction graph, originality, decisions, debt, drift)
```
The Interaction Intelligence Engine and Secure Component Supply Chain are the validated
**Motif** interaction foundation (originally the v1.0 core) (90 web-verified sources, 64
components, 30 effects, 28 patterns, 14 recipes, 5 scanners, controlled installer). Vue and
Frappe-Vue are first-class.
## What you can run today (implemented)
```bash
ii inspect # detect the target project's framework + conventions
ii model-product # scaffold a Product Context Manifest
ii context validate # validate manifests (uncertainty stays explicit)
ii genome validate|explain|diff # Product Design Genome
ii graph validate|query # Interaction Specification Graph (surfaces real gaps)
ii originality audit [--product-form ...] # aesthetic-convergence risk over real source
ii states matrix|validate|inspect # State Completeness Engine
ii motion validate ; ii density validate
ii debt calculate # explainable Interface Debt Score
ii decision create|list # design decision ledger
ii source scan # 5 security scanners (foundation)
ii component plan-install --target # controlled install plan
ii search "" ; ii rank # registry search + transparent ranking
ii validate ; ii doctor # validate all engine data; health check
make check # full local gate (mirrors CI)
```
`motif` is the primary command; `ii` and `oii` are aliases. All three expose the full platform.
### Motif Live (v3, runtime and governance)
```bash
motif init # first run: inspect, create .motif/, first audit
motif improve --target ./app --goal "Make project risk easier to scan"
motif findings audit|list # unified findings with evidence + lifecycle
motif policy init|check # policy as code (blocking thresholds)
motif memory add --type rejected-approach --content "..." # auditable project memory
motif atlas build # static public catalogue from the registry
motif system extract # extract the project's design system
motif guard branch --base main # Guardian: scan a diff against policy
motif mcp serve # MCP server (read tools + guarded writes)
motif studio # local read-only Studio viewer
motif bench --target ./app # InterfaceBench automated measures
```
The browser-runtime surfaces (Visual Twin rendering, Playwright assurance, live preview,
semantic visual diff, interactive apply) are marked experimental and never fake output.
See the [capability matrix](docs/capability-matrix.md) and
[v3 architecture](docs/architecture/motif-v3-live-architecture.md).
### Evidence-grounded runtime (v3.0.0)
```bash
motif evidence query --product-form dashboard --purpose monitor --ability colour-vision-deficiency --risk financial:3
motif evidence evaluate --product-form dashboard --workflow daily-operation # applicable claims + findings -> evidence-backed enforcement
motif evidence explain claim-status-colour-001 # source, tier, limitations, validation
motif evidence check-myth "three click rule"
motif repair golden --target evals/fixtures/sample-vue-app --route /projects # detect -> evidence -> worktree fix -> verify -> exact rollback -> report
motif doctor --browser # browser runtime status (optional motif[browser] extra)
```
A version-controlled UX Evidence Graph (110 Tier 1-3 claims with sources, limitations, and
validation) grounds the audit-and-repair decisions. Browser capture/validation is an
optional extra and reports `not-executed` without a runtime, never faked.
An applicable claim is not a finding. `motif evidence query` returns applicable claims and
the normative requirements to evaluate (status `needs_evaluation`), never evidence-free
blocking. `motif evidence evaluate` correlates detector findings to claims and produces
evidence-backed enforcement: a claim blocks only when it is an applicable normative,
machine-detectable claim with a correlated finding at sufficient confidence and no unresolved
contradiction; non-machine claims route to human review and never auto-block.
Evidence matching uses wildcard semantics: an empty applicability dimension applies to all
values, existing values refine ranking, and only dimensions a claim lists in `restrict` are
hard filters, so universal claims survive rich contexts. `motif evidence query
--explain-matching` shows why each claim matched or was excluded. The originality detector
reports **aesthetic-convergence risk** (generic-pattern concentration with contextual
originality signals); it accounts for design-system provenance and product context, requires
a combination of cliche signals for a high band, and does not determine whether a UI was made
by AI.
## Quick start (no pip)
The core is dependency-free, so setup is one command. Requirements: Python 3.11+ and `git`.
```bash
git clone https://github.com/Suraj787/motif.git motif && cd motif
make install # or: bash install.sh
```
`make install` wires three things (each optional, reversible with `make uninstall`):
1. a `motif` (and `ii`/`oii`) command on your PATH, so you can audit any project from any
terminal, with no pip and no build;
2. a Claude Code skill at `~/.claude/skills/motif`, so you can type `/motif` in Claude Code;
3. the read-only Motif MCP server registered with Claude Code, so `motif.*` evidence and audit
tools are available in any session.
Then:
```bash
motif doctor
motif evidence query --product-form dashboard --ability colour-vision-deficiency
motif evidence evaluate --product-form dashboard --workflow daily-operation ./your-app
```
Prefer a packaged install instead? `python -m pip install -e .` also gives the `ii`, `oii`,
and `motif` entry points. Or run in place with no setup at all: `python -m ii doctor`.
The root [`SKILL.md`](SKILL.md) is the orchestrator (an 18-step workflow with hard rules);
specialist skills live in [`skills/`](skills/).
## Repository map
| Area | What's there |
|------|--------------|
| `SKILL.md`, `skills/`, `agents/` | Orchestrator, 11 specialist skills, 15 reviewer agents |
| `product-intelligence/` | Product Context Manifest + sub-models |
| `design-intelligence/` | Styles, colour, typography, layout, ux-principles, 10 industry packs |
| `interaction-intelligence/` | Motion + density grammars, state requirements, anti-patterns |
| `governance/` | Design genome, interaction graph, decision ledger, debt, drift |
| `registry/`, `scanners/`, `security/`, `connectors/`, `ingestion/` | Secure supply chain (foundation) |
| `adapters/`, `implementations/`, `compiler/` | Framework adaptation and the controlled installer |
| `assurance/` | Assurance evidence model (static scans implemented; runtime planned) |
| `specifications/` | Interface Specification Language (schema + examples) |
| `interfacebench/` | Production-survival benchmark (15 capabilities, 10-round scenario) |
| `ii/`, `motif/` | The platform CLI module (`ii`) and the Motif foundation engine |
| `schemas/` | 25 strict JSON Schemas every record must satisfy |
| `evals/`, `tests/` | Adversarial judgement + security evaluations; test suite |
| `docs/` | Research, competitive analysis, architecture, capability matrix, ADRs |
## What v2.0.0 contains
- All six engines have functioning, schema-validated foundations.
- Design intelligence: 12 styles, 12 layouts, 15 executable UX principles, colour and
typography systems, 10 deep industry packs (workflow and risk, not themes).
- Governance: 2 design genomes, a 31-node / 40-edge interaction graph with six deliberately
seeded gaps that the queries surface, a decision ledger, and an explainable debt analyzer.
- Honesty discipline: the Product Context Manifest separates verified facts from inference
and assumptions; recommendations carry confidence levels; performance is never reported as
measured without measurement.
- `make check`: foundation self-check (75) plus the `ii` self-check (20), engine-data and
graph validation, and a secret scan.
Planned next (v0.3.0): live `ii compile plan/apply`, workflow simulation (Playwright),
visual-regression assurance, drift trend tracking, external provider imports, and the
automated InterfaceBench runner. See the [capability matrix](docs/capability-matrix.md) and
[`docs/product/roadmap.md`](docs/product/roadmap.md).
## Honest limitations
- Live network connectors are declarative; ingestion is offline and proven on fixtures.
- Accessibility and performance assurance are static estimates plus state completeness, not
runtime measurement.
- The design-intelligence and governance catalogues are representative, not exhaustive.
- Third-party code can never be guaranteed completely safe; automated accessibility checks
are incomplete; AI-generated contributions require human review.
## Licence
Original code is [MIT](LICENSE). Third-party sources keep their own licences and
obligations; public source metadata does not imply redistribution rights. See
[`LICENSE_POLICY.md`](LICENSE_POLICY.md) and [`THIRD_PARTY_SOURCES.md`](THIRD_PARTY_SOURCES.md).