motionprompts

Find the components that best fit a natural-language brief (e.g. "un hero elegante para una marca de lujo", "cartas apiladas al hacer scroll") or a name/alias. Returns a ranked, compact list with a `why` for each hit. Combine the free-text `query` with facet filters to narrow. Then call get_component on the chosen slug. Leave `query` empty to browse purely by filters.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text brief or component name/alias. Spanish or English; accent-insensitive.",
      "type": "string"
    },
    "mood": {
      "description": "Aesthetic filter. One of: minimal, elegant, luxury, editorial, bold, playful, corporate, retro, futuristic, experimental, cinematic, brutalist, organic, technical",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "minimal",
          "elegant",
          "luxury",
          "editorial",
          "bold",
          "playful",
          "corporate",
          "retro",
          "futuristic",
          "experimental",
          "cinematic",
          "brutalist",
          "organic",
          "technical"
        ]
      }
    },
    "useCase": {
      "description": "Page-role filter. One of: hero, preloader, page-transition, navigation, footer, gallery, slider, card-deck, scroll-story, image-reveal, text-reveal, hover-interaction, cursor-effect, logo, background, product-showcase, marquee, team-section, cta, contact",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "hero",
          "preloader",
          "page-transition",
          "navigation",
          "footer",
          "gallery",
          "slider",
          "card-deck",
          "scroll-story",
          "image-reveal",
          "text-reveal",
          "hover-interaction",
          "cursor-effect",
          "logo",
          "background",
          "product-showcase",
          "marquee",
          "team-section",
          "cta",
          "contact"
        ]
      }
    },
    "level": {
      "description": "page (owns the whole page/scroll) | section (a block) | widget (small embeddable).",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "page",
          "section",
          "widget"
        ]
      }
    },
    "category": {
      "description": "Animation-family filter (e.g. scroll, cards, menu, 3d-webgl).",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deps": {
      "description": "Require these runtime deps (e.g. [\"three\"], [\"lenis\"]). AND semantics.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "maxPerfCost": {
      "description": "Cap runtime weight: light | medium | heavy.",
      "type": "string",
      "enum": [
        "light",
        "medium",
        "heavy"
      ]
    },
    "mobileSafe": {
      "description": "If true, only components that degrade well on touch/small screens.",
      "type": "boolean"
    },
    "limit": {
      "description": "Max results (default 12).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch one component by slug. `include` controls the payload: 'meta' (full catalog record), 'preview' (thumbnail + live demo URL), 'prompt' (a self-contained brief to REBUILD it faithfully), 'source' (the actual index.html/styles.css/script.js to copy, plus an integration note). Default: meta + preview + prompt. Add 'source' when you want the real code.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Component slug, e.g. \"brandappart-sticky-cards\"."
    },
    "include": {
      "description": "Which payloads to return. Default: [\"meta\",\"preview\",\"prompt\"].",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "meta",
          "preview",
          "prompt",
          "source"
        ]
      }
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return the filter vocabulary (mood, useCase, level, perfCost, category, deps) with how many components carry each value. Call this first to learn the exact values search_components accepts.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Browse the whole catalog as a compact list (slug, title, useWhen, mood, useCase, level, perfCost). Use for an overview or when a brief is vague; use search_components when you have a specific brief.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Max items (default: all).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "description": "Skip N items (pagination).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The 8 motion systems of the library: token sets (ease/duration/stagger/lenis) derived from the measured inventory, not invented. Use this FIRST when composing a page: pick one system and render every component's prompt with it so the page moves coherently.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full token set of a motion system plus the components that are native to it.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "System name, e.g. scrub-lagged."
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Filters by the CAPA-1 motion block (trigger, libs, complexity, motion system) rather than by prose. Prefer this over search_components when composing a page: `category` describes how a component LOOKS, `trigger`/`cluster` describe how it MOVES, and they disagree — the `slider` label alone splits across 3 opposite physics.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string"
    },
    "trigger": {
      "type": "string",
      "enum": [
        "scroll",
        "hover",
        "click",
        "load",
        "pointer",
        "wheel",
        "drag"
      ]
    },
    "libs": {
      "description": "Todas deben estar presentes.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "complexity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "max_complexity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "motion_system": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Given the slugs you intend to put on ONE page, returns: rule violations (hard, invalidate the page), warnings, the measured budget (JS gzip / assets / scroll corridor), and an ordered init plan — single Lenis instance, CustomEase registration, entry veil first, one ScrollTrigger.refresh() at the end, WebGL loop gating. Every step cites the evidence it comes from.

{
  "type": "object",
  "properties": {
    "slugs": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "motion_system": {
      "type": "string"
    },
    "moving_sections": {
      "description": "Las secciones que DEBEN moverse (plan_page → motion_coverage.must_move), o cuántas son. Con esto el contrato audita la cobertura y te dice si te has quedado corto.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    }
  },
  "required": [
    "slugs"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Qué imagen necesita cada sección, CON QUÉ MODELO se hace y cómo se redacta el prompt. Con la arquitectura y el movimiento resueltos, lo que sigue delatando una página generada son las imágenes: genéricas del sector en vez de específicas de la sección, sin una sola persona, y todas rectángulos con fondo. Esta tool devuelve el enrutado por modelo (personas ≠ objetos ≠ paisaje: no son intercambiables), la receta de transparencia (alfa real de gpt-image-2.5 con `background: transparent`, ya sin magenta), la del retoque con referencia (image-to-image para corregir un detalle sin volver a tirar el dado), la de las hojas de seis recortes por generación, y de dónde salen los logotipos reales (Wikimedia, nunca generados). NO genera imágenes, no usa ninguna clave y no hace ninguna llamada de red: devuelve texto. Llámala DESPUÉS de plan_page y ANTES de escribir un solo prompt de imagen.

{
  "type": "object",
  "properties": {
    "brief": {
      "description": "El mismo brief que le diste a plan_page.",
      "type": "string"
    },
    "archetype": {
      "type": "string"
    },
    "sections": {
      "description": "Las secciones de plan_page, tal cual. Sin esto sólo se devuelven las reglas generales.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "role"
        ]
      }
    },
    "palette": {
      "description": "La paleta ya fijada: las tomas obedecen al diseño, no al revés.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the SECTIONS a page of this kind needs — 10 to 14 of them, each with a role, what it has to accomplish, what content it needs, and whether it should move — plus a motion system and its tokens. It returns NO components on purpose: a page can only be as rich as the list it is composed from, and composing from animation mechanics caps every page at five sections. Ask for mechanics afterwards, one section at a time, with suggest_mechanics. It also names the roles the catalog cannot cover, so you write those from the system tokens instead of adopting the least-bad search hit. An optional `reference` contributes STATIC art direction and biases the motion system — motion is NEVER derived from the reference.

{
  "type": "object",
  "properties": {
    "brief": {
      "type": "string",
      "description": "e.g. 'tostaduría de café de especialidad', 'agencia de software a medida'."
    },
    "archetype": {
      "description": "Fuerza el patrón de arquitectura en vez de detectarlo del brief. Uno de: agency, restaurant, product-brand, saas, portfolio, event, editorial",
      "type": "string",
      "enum": [
        "agency",
        "restaurant",
        "product-brand",
        "saas",
        "portfolio",
        "event",
        "editorial"
      ]
    },
    "reference": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "image": {
          "type": "string"
        },
        "palette": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "type_scale": {
          "type": "string"
        },
        "density": {
          "type": "string"
        },
        "motion_system_hint": {
          "description": "Uno de los 8; sesga la elección.",
          "type": "string"
        }
      }
    }
  },
  "required": [
    "brief"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Given a section role from plan_page and what that section has to do, returns ranked candidate components — filtered first by the catalog facets that actually correspond to the role, then ranked by the free-text need. Prefer this over search_components when building a planned page. Crucially, it can answer that the catalog has NOTHING for a role (counters, progress bars, pricing tables, FAQ accordions, data tables) instead of returning the least-bad hit dressed up as an answer — search_components cannot tell you that, and its top result for 'accordion' is a horizontal image gallery. When the verdict is `none`, write the section from the motion system tokens; that is a legitimate outcome, not a failure.

{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "entry",
        "chrome",
        "hero",
        "proof",
        "thesis",
        "feature",
        "collection",
        "process",
        "signature",
        "context",
        "explainer",
        "people",
        "cta",
        "footer",
        "data",
        "pricing",
        "testimonial",
        "faq",
        "reference"
      ],
      "description": "Section role from plan_page. One of: entry, chrome, hero, proof, thesis, feature, collection, process, signature, context, explainer, people, cta, footer, data, pricing, testimonial, faq, reference"
    },
    "need": {
      "description": "What this section must do, in prose. e.g. 'the roast curve draws itself as you scroll'.",
      "type": "string"
    },
    "motion_system": {
      "description": "The page's system; ranks compatible components first and is echoed back when there is nothing to adopt.",
      "type": "string"
    },
    "limit": {
      "description": "Max candidates (default 5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "avoid": {
      "description": "Slugs to exclude — pass everything you already used on OTHER pages. Wide roles offer 100+ candidates whose top scores are statistically tied, so without this you will keep adopting the same handful. NOTE: `avoid` is for not repeating yourself, NOT for animating less — if you drop the #1 because it is taken, take the #2; never leave the section still.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "adopted": {
      "description": "What you have ALREADY adopted on THIS page. Candidates that would invalidate the page alongside them come back with `composes_with_adopted: false`, the reason in `collision`, and sorted last. Without this the tool is blind to the page you are building and the clash only surfaces at get_integration_contract, after you wrote the code.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "role"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The twin of suggest_mechanics for the family that does not fill a section slot: smooth scroll, the shaped edge BETWEEN two stacked sections, a background that runs behind the whole page, a custom cursor, route transitions. These were unreachable from the planner because the whole model assumed a mechanic occupies one slot in `sections` — which is why a page could be planned end to end and still butt every section together with a straight line. A treatment does NOT consume a section and does NOT count toward motion_coverage; it adds on top. Some kinds are decisions rather than components (`scroll-suave`) and come back with verdict `not-a-component` instead of a fake candidate list. Still pass whatever you adopt to get_integration_contract: treatments compete for the same capabilities (scroll owner, document height) as any other component.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "scroll-suave",
        "frontera-de-seccion",
        "fondo-continuo",
        "cursor",
        "transicion-de-ruta"
      ],
      "description": "Treatment kind. One of: scroll-suave, frontera-de-seccion, fondo-continuo, cursor, transicion-de-ruta"
    },
    "need": {
      "description": "What it has to do, in prose. Only reorders within the kind's pool.",
      "type": "string"
    },
    "motion_system": {
      "description": "The page's system; echoed back when there is nothing to adopt.",
      "type": "string"
    },
    "limit": {
      "description": "Max candidates (default 5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "avoid": {
      "description": "Slugs to exclude.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "kind"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

THE way to get a build prompt. Returns three blocks: (a) the standalone prompt VERBATIM, untouched; (b) the tokens of the requested motion system; (c) an explicit instruction telling you to adapt (a) to (b) YOURSELF, preserving arithmetic relationships — if a duration holds up a sum, a chained sequence or a ScrollTrigger `end`, recompute the whole set, never a lone value. Replaces render_prompt, which substituted mechanically and produced prompts whose prose contradicted their code (11/30 in judged evaluation). See DECISIONS.md D15 and D18.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "motion_system": {
      "description": "Default: the component's native system.",
      "type": "string"
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

DEPRECATED in favour of get_component_prompt. Mechanical substitution does not fit this corpus: the prompts narrate their own numbers in prose, so replacing only the code values makes prose and code specify different components (judged 11/30). Coverage is deliberately narrow: 164 of 219 components have ZERO substitutable values because their prompts narrate their own numbers in prose ('over 4s', 'durations are 1'), and substituting those would make prose and code contradict each other. For those components this returns the prompt unchanged. See DECISIONS.md D15. Returns the component's build prompt with its motion tokens (ease/duration/stagger) replaced by the chosen motion system's values, so several components share one timing language. Values that are STRUCTURAL to the effect (elastic overshoot, loop cadence, scrub linearity, shader/physics constants) are never substituted — they come back listed under 'Valores no parametrizables'. Omit `system` to use the component's native one.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Component slug."
    },
    "system": {
      "description": "Motion system name. Default: the component's native system.",
      "type": "string"
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}