Refero Design Skill and MCP

The Refero skill is designed to enforce a research-first approach to AI design work. It provides:

• Mandatory Research: Forces visual style research before implementation.
• Pattern Extraction: Extracts concrete patterns and locks references before coding.
• Bundled Guidance: Applies specific guidance for typography, color, spacing, motion, icons, and copywriting.
• Evidence-Based Decisions: Ties design decisions to real-world evidence (150,000+ app screens and 6,000+ user flows) instead of generic AI defaults.
• Visual Validation: Checks substantial visual work against the selected direction before handoff.

To write effective copy, follow the hierarchy of Clarity > Respect > Character.

• Clarity: The highest priority. Without it, the copy fails to communicate.
• Respect: The second priority. Avoid irritating the user with fluff or ambiguity.
• Character: The final layer. Use this to make the copy memorable, but never at the expense of clarity.

Core Belief: Copy is an interface between a person and a next step. If text does not help someone understand, choose, or act, it hurts the design.

Identify and avoid common amateur or AI-generated design mistakes:

• Excessive scales: Using more than 8 distinct font sizes.
• Low contrast: Gray text on gray backgrounds.
• Flattened hierarchy: Using bold text in body paragraphs or too many font weights.
• Poor formatting: Centered paragraphs (except for marketing copy) or ALL CAPS without increased letter-spacing (tracking).
• Inconsistency: Random gaps or spacing between elements.

The Visual Workflow is a specialized reference used when a task requires visual exploration, generated mockups, bitmap assets, or post-build visual QA.

When to use this workflow:

• Visual exploration or generating mockups.
• Creating bitmap assets (hero imagery, textures, etc.).
• Performing post-build visual QA.

When to use the main Refero workflow instead:

• Researching styles for taste.
• Researching screens for product patterns.
• Researching flows for user journeys.

Motion in product UI should only be used if it serves one of these three functional purposes. If an animation does not fulfill at least one, it should be removed to avoid noise.

1. Feedback: Confirms user actions (e.g., "I pressed this and it worked").
2. Continuity: Explains spatial relationships (e.g., "Here is where the element came from and where it went").
3. Hierarchy: Directs user attention (e.g., "Look here, this is important").

Refero provides three distinct research layers. Choosing the right one depends on the nature of your design task:

1. Styles: Use for visual direction, brand direction, and "look and feel". This includes typography, color palettes, layout/composition, spacing, and elevation. Note: Styles currently focus on web marketing/product pages (landing pages, SaaS sites) rather than in-app dashboards or iOS screens.
2. Screens: Use for concrete UI patterns, specific screen types (dashboards, settings, modals, tables), page layouts, content hierarchy, and form/state examples.
3. Flows: Use for multi-step user journeys and sequences, such as onboarding, signup, checkout, or subscription management.

If a piece of copy feels empty or ineffective, ensure it answers these six components:

1. Context: Where is the user right now?
2. Job to be done: What are they trying to accomplish?
3. Solution: What do you offer?
4. Outcome: What changes for them?
5. Conditions: Limits, tradeoffs, requirements
6. Next step: What should they do now?

Guide the user's eye using a visual weight stack. Test your hierarchy by squinting at the interface to see if 3 clear levels are visible.

Hierarchy Order (Highest to Lowest Impact):

1. Size (Biggest impact)
2. Weight (Bold vs regular)
3. Color (Dark vs gray vs muted)
4. Case (Caps for labels)
5. Spacing (Margins for grouping)
6. Style (Italics for rare emphasis)

Use the Motion Pyramid to prioritize animation types from essential to risky. Start with Level 1 and only add higher levels when functionally justified.

• Level 1: Micro Feedback (Essential): Focuses on responsiveness for high-frequency interactions like hover, press, focus states, toggles, and checkboxes.
• Level 2: State Transitions: Handles movement instead of "teleportation" for elements like accordions, tabs, modals, drawers, and popovers.
• Level 3: Layout Continuity: Maintains cognitive economy during resizing, repositioning, reordering, or filtering (e.g., drag-and-drop, list item changes).
• Level 4: Expressive (Risky): Reserved for marketing, onboarding, or hero animations. Use sparingly in product UI as it easily becomes noise.

When building color scales, avoid HSL because it does not represent perceptual brightness consistently (e.g., a 50% lightness yellow looks much brighter than a 50% lightness blue).

Use OKLCH (or LCH) to ensure that steps in a palette (e.g., 50→950) look visually even.

Workflow:

1. Generate and adjust palettes using OKLCH.
2. Store production values as hex.
3. Use OKLCH logic as the source of truth for scaling.

For MVPs, you may use curated palettes like Tailwind, Radix, or Open Color, but understand that they rely on these perceptual principles.

/* OKLCH example */
--primary-500: oklch(0.55 0.2 250);  /* Base */
--primary-600: oklch(0.48 0.2 250);  /* Hover */
--primary-700: oklch(0.41 0.2 250);  /* Active */