Tools - Refero

Refero MCP gives your agent tools for three research layers:

Styles — visual direction, taste, tokens, typography, spacing, surfaces, imagery, and component feel.
Screens — concrete UI patterns, page structure, copy, states, and product-specific details.
Flows — multi-step journey logic: goals, actions, system responses, friction, and completion states.

For visual design work, start with styles. Use screens for concrete interface decisions. Use flows when the task has a before/after sequence.

Styles

`refero_search_styles`

Search curated design styles using semantic search. Use this first when you need visual direction, brand feel, typography, color, layout, spacing, elevation, surfaces, components, imagery, or design-system inspiration. Parameters

Parameter	Type	Required	Description
`query`	string	yes	A semantic query for aesthetic, domain, audience, product category, or brand direction.
`page`	number	no	Pagination. Default: `1`.
`response_format`	`"md"` \| `"json"`	no	Response format, when supported by your MCP client. Default: `"md"`.

Good queries

editorial monochrome SaaS landing page
premium fintech website with restrained typography
developer tool website with product screenshots
data infrastructure website dark technical style
Attio editorial SaaS typography
Linear changelog dark developer tool

Response shape

{
  "pagination": {
    "count": 10,
    "page": 1,
    "next_page": 2,
    "total_count": 1000,
    "total_pages": 100
  },
  "records": [
    {
      "uuid": "707c2922-e428-4ee4-847c-9791290712d1",
      "title": "Depot",
      "url": "https://depot.dev",
      "platform": "desktop",
      "preview_url": "https://images.refero.design/styles/...",
      "description": "A dark, high-contrast developer-tool landing page..."
    }
  ]
}

Search several visual angles before choosing a direction. Styles are reference ingredients, not templates to copy.

`refero_get_style`

Retrieve full design guidance for one or more style UUIDs. Use this after refero_search_styles. Parameters

Parameter	Type	Required	Description
`style_id`	string	yes*	One style UUID. Use exactly one of `style_id` or `style_ids`.
`style_ids`	string[]	yes*	Multiple style UUIDs. Full styles are large; 3-4 per batch is a practical maximum.
`response_format`	`"md"` \| `"json"`	no	Response format. Default: `"md"`.

What you get

north star / visual thesis
color roles, not just hex values
typography roles and type scale
spacing, radius, shadows, elevation, and surfaces
layout and section rhythm
component treatments and sometimes implementation snippets
imagery, graphics, illustration, or product screenshot guidance
do/don’t rules and agent prompt guidance

Styles currently focus on web marketing and product pages: landing pages, pricing pages, product marketing sites, editorial brand sites, and SaaS websites. They are still useful for product UI work, but use screens and flows for product-specific behavior.

Screens

`refero_search_screens`

Search real UI screens for concrete interface decisions: page structure, component choices, content hierarchy, states, copy, and product patterns. Parameters

Parameter	Type	Required	Description
`query`	string	yes	Search by screen type, UI element, pattern, state, company, or on-screen text.
`platform`	`"web"` \| `"ios"`	yes	Platform filter.
`page`	number	no	Pagination. Default: `1`.
`response_format`	`"md"` \| `"json"`	no	Response format, when supported by your MCP client. Default: `"md"`.

Good queries

pricing page annual monthly toggle
feature comparison table
dashboard empty state
billing settings cancellation modal
2FA setup recovery codes
data table filters

Response shape

{
  "pagination": {
    "count": 10,
    "page": 1,
    "next_page": 2,
    "total_count": 1050,
    "total_pages": 105
  },
  "records": [
    {
      "uuid": "20c61554-3c93-4848-aeb1-e3c1ba62d99d",
      "platform": "web",
      "thumbnail_url": "https://images.refero.design/screenshots/...",
      "page_url": "https://lu.ma/pricing",
      "refero_url": "https://refero.design/pages/20c61554-...",
      "site": {
        "id": 400,
        "domain": "lu.ma",
        "name": "Luma",
        "description": "Luma is all you need to host a memorable event.",
        "categories": ["Social Networking", "Entertainment"]
      },
      "page_types": ["Paywall & Subscription"],
      "ux_patterns": ["Product Features"],
      "ui_elements": ["Table", "Button", "Switch & Toggle"],
      "hex_colors": ["0x1B1C1D", "0xDB3464"],
      "content": {
        "description": "The screen presents a pricing page..."
      }
    }
  ]
}

Use page for pagination. Do not pass limit, offset, image_size, or include_similar to search tools.

`refero_get_screen`

Get full metadata and descriptions for one or more screens by UUID. Parameters

Parameter	Type	Required	Description
`screen_id`	string	yes*	One screen UUID from `refero_search_screens`.
`screen_ids`	string[]	yes*	Multiple screen UUIDs. Use exactly one of `screen_id` or `screen_ids`.
`response_format`	`"md"` \| `"json"`	no	Response format. Default: `"md"`.

Response shape

{
  "uuid": "20c61554-3c93-4848-aeb1-e3c1ba62d99d",
  "platform": "web",
  "thumbnail_url": "https://images.refero.design/screenshots/...",
  "preview_url": "https://images.refero.design/screenshots/...",
  "page_url": "https://lu.ma/pricing",
  "refero_url": "https://refero.design/pages/20c61554-...",
  "site": {
    "domain": "lu.ma",
    "name": "Luma",
    "description": "Luma is all you need to host a memorable event."
  },
  "fonts": ["San Francisco"],
  "page_types": ["Paywall & Subscription"],
  "ux_patterns": ["Product Features"],
  "ui_elements": ["Table", "Button", "Switch & Toggle"],
  "content": {
    "description": "Detailed prose about the screen...",
    "layout": "How elements are arranged...",
    "functions": "What users can do..."
  }
}

`refero_get_similar_screens`

Find visually and functionally similar screens for a screen UUID. Parameters

Parameter	Type	Required	Description
`screen_id`	string	yes	Screen UUID from search or detail results.
`limit`	number	no	Number of similar screens. Range: 1-20. Default: 10.
`response_format`	`"md"` \| `"json"`	no	Response format. Default: `"md"`.

Use this when one result is especially relevant and you want comparable examples quickly.

`refero_get_screen_image`

Return raw screenshot image content for a screen UUID. Parameters

Parameter	Type	Required	Description
`screen_id`	string	yes	Screen UUID from search or detail results.
`image_size`	`"thumbnail"` \| `"full"`	no	Default: `"thumbnail"`.

Use this only when text metadata is not enough and the agent needs to visually inspect the exact screenshot.

Flows

`refero_search_flows`

Search multi-step journeys: onboarding, checkout, signup, cancellation, upgrade, account deletion, password reset, and settings changes. Parameters

Parameter	Type	Required	Description
`query`	string	yes	Search by task, journey, company, industry, or key step.
`platform`	`"web"` \| `"ios"`	yes	Platform filter.
`page`	number	no	Pagination. Default: `1`.
`response_format`	`"md"` \| `"json"`	no	Response format, when supported by your MCP client. Default: `"md"`.

Good queries

signup onboarding
checkout with promo code
subscription cancellation with retention offer
account deletion feedback
password reset 2FA

Response shape

{
  "pagination": {
    "count": 10,
    "page": 1,
    "next_page": 2,
    "total_count": 13,
    "total_pages": 2
  },
  "records": [
    {
      "id": 11201,
      "platform": "web",
      "name": "Subscription cancellation and feedback path",
      "screens_count": 9,
      "refero_url": "https://refero.design/flows/11201",
      "description": "Happy path: A signed-in user opens Account > Subscription & Billing...",
      "problem": "User goal: cancel an existing paid subscription...",
      "steps": [
        "Account subscription overview",
        "Subscription detail",
        "Cancellation confirmation interstitial"
      ],
      "site": {
        "id": 868,
        "domain": "washingtonpost.com",
        "name": "The Washington Post",
        "categories": ["Magazines & Newspapers", "News"]
      }
    }
  ]
}

`refero_get_flow`

Get the complete flow with all steps, goals, actions, system responses, screen metadata, and related search queries. Parameters

Parameter	Type	Required	Description
`flow_id`	number	yes*	One flow ID from `refero_search_flows`.
`flow_ids`	number[]	yes*	Multiple flow IDs. Use exactly one of `flow_id` or `flow_ids`.
`response_format`	`"md"` \| `"json"`	no	Response format. Default: `"md"`.

Response shape

{
  "id": 11201,
  "platform": "web",
  "name": "Subscription cancellation and feedback path",
  "screens_count": 9,
  "site": {
    "domain": "washingtonpost.com",
    "name": "The Washington Post"
  },
  "steps": [
    {
      "name": "Account subscription overview",
      "screen_id": "76822c91-6db9-42f4-a1a4-b8f30f2a7ca7",
      "refero_url": "https://refero.design/pages/76822c91-...",
      "thumbnail_url": "https://images.refero.design/screenshots/...",
      "goal": "See current subscription status...",
      "action": "User reviews the subscription card...",
      "system_response": "Navigates to the subscription detail view...",
      "page_types": ["Settings"],
      "ux_patterns": ["Billing & Plans"],
      "ui_elements": ["Button", "Tabs", "Navigation Bar"],
      "content": {
        "description": "Detailed screen description...",
        "layout": "Layout details...",
        "functions": "Available actions..."
      }
    }
  ],
  "related_queries": [
    "manage subscription settings",
    "subscription cancellation retention offer design"
  ]
}

Common mistakes

Do not use old _tool suffixed names.
Do not call get_design_guidance; use styles, screens, and flows.
Do not pass image_size or include_similar to refero_get_screen.
Do not use numeric screen IDs. Screens use UUIDs.
Do not use screens as the main source for visual taste when styles are available.
Do not copy a single style directly.

Data Model

Field reference for styles, screens, and flows.

Examples

Simple research workflows using current tools.

Refero Skill

Research-first design methodology for agents.

​Styles

​refero_search_styles

​refero_get_style

​Screens

​refero_search_screens

​refero_get_screen

​refero_get_similar_screens

​refero_get_screen_image

​Flows

​refero_search_flows

​refero_get_flow

​Common mistakes

​Next

Data Model

Examples

Refero Skill

Styles

`refero_search_styles`

`refero_get_style`

Screens

`refero_search_screens`

`refero_get_screen`

`refero_get_similar_screens`

`refero_get_screen_image`

Flows

`refero_search_flows`

`refero_get_flow`

Common mistakes

Next